> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ukrgsm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP API

> Створюйте REST API інструменти, які ваш ШІ-агент може викликати під час розмов для інтеграції із зовнішніми системами.

Інструменти HTTP API дозволяють прикріпити виклики зовнішнього REST API безпосередньо до вузлів сценарію, даючи голосовим агентам змогу звертатись до будь-якої внутрішньої чи зовнішньої системи під час живої розмови — на розсуд LLM і за вашими промптами. Це працює подібно до function calling на будь-якій агентній платформі й повністю налаштовується під ваші потреби.

## Що таке інструмент HTTP API

Інструмент HTTP API — це визначення REST API, яке LLM може викликати під час виконання.

**Типові сценарії використання:**

* виклик власних ендпоінтів бекенду;
* запуск автоматизацій n8n;
* синхронізація даних із CRM;
* отримання даних із зовнішніх API (погода, ціни, наявність тощо);
* запис, оновлення чи читання даних через REST API.

**LLM вирішує:**

* який інструмент викликати;
* коли його викликати;
* які параметри надіслати.

**На основі:**

* ваших промптів: інструкцій на рівні вузла простою мовою (українською чи будь-якою іншою);
* назви інструмента;
* опису інструмента;
* визначень параметрів.

<br />

<div style={{ borderBottom: '2px solid #e5e5e5', margin: '20px 0' }} />

## Визначення інструмента HTTP API

### 1. Назва інструмента

* Має бути чіткою й орієнтованою на дію.

* **Приклади:** `capture_lead_interest`, `fetch_weather`, `create_crm_contact` тощо.

### 2. Опис інструмента

* Надзвичайно важливий.
* Саме за ним LLM вирішує, **коли** використовувати інструмент.
* Пишіть просто й однозначно.

**Погано:**
"API для збору даних"

**Добре:**
"Цей інструмент фіксує зацікавленість. Використовуй його, коли користувач явно виражає інтерес до продукту або хоче, щоб з ним зв'язались."

<img src="https://mintlify.s3.us-west-1.amazonaws.com/ukr-gsm/images/tool%20description.png" alt="Приклад опису інструмента" />

### 3. Налаштування ендпоінта

* Повний URL (**обов'язково з `http://` або `https://`**).
* Підтримуються методи **REST**.

<Note>Типова помилка: забути `https://` в URL.</Note>

<br />

<div style={{ borderBottom: '2px solid #e5e5e5', margin: '20px 0' }} />

### 4. Автентифікація й заголовки

* Додайте власну автентифікацію.
* Додайте власні заголовки.
* Працює як із внутрішніми сервісами, так і зі сторонніми API.

<br />

<div style={{ borderBottom: '2px solid #e5e5e5', margin: '20px 0' }} />

### 5. Параметри

Кожен параметр повинен мати:

* назву;
* тип;
* опис;
* позначку обов'язковості.

**Опис параметра важливіший за тип.**

Рекомендації:

* Де можливо, починайте з рядкових (`string`) параметрів.
* Пишіть явно, що саме означає значення.
* Позначайте як обов'язкові лише справді необхідні поля.

Приклад:

* interest (string):
  "Встановити true, якщо користувач явно виявляє намір купити або хоче, щоб з ним зв'язались. Інакше false."

<img src="https://mintlify.s3.us-west-1.amazonaws.com/ukr-gsm/images/tool%20params.png" alt="Приклад параметра" />

<br />

<div style={{ borderBottom: '2px solid #e5e5e5', margin: '20px 0' }} />

## Прикріплення інструментів до вузлів сценарію

* До одного вузла можна прикріпити **кілька інструментів**.
* Усі створені вами інструменти доступні для вибору у вузлі.
* Інструменти можна викликати лише тоді, коли вони прикріплені до вузла.
* LLM сама вирішує, який з них викликати.

У вузлі спрямовуйте LLM **простими інструкціями**.

Приклад:

"Якщо користувач виявляє інтерес поговорити з відділом продажів або хоче, щоб йому передзвонили, одразу виклич інструмент capture\_lead\_interest і встанови interest у true."

Ця інструкція часто є вирішальним фактором для коректного використання інструмента.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/ukr-gsm/images/tool%20attachment.png" alt="Приклад прикріплення" />

<br />

<div style={{ borderBottom: '2px solid #e5e5e5', margin: '20px 0' }} />

## Логіка виклику інструмента (як міркує LLM)

LLM враховує:

* висловлений намір користувача;
* інструкції промпту вузла;
* назву й опис інструмента;
* описи параметрів.

Якщо все це чітко узгоджується, інструмент викликається автоматично.

Погана назва чи розпливчастий опис призводять до:

* пропущених викликів інструмента;
* неправильних параметрів;
* вигаданих значень.

<br />

<div style={{ borderBottom: '2px solid #e5e5e5', margin: '20px 0' }} />

## Ключові найкращі практики

* Давайте інструментам чіткі назви.
* Пишіть детальні, орієнтовані на дію описи.
* Спочатку тримайте параметри простими.
* Завжди вказуйте http/https в URL.
* Використовуйте прості інструкції у вузлі.
* Прикріплюйте до кожного вузла лише релевантні інструменти.

**Чітко визначені інструменти + зрозумілі промпти = надійні голосові агенти продакшн-рівня.**