Кастомные инструменты

Кастомные инструменты агента

Дайте агенту вызывать ваш HTTP-вебхук как инструмент прямо во время разговора: проверить статус заказа, найти запись, создать заявку, дёрнуть вашу систему. Вы описываете инструмент (имя, параметры, URL), агент сам решает, когда его вызвать, — платформа отправляет запрос на ваш сервер и возвращает ответ агенту в диалог.

Доступно на тарифах Бизнес и Про. Настраивается в кабинете, в редакторе проекта.

Как настроить

  1. Откройте проект → вкладка «Движок агента» → блок «Кастомные инструменты».
  2. Нажмите «Добавить инструмент» и заполните:
    • Имя — латиницей, как имя функции (get_order_status). По нему модель вызывает инструмент.
    • Описание — когда и зачем вызывать. Чем точнее, тем правильнее агент выберет момент.
    • Параметры — список аргументов: имя, тип (string/number/integer/boolean), описание, обязательность. Их значения агент извлекает из разговора.
    • Метод и URL — POST (по умолчанию) или GET и адрес вашего вебхука (https://…).
  3. Сохраните проект.

Как это работает

Когда по ходу диалога агент решает, что инструмент нужен, платформа отправляет на ваш URL запрос с аргументами, дожидается ответа и передаёт его агенту как результат инструмента — агент продолжает разговор уже с этими данными.

Запрос (для POST — JSON в теле; для GET — те же поля в query-параметрах):

POST https://your-backend.com/order-status
Content-Type: application/json
 
{ "order_id": "A-2045" }

Ответ — любой текст или JSON (200 OK). Его получит агент:

{ "status": "в пути", "eta": "завтра до 18:00" }

Агент озвучит смысл ответа: «Ваш заказ в пути, доставим завтра до 18:00».

Лимиты и поведение

ПараметрЗначение
Инструментов на проектдо 10
Таймаут запроса~8 секунд (голос не ждёт долго)
Размер ответа в контекстедо ~1500 символов (длиннее — обрезается)
МетодыGET, POST
Порты80, 443

Если вебхук не ответил или вернул ошибку — агент получает короткое «не удалось выполнить» и продолжает разговор, не срываясь.

Безопасность

⚠️

Ответ вебхука — это данные, а не команды. Агент проинструктирован не выполнять инструкции из тела ответа (защита от prompt-injection). Не возвращайте в ответе «служебных» указаний агенту.

  • URL должен быть публичным https. Запросы на loopback, приватные и служебные адреса (127.0.0.1, 10.0.0.0/8, 192.168.…, 169.254.169.254 и т.п.) блокируются — это защита от SSRF; адрес проверяется и «пиннится» на коннекте, поэтому DNS-rebinding не сработает.
  • Для аутентификации добавляйте свой заголовок (например, Authorization: Bearer …) — задаётся в конфигурации инструмента. Заголовок Host переопределить нельзя.
  • Проверяйте на своей стороне, что запрос пришёл от вас ожидаемым (секрет в заголовке/пути).

Совместимость с моделями

Инструменты вызываются нативно на моделях со structured tool-calls (например, Gemini). На YandexGPT (LLM по умолчанию) вызов «протекает текстом» — платформа распознаёт и исполняет его автоматически, так что кастомные инструменты работают и там.

ВебхукиБаза знаний