Перейти к основному содержанию

Внешние системы: Function и инструменты

Цель модуля: вызвать CRM двумя разными способами и понимать, когда какой уместен.
Есть два способа сходить во внешнюю систему, и разница между ними — кто решает, что пора идти.
Инспектор узла Function: заглушка или HTTP, параметры, переменные из ответа

Function. Переключатель Заглушка / HTTP, параметры с {{var}}, разбор ответа по JSONPath в переменные и реплика-филлер на время вызова.

Инспектор узла Function: заглушка или HTTP, параметры, переменные из ответа
Инспектор Conversation с инструментом book_appointment и переопределением модели

Conversation + инструмент. Тот же вызов, но решение принимает модель: инструмент book_appointment плюс своя модель генерации для этого узла.

Инспектор Conversation с инструментом book_appointment и переопределением модели

Что настраивается у Function

Инструмент у Conversation настраивается той же формой, поэтому всё ниже относится к обоим способам.
  • Режим выполнения — Заглушка (постоянный ответ) или HTTP (реальный вызов).
  • Имя в блоке Функция — префикс служебных переменных результата: функция get_free_slots запишет get_free_slots_status, get_free_slots_success и так далее.
  • Метод и URL — метод выбирается из списка: GET, POST, PUT, PATCH, DELETE. URL, Параметры строки запроса, Заголовки и тело поддерживают подстановку {{var}} и секретов {{env.ИМЯ}}. Секрет в поле не пишут: пишут ссылку на него, значение подставляется при выполнении и маскируется в логах.
  • Тело запроса — у всех методов, кроме GET; тип json, form или raw. Content-Type (переопределение) задаёт заголовок вручную; пустое поле — Content-Type по типу тела.
  • Таймаут, сек — по умолчанию 10, считается на каждую попытку.
  • Повторы — по умолчанию 0. Повтор делается при сетевой ошибке, таймауте и ответе 5xx; ответ 4xx не повторяется.
  • Пауза между повторами, сек — по умолчанию 0,5 и удваивается с каждым повтором: 0,5 → 1 → 2 с. Повторы и паузы удлиняют вызов, а клиент всё это время ждёт.
  • Проверять TLS-сертификат (tls_verify) — включено по умолчанию.
  • Успешные статусы ответа — по умолчанию 2xx; можно перечислить коды и диапазоны через запятую, например 200-299, 404. Остальные статусы — неуспех.
  • Переменные из ответа — slots_count ← $.count: слева имя переменной, справа путь JSONPath в ответе. Переменной становится только то, что здесь перечислено. Кроме них после вызова всегда доступны служебные <имя>_status, <имя>_success (true или false), <имя>_error и <имя>_result — сырой ответ, его нет, если ответа не было. Те же статус, успех и ошибка последнего вызова лежат в http_status, http_success, http_error. По ним строят ветвление «успех / ошибка» формулой.
  • Реплика во время вызова — «Секунду, смотрю свободное время…». Агент произносит её перед запросом, {{var}} в ней подставляются. Совет: в голосе это не украшение — без неё клиент слышит тишину на всё время запроса. Пишите реплику на языке разговора: для англоязычного агента, например, «One moment, let me check the available times…».
  • Заглушка — фиксированный ответ: HTTP-код заглушки и Ответ-заглушка (JSON с {{var}}). Сценарии-заглушки добавляют именованные варианты: успех со своим кодом и ответом или сбой timeout / network; Активный сценарий по умолчанию выбирает, какой из них отвечает. На заглушке собирают и тестируют сценарий, пока API клиента не готов: наружу ничего не уходит. Ею же отвечает функция в чат-тесте, когда в настройках запуска для HTTP-функций выбрано заглушки, — даже если в узле включён режим HTTP.
URL должен быть доступен из интернета: запросы на частные и локальные адреса платформа может отклонить — тогда запрос не уходит, а <имя>_error равно blocked. Как платформа формирует запрос и разбирает ответ, подробно описано в контракте для разработчика.
Грабли: неуспех — это тоже маршрутСеть падает, CRM отвечает 500. Если из Function выходит один переход Always, ошибка поедет дальше как «всё хорошо» — с пустыми переменными. Правильно: после Function поставить ветвление по <имя>_success, например {{get_free_slots_success}} == false, и вести неуспех на человека или на вежливое «мы перезвоним». Проверить эту ветку заранее помогает сценарий-заглушка с ошибкой.
Если ваша система отдаёт инструменты по MCP, есть третий путь — узел MCP Tool. Он работает как Function: вызывает инструмент MCP-сервера на входе в узел, аргументы — с {{var}}, переменные из ответа — по JSONPath, есть реплика во время вызова.