Действие Агента ИИ: Выполнять HTTP-запросы

Доступность плана: Доступно на тарифах Advanced, Enterprise и некоторых Legacy. Тестирование доступно всем пользователям, но публикация требует подходящего тарифа.

Действие Выполнять HTTP-запросы позволяет Агенту ИИ вызывать внешние API во время разговора. Это позволяет Агенту ИИ получать данные в реальном времени или запускать действия во внешних системах по запросу Контакта. Например, Агент ИИ может проверить статус заказа, получить информацию об учетной записи или создать записи в другой системе. В этой статье ты узнаешь, как настроить действие HTTP-запроса и протестировать его с Агентом ИИ.

Агент ИИ:

1. Анализирует сообщение Контакта, чтобы определить, соответствует ли оно намерению, заданному в инструкциях к действию.

2. Собирает необходимую информацию.

3. Отправляет HTTP-запрос.

4. Интерпретирует ответ API.

5. Естественно отвечает Контакту.

Добавить действие «Выполнять HTTP-запросы»

Включи действие и нажми кнопку «Добавить действие», чтобы начать настройку HTTP-запроса.

Укажи, когда должно выполняться действие

Дай описательное имя действию в поле Action name .

В поле When and how should this action be performed? в этом поле опиши:

• Когда Агент ИИ должен использовать это действие

• Что оно получает или отправляет

• Какие условия или исходы нужно обработать

Пример:

Используй это действие, чтобы получить статус заказа Контакта, когда он спрашивает о своём заказе. Если API вернёт ошибку 404, сообщи Контакту, что заказ не найден.

Агент ИИ использует это описание, чтобы решить, когда запускать запрос.

Информация, которая может понадобиться Агенту ИИ (необязательно)

Определи входные данные, которые требуются в этом разделе, до вызова API.

Это структурированные переменные, которые Агент ИИ должен собрать. Запрос выполняется только после того, как все обязательные входные данные доступны.

Если значение:

• Уже упомянуто в разговоре → Агент ИИ использует его.

• Отсутствует → Агент ИИ запрашивает его у Контакта.

Переменные, созданные здесь, можно использовать в настройках API. Переменные Контакта (например, $contact.email) доступны автоматически и не требуют добавления.

Настройки поля

Настройка API

Определи, как Агент ИИ должен вызывать твой API.

Ты можешь настроить:

• Метод

• URL

• Параметры запроса

• Заголовки

• Тело JSON (для POST, PUT, PATCH)

Использование переменных

Ты можешь вставлять переменные в URL, параметры, заголовки или тело, используя $.

Есть два типа:

• Переменные Контакта — существующие поля Контакта

  • $contact.email

• Переменные Агента ИИ — поля, определённые в разделе Информация, которая может понадобиться Агенту ИИ

  • $agent.order_id

Переменные заменяются реальными значениями при выполнении запроса. Если обязательная переменная Агента ИИ отсутствует, Агент ИИ запросит её перед запуском API-вызова.

Как Агент ИИ обрабатывает ответы API

Пример тела:

{
  "order_id": "$agent.order_id",
  "email": "$contact.email"
}

Агент ИИ автоматически интерпретирует JSON-ответ API и формирует естественный ответ.

Пример ответа API:

{
  "status": "shipped",
  "eta": "2025-12-12"
}

Ответ Агента ИИ: «Отличные новости! Ваш заказ отправлен и ожидается доставка 12 декабря 2025 года.»

Тестирование

Ты можешь протестировать действие HTTP-запроса в панели Test AI Agent перед публикацией.

Как протестировать

1. Начни тестовый разговор, который соответствует условиям действия.

   

2. Когда намерение распознано и обязательные входные данные доступны, Агент ИИ выполняет HTTP-запрос.

3. Событие выполнения появляется в тестовой панели:

   

   1. {AI Agent name} выполнил {Action name}

   2. Ответы 2xx отображаются как успешные

   3. Все остальные коды состояния отображаются как неуспешные

4. Нажми на событие, чтобы просмотреть:

   1. Response вкладка (по умолчанию) — полное тело ответа API

   2. Request вкладка — полное содержимое cURL-запроса

   3. Опция копирования для отладки

5. После получения ответа API Агент ИИ формирует ответ на основе возвращённых данных.

Важные примечания

• События выполнения появляются только в панели Test AI Agent. Они не отображаются в Inbox или в активности Контакта.

• Если обязательные входные данные отсутствуют, Агент ИИ запросит их перед запуском запроса.

Лучшие практики

• Будь точным в описании действия. Неясные инструкции приводят к неопределённым запускам.

• Ясно укажи обязательные входные данные. Если Агенту ИИ нужно что-то запросить, сделай это очевидным.

• Учти обработку ошибок в инструкциях.

• Всегда тестируй перед публикацией.

• Не дублируй логику, уже реализованную в автоматизированных алгоритмах, если это не сделано намеренно.

Ограничения

• Максимум 10 действий HTTP-запросов на одного Агента ИИ.

• Максимум на действие:

  • 20 полей ввода данных

  • 50 параметров

  • 50 заголовков

• Агент ИИ определяет, когда вызывать API, на основе твоего текстового описания. Плохо составленные инструкции могут привести к непредсказуемым запускам.

• Обработка ответа API происходит автоматически. Ты не можешь вручную сопоставлять поля ответа — Агент ИИ интерпретирует JSON контекстно.

• События выполнения HTTP-запроса отображаются только в панели Test AI Agent и не появляются в активности Контакта.

• Голосовые Агенты ИИ могут запускать действие «Выполнять HTTP-запросы». Однако возвращённый ответ API не передаётся обратно голосовому Агенту ИИ для генерации ответа, поэтому голосовые разговоры не могут динамически реагировать на основе результата API.