Инструмент Запросы к внешним сервисам позволяет AI-агенту совершать API-запросы в ходе разговора.
Агент может получать информацию из внешних сервисов, и отправлять данные, полученные в ходе диалога.
Поддерживается только взаимодействие с REST API, тело запроса может быть только в формате JSON.
¶ Настройка запросов в AI-агенте
¶ Настройка переменных
Для отправки данных из диалога в запросе к серверу необходимо предварительно объявить нужные переменные во вкладке Переменные параметров AI-агента.
Полученные переменные могут использоваться в теле запроса к серверу, в промптах, и при фиксации результатов диалога. Принципы работы с переменными в промптах описаны ниже.
Для добавления новой переменной перейдите на вкладку Переменные и нажмите кнопку Добавить переменную.
Заполните параметры:
- Название переменной – название, которое можно использовать в промптах и в параметрах запросов к серверу. В названии могут использоваться кириллица и латиница, дефис и нижнее подчеркивание, пробелы и иные символы запрещены.
- Описание переменной – Небольшой промпт, указывающий какие именно данные нужно извлечь из диалога и сохранить в качестве значения переменной. Также в промпте можно указать действие, которое нужно совершить со значением переменной, прежде чем оно будет сохранено.
Примеры описания переменной:
Шестизначный номер заказа, названный клиентом в ходе диалога
Номер телефона собеседника, который он продиктовал. Если номер начинается на цифру 8, то замени её на цифру 7.
Если номер содержит всего 10 цифр, то добавляй цифру 7 в начале.
Если номер начинается с цифры 7 и содержит всего 11 цифр, то записывай номер без изменений.
Значение по умолчанию – исходное значение переменной. Заменяется, если в ходе диалога в переменную было записано новое значение.
Пример настроек переменных:
¶ Работа с переменными в промптах
Констекстные переменные могут использоваться в промптах агента.
Если нужно обратиться к значению переменной, то требуется указать ее в формате {имя_переменной}.
Пример:
Клиент забронировал столик на {дата}. Имя клиента: {имя}.
Если нужно указать агенту на саму переменную, например, для записи значения переменной, то название переменной требуется указать без фигурных скобок.
Пример:
Названную клиентом дату запиши в переменную "дата". Имя клиента хранится в переменной "имя".
Обращайте внимание на обращения к переменным при составлении промптов – некорректно выбранный вариант обращения может вызвать ошибки в работе агента, и негативно повлиять на качество его ответов.
Чтобы озвучить значение переменной клиенту, нужно обратиться к переменной из основной инструкции агента.
Пример:
...
#Структура и этапы диалога
1. Получить номер заказа собеседника.
2. Получить номер телефона собеседника.
4. Получить статус заказа с помощью инструмента STATUS_REQUEST.
5. Получить дату доставки с помощью инструмента DELIVERY_REQUEST.
6. Сообщить статус заказа: {status} и дату доставки: {deliveryDate}.
...
¶ Добавление запроса
Для добавления нового запроса нажмите кнопку Добавить запрос в разделе Запросы к внешним сервисам параметров AI-агента.
В открывшемся окне заполните параметры запроса:
- Уникальное название запроса для использования в промпте – с помощью этого названия можно взаимодействовать с запросом из промпта (инструкции) AI-агента. В названии могут использовать кириллица и латиница, дефис и нижнее подчеркивание, пробелы и иные символы запрещены. Рекомендуется указывать названия, соответствующие смыслу запроса вместо стандартных.
- Таймаут (в секундах) – максимальное время ожидания ответа на запрос. Если ответ на запрос не будет получен в течение указанного времени, то звонок будет сброшен.
- Промпт (инструкция) – Промпт для работы с указанным запросом.
В промпте нужно указать:- Какие действия нужно произвести при отправке запроса и при получении ответа;
- Какие данные нужно отправить, и какие данные нужно сохранить.
- Фраза перед выполнением запроса – (Опционально) Сообщение, которое агент озвучивает перед выполнением запроса. Можно использовать статичный текст, чтобы задать фиксированную фразу или позволить агенту сгенерировать фразу на основе промпта.
Пример промпта для запроса с названием ПРОВЕРКА_СТАТУСА_ЗАКАЗА:
Номер заказа клиента передай в массиве orders
Получи значение из поля status, это строка содержащая статус заказа
Следующие параметры схожи с параметрами блока Запрос к серверу из редактора сценариев:
- Метод – метод запроса. Допустимые значения: GET, POST, PUT, DELETE.
- URL – адрес, на который будет отправлен запрос.
- Параметры – параметры, которые будут переданы в URL. В значениях параметров допустима передача контекстных переменных в формате
{имя_переменной}. Работа с переменными описана в разделе Работа с переменными этой статьи. - Заголовки – Заголовки (headers) запроса.
- Тело запроса – Тело запроса в формате JSON. В значениях полей допустима передача контекстных переменных в формате
{имя_переменной}. Работа с переменными описана в разделе Работа с переменными этой статьи. - Контекстные переменные – Раздел позволяет сохранить поля из ответа сервера в контекстные переменные. Путь до поля указывается в формате JSONPath (например,
data.0.operator.name). Стоит учитывать, что контекстные переменные не передаются в агента автоматически, но могут использоваться в промптах и при фиксации результатов диалога. - Контроль токенов – Раздел определяет, какие именно поля из ответа сервера передаются в агента. Путь до поля указывается в формате JSONPath (например,
data.0.operator.name). Если поля не указаны, агенту будет передано тело ответа целиком. Выбор конкретных полей для передачи агенту позволяет сократить объем токенов для обработки агентом, что повышает скорость и точность ответов.
Пример настроек запроса:
¶ Обращение к запросу в основном промпте агента
Если в основной инструкции не указано, когда именно агент должен отправить запрос, то он не будет выполняться.
Обращение к запросу в промпте происходит по его названию без фигурных скобок.
Если в агенте используется несколько запросов, рекомендуется указывать собственные названия для запросов, иначе агент может некорректно интерпретировать промпт.
¶ Сохранение информации из ответа сервера
Настроить сохранение данных можно с помощью вкладки Контекстные переменные в настройках запроса, либо через промпт запроса.
Настройка через промпт – более гибкая; агент сам находит нужное поле в ответе, запоминает его, и потом может использовать его значение в ходе диалога. Стоит учитывать, что в таком случае значение не записывается в контекстные переменные, если не создана переменная с соответствующим промптом. Создание переменных, и пример переменной для записи ответа сервера описаны в разделе Работа с переменными этой статьи.
Настройка через контекстные переменные – более точная; не позволяет агенту ошибиться при записи значения переменной, так как требует точного указания пути до нужного поля.
¶ Рекомендации при настройке запросов
- Объявлять все используемые переменные в разделе Контекстные переменные
- Если в агенте используется несколько запросов, рекомендуется указывать собственные названия для запросов, иначе агент может некорректно интерпретировать промпт.
- Если агент некорректно озвучивает значение переменной, можно в промпте указать чтобы агент предварительно изменил формат значения для корректного озвучивания.
- Указывайте точную последовательность действий в основной инструкции, включая запросы к серверу – это позволит избежать ошибок в диалогах.