Инструменты и интеграции
Подключение агентов к внешним API и вебхукам в Voxagent
Агенты Voxagent могут вызывать внешние API во время разговоров, получая данные, выполняя действия и интегрируясь с вашими системами.
Обзор
Инструменты — это HTTP-интеграции, которые LLM может вызывать во время разговора. Когда агент решает, что ему нужны внешние данные или нужно выполнить действие, он вызывает настроенный инструмент и использует результат в своём ответе.
Типы инструментов
Webhook-инструменты
Пользовательские HTTP-эндпоинты, которые агент может вызывать:
- Метод — GET, POST, PUT, DELETE
- URL — адрес эндпоинта (поддерживает подстановку переменных)
- Заголовки — кастомные заголовки, определённые через OpenAPI-схему
- Тело — тело запроса, определённое через OpenAPI-схему
- Описание — объясняет LLM, когда и как использовать инструмент
Системные инструменты
Встроенные инструменты платформы — их не нужно создавать, достаточно включить у агента:
| Инструмент | Функция |
|---|---|
| Завершить звонок | Агент самостоятельно завершает разговор, когда цель достигнута |
| Перевод на оператора | Звонок переводится на телефон живого оператора по SIP: холодный перевод, перевод с заранее заданным сообщением оператору или с автоматическим саммари разговора |
| Перевод на другого агента | Диалог передаётся другому AI-агенту в рамках той же сессии |
| Определение языка | Разговор переключается на язык собеседника из числа настроенных у агента |
| Пропустить ход | Агент молчит и ждёт, если собеседник попросил паузу |
| Запросить уточнение | Фиксируется, какой информации агенту не хватило для решения задачи |
Подробное описание настройки — в разделе Системные инструменты руководства пользователя.
Настройка инструмента
Каждый инструмент определяется OpenAPI-схемой для его параметров:
- Схема тела — определяет структуру JSON-тела, которое LLM должен сформировать
- Схема заголовков — определяет кастомные заголовки для отправки
- Код — уникальный идентификатор, по которому LLM ссылается на инструмент
Речь во время выполнения инструмента
Инструменты поддерживают настраиваемую речь при выполнении:
- Pre-tool speech — что агент говорит перед вызовом инструмента (например, «Сейчас проверю...»)
- Progress speech — что агент говорит в ожидании ответа
Правила переключения
Инструменты перевода содержат правила переключения, перенаправляющие разговор:
- Переключение на другого агента — передача разговора другому AI-агенту внутри той же сессии
- Перевод на оператора — исходящий вызов на номер живого оператора с настраиваемым таймаутом дозвона и режимом прогрева
- Условие — когда должно произойти переключение; по нему модель выбирает правило
Это позволяет создавать мультиагентные сценарии, где специализированные агенты обрабатывают конкретные темы, а всё, что выходит за рамки автоматизации, уходит живому оператору.
Как это работает
- LLM решает вызвать инструмент на основе контекста разговора
- Python worker формирует HTTP-запрос по OpenAPI-схеме
- Запрос отправляется на настроенный эндпоинт
- Ответ передаётся обратно в LLM
- LLM включает результат в свой ответ
Управление вебхуками
Платформа также предоставляет отдельную систему вебхуков для приёма событий:
- Настройка эндпоинтов для получения событий сессий
- Просмотр истории запросов и полезных нагрузок
- Управление разрешёнными путями и маршрутизацией через Webhook Receiver Client
Примеры
Поиск в CRM:
Инструмент: get_customer_info
Метод: GET
URL: https://crm.example.com/api/customers/{{customer_id}}
Описание: Поиск информации о клиенте по IDСтатус заказа:
Инструмент: check_order_status
Метод: POST
URL: https://api.example.com/orders/status
Тело: { "order_id": "string" }
Описание: Проверить текущий статус заказа клиента