HTTP-инструменты

Опишите HTTP-запрос инструмента, его параметры и результат в конструкторе плагина.

В разделе «Инструменты агента» приложения выберите «Конструктор».

Конструктор HTTP-инструментов

Нажмите «Добавить». В форме инструмента сначала заполните представление для пользователя.

На вкладке «Русский» укажите название и краткое описание. В необязательном поле «Описание ответа» поясните, какие данные вернёт инструмент после выполнения.

На вкладке English заполните английское название и английское описание. Если описание ответа заполнено на русском, добавьте его английскую версию в поле «Описание ответа».

Оба названия и оба кратких описания обязательны: пользователь увидит вариант языка своего кабинета. Описание ответа можно не заполнять, но если оно нужно, укажите обе языковые версии. Пользователь увидит его в подробностях инструмента и поймёт, какой результат ожидается после вызова.

Затем задайте технические параметры:

• системное имя, например find_customer;
• URL обработчика с http или https;
• по умолчанию агент использует русское краткое описание. Включите «Техническое описание для агента» и заполните описание для агента, только если модели нужны дополнительные условия вызова, которых не должен видеть пользователь;

• в списке параметров задайте имя, тип string, number или boolean, понятное описание и обязательность каждого аргумента.

В блоке «Добавление в агента» включите «Настройка при добавлении», если перед подключением действия пользователь должен выбрать аккаунт, область доступа или другие параметры. При необходимости включите «Разрешить добавлять несколько раз»: тогда один агент сможет иметь несколько независимо настроенных экземпляров.

Для каждого нового аргумента нажмите «Добавить параметр». У каждого параметра есть кнопка удаления.

После подтверждения параметр исчезает только из текущей формы; фактический инструмент изменится после сохранения всей формы.

После заполнения формы используйте «Сохранить».

Сохранённый инструмент в списке можно снова открыть и изменить. Действие «Удалить» требует подтверждения и окончательно убирает инструмент из приложения.

При вызове обработчик получает JSON такого вида:

{
  "event_id": "019d0000-0000-7000-8000-000000000001",
  "event_type": "tool_call",
  "timestamp": "2026-07-30T12:00:00.000Z",
  "app_id": "app-id",
  "installation_id": "installation-id",
  "project_id": "project-id",
  "agent_id": "agent-id",
  "dialog_id": "dialog-id",
  "lead_id": "lead-id",
  "tool_name": "find_customer",
  "tool_instance_id": "tool-instance-id",
  "arguments": {
    "customer_id": "123"
  },
  "configuration": {
    "account_id": "store-1"
  },
  "private_data": {
    "access_token": "write-only-token"
  }
}

agent_id и dialog_id передаются всегда, а lead_id — только когда диалог связан с лидом. tool_instance_id отличает независимо настроенные экземпляры одного инструмента. configuration содержит обычные настройки экземпляра, private_data — расшифрованные закрытые данные для выполнения вызова; не записывайте их в открытые логи и ответы. Для обычного ненастраиваемого инструмента оба объекта пустые.

Вызов подписывается единым секретом всех webhook приложения. Проверьте свежесть X-Webhook-Timestamp, соответствие X-Webhook-Event-Id полю event_id и X-Webhook-Signature по тем же правилам, что и для публичных webhook приложения. Не выполняйте действие до успешной проверки подписи.

Используйте event_id как ключ идемпотентности: автоматический или ручной повтор может отправить то же действие снова.

Режимы выполнения и повторы

В режиме выполнения выберите:

• «Мгновенное выполнение» — агент ждёт один HTTP-ответ и получает его тело как результат инструмента; автоматических повторов нет;
• «Ожидание результата» — запрос ставится в очередь, агент приостанавливает этот шаг и продолжает после успешного результата;
• «Фоновая операция» — запрос ставится в очередь, но агент не ждёт и не использует ответ для продолжения текущего шага.

Одна попытка ждёт ответ 10, 30, 60 или не более 120 секунд — значение выбирается в поле «Таймаут HTTP-попытки». Для двух асинхронных режимов выберите окно повторов:

• 5 минут — 5 попыток: сразу, через 15 секунд, 1, 3 и 5 минут;
• 3 часа — 8 попыток: сразу, через 1, 5, 15, 30 минут, 1, 2 и 3 часа;
• 1 день — 12 попыток: сразу, через 1, 5, 15, 30 минут, 1, 2, 4, 8, 12, 18 и 24 часа.