Добавление инструментов и перевода на оператора в голосовой агент Vonage + Deepgram

Введение

Руководство по использованию Vonage Voice API и Deepgram позволяет продвинуться удивительно далеко.

К концу этого руководства вы сможете позвонить на номер Vonage, поговорить с ИИ-агентом, перебить его во время разговора и вести естественную голосовую беседу, работающую на базе Voice Agent API от Deepgram.

Однако агент все еще не может сделать для вас ничего существенного (у него нет инструментов!).

Попросите агента выполнить действие, и если информация об этом действии не прописана в системном промпте, ему негде будет ее искать. Дайте ему задачу, зависящую от другой системы, и вы столкнетесь с новой проблемой: вызывающий абонент будет ждать, пока эта система ответит.

В голосовом общении такие детали становятся заметны очень быстро. Медленный вызов API выглядит не как индикатор загрузки, а как тишина в трубке.

Эта специфическая для аудио проблема ИИ-агентов была описана в статье «Don’t Loop the Latency: Where Agent Loops Belong in Voice AI». Одна из идей статьи заключается в том, чтобы сделать работу, выполняемую во время живого телефонного звонка, минимальной и предсказуемой.

Цель этой статьи — превратить демонстрационную версию агента в инструмент, который может выполнять полезные задачи, предсказуемо обрабатывать ошибки и, что самое важное, сохранять достаточно информации для последующего улучшения. В этом руководстве мы расширим существующий агент Vonage + Deepgram, чтобы он мог:

• предоставить агенту инструмент для проверки статуса заказа

предоставить агенту инструмент для проверки статуса заказа

• установить жесткий тайм-аут для поиска

установить жесткий тайм-аут для поиска

• обрабатывать сбои, не заставляя абонента ждать

обрабатывать сбои, не заставляя абонента ждать

• переводить запросы, с которыми агент не справляется, на реальный номер телефона

переводить запросы, с которыми агент не справляется, на реальный номер телефона

• сохранять запись того, что произошло во время каждого звонка

сохранять запись того, что произошло во время каждого звонка

TL;DR: Краткое руководство доступно на GitHub.

TL;DR: Краткое руководство доступно на GitHub.

Предварительные требования

Вам понадобятся:

• Учетная запись Vonage API

Учетная запись Vonage API

• Приложение Vonage с поддержкой Voice

Приложение Vonage с поддержкой Voice

• Номер телефона Vonage, привязанный к этому приложению

Номер телефона Vonage, привязанный к этому приложению

• Второй номер телефона, который можно использовать для перевода на оператора

Второй номер телефона, который можно использовать для перевода на оператора

• Учетная запись Deepgram с доступом к Voice Agent

Учетная запись Deepgram с доступом к Voice Agent

• Node.js 20+

Node.js 20+

• ngrok

ngrok

Даем агенту инструмент

Мы намеренно ограничимся простым сценарием: проверка статуса заказа. Абонент говорит:

«Где мой заказ A1001?»

«Где мой заказ A1001?»

Deepgram распознает, что агенту нужна внешняя информация, и просит наше приложение вызвать:

getOrderStatus("A1001")

getOrderStatus("A1001")

Наше приложение выполняет поиск и отправляет результат обратно в Deepgram. Затем модель превращает этот результат в естественный голосовой ответ.

Для этого руководства бэкенд заказов является имитацией. Позже вы сможете заменить его на собственную базу данных или API; нам просто нужен поиск, который может завершиться успешно, с ошибкой или занять слишком много времени:

Также есть несколько специальных ID заказов для тестирования:

• ID, начинающиеся с SLOW, возвращают ответ через две секунды.

ID, начинающиеся с SLOW, возвращают ответ через две секунды.

• ID, начинающиеся с FAIL, имитируют временный сетевой сбой.

ID, начинающиеся с FAIL, имитируют временный сетевой сбой.

• Все остальное возвращает not_found.

Все остальное возвращает not_found.

Это позволяет нам воспроизвести поведение, которое мы получили бы от реальной базы данных или внешнего API, не создавая полноценный бэкенд для этого руководства.

Регистрация инструмента в Deepgram

Voice Agent API от Deepgram поддерживает вызов функций на стороне клиента. Мы описываем функцию в сообщении Settings агента:

Мы не даем Deepgram HTTP-эндпоинт для функции. Вместо этого Deepgram отправляет на наш WebSocket запрос FunctionCallRequest. Это означает, что наше приложение сохраняет контроль над фактическим выполнением инструмента.

Это полезно, потому что мы можем решать:

• разрешен ли инструмент

разрешен ли инструмент

• как долго он может выполняться

как долго он может выполняться

• нужно ли повторять попытку при сбое

нужно ли повторять попытку при сбое

• что услышит абонент, если что-то пойдет не так

что услышит абонент, если что-то пойдет не так

Промпт агента также остается узкоспециализированным:

Промпт говорит модели, что делать, но мы не полагаемся только на него. Перед выполнением поиска заказа приложение проверяет, входит ли запрос в область компетенции и не использовался ли этот инструмент ранее в рамках данного звонка. Вы можете увидеть, как это работает, в разделе «Обработка вызова функции».

Установка дедлайна для поиска

Здесь разработка для телефонных звонков начинает отличаться от создания обычного чат-бота. Представьте, что сервис заказов отвечает шесть секунд. С точки зрения сервера — это просто медленный запрос.

С точки зрения абонента — он задал вопрос и услышал шесть секунд тишины.

Поэтому в данном примере на поиск отводится 1500 миллисекунд:

Обертка сопоставляет вызов бэкенда с этим дедлайном:

Важно то, что существует три возможных исхода:

Исход

Что это значит

Что мы делаем

result

Бэкенд ответил

Возвращаем результат

timeout

Ответа не было в течение 1500 мс

Используем резервный вариант

transport_error

Соединение разорвано

Повторяем один раз

Ответ not_found — это все еще успешный поиск. Бэкенд ответил, просто он не нашел заказ.

Это отличается от тайм-аута.

Ограничение действий во время звонка

Для этого примера правила намеренно минимальны:

Каждый телефонный звонок получает свой экземпляр политики:

Тайм-аут не повторяется.

Мы уже прождали 1,5 секунды. Повторный запуск того же медленного запроса может просто дать нам еще 1,5 секунды тишины.

Сбой передачи данных получает одну повторную попытку, так как разорванное соединение или временная проблема на стороне провайдера могут быть устранены немедленно.

Обработка вызова функции

Когда Deepgram отправляет FunctionCallRequest, обработчик WebSocket применяет эти правила перед запуском инструмента.

Основной поток выглядит так:

Фактический обработчик также записывает вызов инструмента и время выполнения, но именно эта часть контролирует то, что слышит абонент.

Использование фиксированного резервного ответа

Если поиск не удался, вы не хотите, чтобы модель придумывала собственный план восстановления.

Приложение внедряет фиксированный ответ:

InjectAgentMessage от Deepgram позволяет нам поместить этот ответ прямо в разговор:

Здесь важно поведение прерывания.

Использование поведения по умолчанию может привести к тому, что внедренное сообщение будет отклонено, пока абонент говорит. Это не то, что вы хотите обнаружить, когда внедренное сообщение — ваш путь обработки ошибки.

Также обратите внимание на имя поля: это message, а не content.

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

Перевод неподдерживаемых запросов на человека

Агент по статусу заказов не должен пытаться ответить на все вопросы.

Если кто-то говорит:

«Я хочу оспорить списание средств».

«Я хочу оспорить списание средств».

Мы классифицируем это как запрос по биллингу:

Для этой демо-версии классификация намеренно ограничена и детерминирована:

Здесь нет второго вызова модели.

Если абонент просит что-то вне компетенции агента, мы знаем, что хотим одного и того же результата каждый раз: перевести звонок на человека.

transferToHuman() обновляет активный вызов Vonage с помощью нового NCCO.

Сначала NCCO сообщает вызывающему абоненту, что происходит, а затем переключает вызов на номер службы поддержки:

Затем мы переводим активный вызов:

Для локального тестирования в качестве SUPPORT_PHONE_NUMBER можно просто указать другой телефон, который находится рядом с вами.

Позвоните на свой номер Vonage с одного телефона, попросите оспорить списание, и второй телефон должен зазвонить.

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

Настройка перевода

Чтобы реальная передача вызова заработала, добавьте эти значения в свое окружение:

Вам также понадобится существующая конфигурация:

Используйте номера в формате E.164 для Vonage и службы поддержки.

Сохранение информации о ходе вызова

Приложение также записывает небольшую запись в SQLite по окончании вызова.

Это не база данных заказов. Это запись самого голосового взаимодействия.

Запись может сообщить нам:

• что сказали вызывающий абонент и агент

что сказали вызывающий абонент и агент

• какой инструмент был вызван

какой инструмент был вызван

• сколько времени это заняло

сколько времени это заняло

• был ли использован резервный вариант

был ли использован резервный вариант

• был ли переведен вызывающий абонент

был ли переведен вызывающий абонент

• почему произошел перевод

почему произошел перевод

• как закончился вызов

как закончился вызов

Например, звонок по вопросам биллинга может выглядеть примерно так:

Это полезно, даже если вы никогда не будете строить вокруг этого сложную систему оценки.

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

Как запустить агента

Сначала запустите ngrok:

Вставьте этот HTTPS-URL в BASE_URL и в вебхуки Answer и Event вашего приложения Vonage.

Затем запустите приложение:

Вы можете проверить работоспособность вебхука ответа перед совершением телефонного звонка:

Возвращенный NCCO должен содержать WebSocket-эндпоинт, похожий на этот:

wss://YOUR-NGROK-URL/socket?callUuid=test123

Попробуйте четыре вызова

Попробуйте протестировать основные сценарии поведения отдельными телефонными звонками.

Вызов

Что сказать

Что должно произойти

«Где заказ A1001?»

Агент зачитывает статус доставки

«Где заказ SLOW999?»

Поиск по времени ожидания истекает, и срабатывает фиксированный резервный вариант

«Где заказ XYZ123?»

Агент сообщает, что заказ не найден

«Я хочу оспорить списание.»

Вызов переводится на ваш телефон службы поддержки

Делайте каждый вызов новым. Этот пример позволяет выполнить один поиск заказа за вызов.

После этого изучите записи:

Вы должны увидеть различные пути, представленные в данных:

completed fallback completed handoff

Для последнего вызова handoff_reason должен быть billing.

Заключение

Оригинальное руководство по Vonage + Deepgram позволяет внедрить разговорного ИИ-агента в реальный телефонный вызов. Здесь мы дали этому агенту одну полезную задачу: искать заказ, прекращать ожидание, когда бэкенд слишком медленный, корректно переключаться на резервный вариант при сбоях и переводить неподдерживаемые запросы на человека.

Бэкенд заказов является имитацией, но схема будет такой же, если вы замените getOrderStatus() на свою собственную базу данных или API.

Это идея Винса «не зацикливай задержку» на практике: пока вызывающий абонент ждет, выполняйте минимум действий, устанавливайте сроки для внешних вызовов и предоставляйте полезный путь отхода.

После завершения вызова эти ограничения по задержке исчезают. Именно здесь становятся полезными сохраненные нами записи, транскрипты, вызовы инструментов, результаты, причины перевода и версии агентов.

Если, например, «возвраты» начинают появляться как причина перевода, мы можем использовать эти вызовы, чтобы решить, что создавать дальше, добавить возможность обработки возвратов в новую версию и протестировать ее на сохраненных вызовах, прежде чем представлять ее пользователям.

Это начало рабочего процесса проектирования циклов. Но это уже для следующей статьи!