Как создать голосового агента и Realtime API

Сегодня вы познакомитесь с голосовыми агентами и разберёте, как они работают. На этом интересное не заканчивается! Вы также изучите интерфейс Realtime API, который позволяет агентам работать в режиме реального времени.

Что такое голосовые агенты

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

• распознавать речь пользователя в реальном времени;
• понимать смысл запроса и учитывать контекст;
• формировать ответ с учётом контекста и логики диалога;
• при необходимости вызывать инструменты и внешние сервисы;
• отвечать голосом, поддерживая естественный ход диалога.

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

Состав голосового агента

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

• Языковая модель (LLM) — интерпретирует смысл сказанного, принимает решения и формирует ответ или действие.
• Инструкция к модели (промпт) — задаёт цели, стиль и правила поведения агента, определяет рамки его решений.
• Инструменты (tools) — позволяют агенту выполнять конкретные операции: обращаться к данным, вызывать внешние сервисы или выполнять вычисления.
• Speech-to-Text (STT) — преобразует речь пользователя в текст для дальнейшей обработки моделью.
• Text-to-Speech (TTS) — озвучивает сформированный ответ и обеспечивает естественный разговорный интерфейс.

Общий цикл обработки пользовательской реплики в голосовом агенте:

Пример работы голосового агента

Заданные условия:

• Промпт для агента: «Ты — дружелюбный погодный ассистент. Отвечай кратко и естественно.Если спрашивают о погоде, используй инструмент get_weather.Если город не указан, уточни его.»
• Доступен инструмент get_weather(city, day).

Как происходит взаимодействие:1️⃣ Пользователь произносит фразу

Какая погода завтра в Киото?2️⃣ Speech-to-Text (STT) преобразует аудиопоток в текст Какая погода завтра в Киото?

3️⃣ Языковая модель (LLM) анализирует запрос, опирается на промпт и принимает решение вызвать инструмент get_weather.

4️⃣ Инструмент возвращает данные: get_weather(city="Киото", day="завтра") → {"temp": "+23°C", "condition": "ясно"}.

5️⃣ LLM формирует текстовый ответ согласно инструкции и ответу инструмента Завтра в Киото +23 и ясно.

6️⃣ Text-to-Speech (TTS) преобразует текст в речь выбранным голосом (например, marina).

Где используются голосовые агенты

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

Клиентские сервисы и поддержка

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

Сайты и мобильные приложения

Подходит, когда пользователю неудобно печатать. Агент помогает оформить заказ, найти информацию или заполнить форму — всё в диалоговом режиме.

Банк и финансы

Автоматизация простых операций: проверка баланса, статус заявки, блокировка карты, консультации по услугам. Голосовой агент снижает нагрузку на операторов и сокращает время обработки.

Логистика, ритейл, транспорт

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

Медицина и страхование

Сбор первичной информации, напоминание о визитах, помощь с оформлением документов. Во внутренних процессах — поддержка операторов и ускорение обработки типовых обращений.

Обучение и корпоративные тренажёры

Голосовые тренажёры и ассистенты позволяют отрабатывать сценарии общения, получать подсказки и обратную связь в удобном формате.

Realtime API

Современные пользователи ожидают от голосовых систем естественного разговора — с нормальными паузами, без искусственных задержек и роботизированных переходов между репликами.Чтобы голосовой агент воспринимался живым, он должен реагировать мгновенно, но говорить в естественном ритме — как человек.Стандартные голосовые боты работали с длинными паузами: они ждали полного окончания фразы, обрабатывали речь поэтапно, не умели говорить и слушать одновременно. Это делало ответы медленными и неестественными. Решение этих ограничений — переход к потоковой обработке и двунаправленному соединению с моделью. Именно этот подход реализован в Realtime API.💡 Realtime API — это интерфейс, позволяющий работать с моделями в режиме реального времени через WebSocket.Realtime API позволяет системе одновременно:

• принимать аудио от пользователя;
• распознавать речь по мере поступления;
• генерировать ответ;
• начинать синтез речи до завершения генерации.

Аудио, текст и команды обрабатываются параллельно, а ответ начинает формироваться за доли секунды в живом ритме диалога. Благодаря этому голосовые агенты больше не звучат как машины, а ведут разговор естественно.Главное преимущество Realtime API — единая потоковая сессия, в которой распознавание речи, языковая модель и синтез речи работают синхронно. Разработчику не нужно вручную связывать STT, LLM и TTS через отдельные запросы — взаимодействие происходит внутри одного соединения в реальном времени, без лишних задержек.

Концепции Realtime API

💡 В основе работы лежат два ключевых понятия — сессия и ивенты.

Сессия

💡 Сессия — это постоянное двунаправленное соединение между клиентом и моделью, в рамках которого выполняются все операции реального времени: передача аудио, получение промежуточных событий, генерация ответа и вызов инструментов.В сессии сохраняется контекст диалога — предыдущие реплики, инструкции и настройки, что позволяет агенту вести непрерывный разговор в рамках одного подключения.Через параметры сессии можно задать:

• конфигурацию детекции конца фраз;
• параметры синтеза голоса;
• включение/отключение текстового выхода;
• системные инструкции агента.

Именно сессия определяет контекст и параметры, в которых агент работает в реальном времени.

Ивенты (events)

Realtime API работает по событийной модели, где взаимодействие строится как обмен структурированными событиями поверх WebSocket.Каждый этап работы голосового агента: приём аудио, распознавание, генерация ответа, вызов инструментов, изменение настроек — оформлен как отдельное событие с определённым типом и набором полей.Сессия в этом случае выступает как поток событий, а клиент и сервер — как два асинхронных участника, обменивающихся сообщениями независимо друг от друга. Это позволяет системе:

• обрабатывать аудио и текст параллельно;
• выдавать частичные результаты (delta-события);
• корректно реагировать на прерывания пользователя;
• менять конфигурацию моментально;
• обеспечивать низкую латентность за счёт отсутствия жёстких циклов запросов и ответов.

Каждое действие клиента формирует событие, а сервер генерирует свои события по мере прогресса обработки данных.В итоге весь Realtime API — это детерминированный протокол обмена событиями, из которых можно собрать полную картину хода диалога и состояния внутреннего пайплайна агента.Примеры входящих событий от клиента:

• input_audio_buffer.append — передача очередного аудиофрагмента;
• session.update — изменение параметров сессии, например голоса или встроенного детектора голосовой активности (VAD);
• response.cancel — отмена текущего ответа;
• response.create — запрос на генерацию ответа.

Примеры исходящих событий от сервера:

• input_audio_buffer.speech_started и speech_stopped — серверный VAD зафиксировал начало или конец речи;
• conversation.item.input_audio_transcription.completed — завершено распознавание реплики;
• response.created, response.output_text.delta, response.output_audio.delta — потоковая генерация текста и звука;
• error — сообщение об ошибке.

Благодаря событийной структуре разработчик Realtime API получает полное управление жизненным циклом диалога — от начала речи до ответа модели.

Компоненты Realtime API

Синтез речи

Realtime API поддерживает потоковый синтез речи: агент не ждёт, пока ответ будет сгенерирован целиком, а начинает озвучивать его по частям. Благодаря этому диалог звучит естественно, без длинных пауз и задержек.В Realtime API доступны все голоса Yandex SpeechKit, включая:

• общедоступные голоса — на всех языках, поддерживаемых синтезом SpeechKit;
• уникальные пользовательские голоса, созданные по технологиям Brand Voice Lite и Brand Voice Premium.

📚 Полный каталог общедоступных голосов смотрите в документации.

Распознавание речи

Realtime API поддерживает потоковое распознавание речи. Агент получает текст по мере того, как пользователь говорит, а не после завершения всей фразы. Это ускоряет реакцию и делает диалог естественным и непрерывным.Realtime API использует механизм распознавания SpeechKit. Его можно настраивать и дообучать стандартными средствами SpeechKit. Например, вы можете адаптировать распознавание под терминологию компании или конкретные сценарии.VAD автоматически определяет начало и конец реплик. Это помогает агенту не перебивать пользователя и вовремя переходить к ответу.

Языковая модель

Языковая модель в Realtime API — центральный оркестратор голосового агента. Она получает текст после распознавания речи, анализирует запрос и учитывает контекст до 32k токенов. На основе этого модель определяет следующий шаг:

• ответить самостоятельно;
• вызвать подходящий инструмент (file_search, web_search, MCP, собственные функции).

Модель управляет логикой диалога, выбирает сценарий действий и формирует итоговый ответ. Затем этот ответ озвучивается с помощью TTS. Благодаря этому голосовой агент сохраняет связность, логичность и инициативность в диалоге.

Инструменты

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

• file_search — встроенный инструмент для поиска по документам и данным (RAG, корпоративные базы, FAQ).
• web_search — встроенный инструмент для получения актуальной информации из интернета.
• function calling ****— механизм вызова ваших функций, реализация функции и обработка результата остаётся на стороне разработчика.
• mcp — возможность подключать внешние API по протоколу Model Context Protocol

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

Использование Realtime API: API и SDK

Чтобы создать голосового агента и управлять им в реальном времени, разработчик может использовать API (WebSocket + события) или SDK — готовые клиентские обёртки.Оба подхода дают доступ ко всем возможностям Realtime API, но отличаются уровнем абстракции и удобством разработки.

Использование прямого API (WebSocket + события)

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

Как это работает

1️⃣ Клиент открывает WebSocket-соединение: wss://…/realtime-api/v1?model=gpt://…2️⃣ Далее взаимодействие строится полностью на ивентах:

• клиент отправляет события (input_audio_buffer.append, session.update, response.create);
• сервер возвращает события (speech_started, transcription.completed, output_audio.delta).

3️⃣ Вы сами контролируете:

• передачу аудиопотока;
• обработку входящих событий;
• очерёдность ответов;
• отмену вывода;
• синхронизацию текстовых и голосовых потоков;
• реализацию инструментов Function Calling и MCP.

Когда это удобно

Подходит для таких случаев:

• нужно точное управление пайплайном (VAD, начало/конец речи);
• используются нестандартные компоненты: собственный плеер, кастомные аудиоформаты, тонкие настройки;
• интеграция происходит на устройствах, микросервисах, в браузере;
• SDK недоступен для нужной платформы.

Использование SDK (клиентские библиотеки)

SDK — это высокоуровневая обёртка, которая упрощает работу с сессией и событиями.

Что делает SDK

• автоматически открывает WebSocket-сессию;
• сериализует и десериализует события;
• буферизует поток аудио;
• управляет очередью ответа;
• упрощает обработку инструментария;
• предоставляет удобный API для:
  • подключения микрофона;
  • обработки промежуточных результатов;
  • получения текста и голоса.

В результате разработчик взаимодействует с понятными объектами и callback, а не с сырыми JSON-событиями.

Когда SDK удобнее

• быстрый старт;
• прототипирование;
• клиентские и веб-приложения;
• создание помощников внутри продуктов и UI;
• потребность в простоте и стабильности, а не в тонкой настройке.

Краткое резюме

• API — обеспечивает полный контроль и гибкость.
• SDK — обеспечивает быструю и удобную разработку голосовых агентов без ручного управления буферами, событиями и синхронизацией.

Ссылка :https://practicum.yandex.ru/trainer/yc-ml-aiagents/lesson/b673a75d-e51a-49f6-9dca-927f531769ee/