AIKraft Agents
Главная/Блог/Гайд/Как создать голосового AI-агента:…
Гайд13 мин чтения · 13 ноября 2026 г.

Как создать голосового AI-агента: Полное руководство

Пошаговое руководство по созданию голосового AI-агента на Python с использованием OpenRouter. Разбираем архитектуру, оптимизацию задержек, стоимость и типичные ошибки.

Как создать голосового AI-агента: Полное руководство

Голосовые AI-агенты перестали быть просто технологической диковинкой. Сегодня они способны не просто генерировать текстовые ответы, но и вести полноценный диалог в реальном времени: понимать речь, принимать решения, вызывать внешние инструменты и, что самое важное, начинать говорить до того, как пользователь закончит ждать. В этом руководстве мы разберем полную архитектуру такого агента, от транскрипции до синтеза речи, и покажем, как собрать работающий прототип на Python, используя возможности OpenRouter.

Наш пример — это агент для бронирования столиков в ресторане. Он принимает звонок, преобразует речь в текст, проверяет наличие мест через инструменты (tools) и возвращает ответ голосом. Ключевая особенность нашего подхода — потоковая передача (streaming) предложений в синтезатор речи (TTS) по мере их генерации языковой моделью (LLM). Это позволяет значительно сократить время ожидания для пользователя, создавая эффект естественного диалога.

01Как работает один оборот голосового агента

Процесс взаимодействия голосового агента с пользователем можно разбить на четкий цикл. Когда абонент произносит фразу, система должна выполнить несколько этапов обработки, прежде чем ответ будет озвучен. Это не просто цепочка «вопрос-ответ», а сложный конвейер, где каждый этап влияет на общую задержку (latency).

Сначала речь абонента преобразуется в текст с помощью модели Speech-to-Text (STT). Затем этот текст передается в LLM, которая определяет намерение пользователя. Если для выполнения запроса требуется внешняя информация (например, проверка свободных столиков), модель вызывает функцию (tool calling). Приложение исполняет эту функцию, получает результат и отправляет его обратно в модель. Только после этого LLM формирует финальный ответ, который снова преобразуется в речь через Text-to-Speech (TTS).

Схема работы голосового AI-агента: от речи к тексту и обратно
Схема работы голосового AI-агента: от речи к тексту и обратно

Главная проблема такого подхода — задержка. Если ждать, пока LLM сгенерирует весь ответ целиком, прежде чем отправлять его в TTS, пользователь будет молчать в микрофон несколько секунд. Чтобы этого избежать, мы используем потоковую генерацию. Как только LLM завершает предложение (определяется по знакам препинания и пробелам), этот фрагмент сразу отправляется в TTS. Пока синтезируется первая часть ответа, модель продолжает генерировать вторую. Это перекрестное выполнение (overlap) критически важно для ощущения «живого» разговора.

02Сборка голосового агента на Python

Для реализации мы будем использовать Python 3.10 или новее. Нам понадобятся три основные модели через API OpenRouter:

  • STT: elevenlabs/scribe-v2 для транскрипции речи.
  • LLM: openai/gpt-6-luna для понимания контекста и принятия решений.
  • TTS: elevenlabs/eleven-flash-v2.5 для синтеза голоса.

Установите необходимые библиотеки и задайте переменную окружения с вашим API-ключом OpenRouter:

terminalbash
pip install requests
export OPENROUTER_API_KEY="your-api-key"

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

terminalpython
import base64
import io
import json
import os
import re
import wave
from concurrent.futures import ThreadPoolExecutor
from datetime import date
import requests

API = "https://openrouter.ai/api/v1"
AUTH = {"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}"}
STT = "elevenlabs/scribe-v2"
LLM = "openai/gpt-6-luna"
TTS = "elevenlabs/eleven-flash-v2.5"
PCM_RATE = 24000

def system_prompt():
    today = date.today()
    return (f"You are the phone receptionist for Luigi's restaurant. "
            f"Today is {today.strftime('%A, %B %d, %Y')}. "
            "Keep answers short and spoken: "
            "no markdown, and say times in words. "
            "Check availability before offering a table. "
            "Only book after the caller agrees and provides a name. "
            "Do not claim to send confirmation texts.")

def tool(name, description, properties):
    return {
        "type": "function",
        "function": {
            "name": name,
            "description": description,
            "parameters": {
                "type": "object",
                "properties": properties,
                "required": list(properties),
            },
        },
    }

DATE = {"type": "string", "description": "YYYY-MM-DD"}
TIME = {"type": "string", "description": "HH:MM, 24-hour"}
PARTY = {"type": "integer", "minimum": 1}

TOOLS = [
    tool("check_availability", "Find open tables near the requested time",
         {"date": DATE, "time": TIME, "party_size": PARTY}),
    tool("book_table", "Book only after the caller accepts a time and gives a name",
         {"date": DATE, "time": TIME, "party_size": PARTY, "name": {"type": "string"}}),
]

def run_tool(name, args):
    # Mock booking service; replace with a real reservation backend.
    if name == "check_availability":
        return {"open_times": ["17:45", "20:15"] if args["party_size"] >= 6 else [args["time"]]}
    if name == "book_table":
        allowed = ["17:45", "20:15"] if args["party_size"] >= 6 else [args["time"]]
        if args["time"] in allowed:
            return {"booked": True, "reference": "XJ47Q"}
        return {"booked": False, "error": "Time unavailable"}
    return {"error": f"Unknown tool: {name}"}

def to_wav(pcm, rate):
    if len(pcm) % 2 != 0:
        raise ValueError("PCM audio must contain whole 16-bit samples")
    output = io.BytesIO()
    with wave.open(output, "wb") as wav:
        wav.setnchannels(1)
        wav.setsampwidth(2)
        wav.setframerate(rate)
        wav.writeframes(pcm)
    return output.getvalue()

def speak(text, voice="sarah"):
    if not text.strip():
        return "", PCM_RATE
    response = requests.post(
        f"{API}/audio/speech",
        headers=AUTH,
        stream=True,
        timeout=60,
        json={
            "model": TTS,
            "input": text,
            "voice": voice,
            "response_format": "pcm",
            "provider": {"options": {"elevenlabs": {"output_format": "pcm_24000"}}},
        },
    )
    response.raise_for_status()
    if not response.headers.get("Content-Type", "").startswith("audio/pcm"):
        raise ValueError("Expected raw PCM audio from TTS")
    pcm = b"".join(response.iter_content(4096))
    if not pcm:
        raise ValueError("TTS returned no audio")
    return pcm, PCM_RATE

def transcribe(wav):
    response = requests.post(
        f"{API}/audio/transcriptions",
        headers=AUTH,
        timeout=60,
        json={
            "model": STT,
            "language": "en",
            "input_audio": {
                "data": base64.b64encode(wav).decode("ascii"),
                "format": "wav",
            },
        },
    )
    response.raise_for_status()
    return response.json()["text"].strip()

def choose_tool_calls(messages):
    # Resolve possible tools before starting any paid TTS requests.
    response = requests.post(
        f"{API}/chat/completions",
        headers=AUTH,
        timeout=60,
        json={
            "model": LLM,
            "messages": messages,
            "tools": TOOLS,
            "tool_choice": "auto",
            "reasoning": {"effort": "none"},
            "max_tokens": 300,
        },
    )
    response.raise_for_status()
    message = response.json()["choices"][0]["message"]
    return message.get("tool_calls") or []

def stream_reply(messages):
    # This request has no tools, so sentences can safely go to TTS.
    pending, finish = "", None
    with requests.post(
        f"{API}/chat/completions",
        headers=AUTH,
        stream=True,
        timeout=60,
        json={
            "model": LLM,
            "messages": messages,
            "reasoning": {"effort": "none"},
            "max_tokens": 300,
            "stream": True,
        },
    ) as response:
        response.raise_for_status()
        response.encoding = "utf-8"
        for line in response.iter_lines(decode_unicode=True):
            if not line or not line.startswith("data: {"):
                continue
            chunk = json.loads(line[6:])
            if chunk.get("error"):
                raise RuntimeError(f"stream error: {chunk['error']}")
            choices = chunk.get("choices")
            if not choices:
                continue
            finish = choices[0].get("finish_reason") or finish
            pending += (choices[0].get("delta") or {}).get("content") or ""
            
            # Wait for whitespace; a buffer ending in "3." may still become "3.14".
            while match := re.search(r"[.!?]\s", pending):
                sentence = pending[:match.end()].strip()
                if sentence:
                    yield sentence
                pending = pending[match.end():]
        
        if finish == "length":
            raise RuntimeError("reply cut off at max_tokens")
        if pending.strip():
            yield pending.strip()

def run_turn(caller_wav, messages):
    heard = transcribe(caller_wav)
    messages.append({"role": "user", "content": heard})
    
    # Tool selection can repeat when the model needs several tool results.
    for _ in range(5):
        calls = choose_tool_calls(messages)
        if not calls:
            break
        messages.append({"role": "assistant", "content": None, "tool_calls": calls})
        for call in calls:
            try:
                args = json.loads(call["function"]["arguments"])
                result = run_tool(call["function"]["name"], args)
            except (ValueError, TypeError, KeyError) as exc:
                result = {"error": str(exc)}
            messages.append({
                "role": "tool",
                "tool_call_id": call["id"],
                "content": json.dumps(result),
            })
    else:
        raise RuntimeError("Too many tool calls")

    sentences, jobs = [], []
    with ThreadPoolExecutor(max_workers=4) as pool:
        for sentence in stream_reply(messages):
            sentences.append(sentence)
            jobs.append(pool.submit(speak, sentence))
    
    audio = [job.result() for job in jobs]
    if not sentences:
        raise RuntimeError("LLM returned no spoken response")
    
    rates = {rate for _, rate in audio}
    if rates != {PCM_RATE}:
        raise ValueError("Inconsistent TTS sample rates")
    
    spoken = " ".join(sentences)
    messages.append({"role": "assistant", "content": spoken})
    pcm = b"".join(chunk for chunk, _ in audio)
    return heard, spoken, to_wav(pcm, PCM_RATE)

if __name__ == "__main__":
    caller_lines = [
        "Hi, do you have a table for six this Saturday at seven thirty?",
        "Eight fifteen works. The name is Siobhan Okafor.",
        "Can you text the confirmation to four one five, "
        "five five five, zero one eight two?",
        "No, that's everything. Thanks, bye."
    ]
    messages = [{"role": "system", "content": system_prompt()}]
    
    for turn, line in enumerate(caller_lines, 1):
        pcm, rate = speak(line, voice="george")
        heard, said, reply = run_turn(to_wav(pcm, rate), messages)
        with open(f"agent_{turn}.wav", "wb") as file:
            file.write(reply)
        print(f"caller: {heard}\nagent: {said}\n")
Темная тема интерфейса разработки голосового агента
Темная тема интерфейса разработки голосового агента

03Почему эта архитектура работает и где она ломается

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

Проблема двусторонняя. Если модель напишет «8:15», TTS может прочитать это как «восемь часов пятнадцать», что верно. Но если абонент скажет «восемь пятнадцать», STT-модель может транскрибировать это как «815». В нашем тесте LLM успешно поняла контекст благодаря истории диалога, но в других случаях это может привести к ошибкам. Всегда просите подтверждать важные данные (имя, телефон) перед действием.

Еще один критический аспект — безопасность действий. Агент не должен обещать бронирование, если оно еще не совершено. В коде выше функция run_tool для book_table возвращает успешный статус только если время действительно свободно. В реальном приложении эта функция должна обращаться к базе данных, блокировать столик и только потом возвращать ID бронирования. Иначе агент может «создать» бронь в разговоре, но не записать ее в систему.

💡
Совет по оптимизации. Обратите внимание, что мы используем reasoning: {"effort": "none"} в запросах к LLM. Это отключает сложные цепочки рассуждений (Chain-of-Thought), которые увеличивают время генерации. Для голосового агента важна скорость, а не глубокий анализ, поэтому простой, быстрый ответ предпочтительнее.

04Скорость работы голосового агента

Время отклика — главный враг пользовательского опыта. В нашем тесте мы измеряли серверное время до появления первого аудиобайта (Time to First Audio, TTFA). Это метрика, которую пользователь чувствует как «задержку перед началом речи».

Результаты по 12 оборотам в трех диалогах показали медианное время 1.9 секунды. Однако есть существенная разница между типами оборотов:

  • Без вызова инструментов: 1.4 секунды. Модель сразу генерирует ответ.
  • С вызовом инструментов: 2.4 секунды. Требуется дополнительный запрос к LLM для выбора функции, выполнение функции, и второй запрос к LLM для формирования ответа на основе результата.
Визуализация процесса RAG и реранкинга для контекста
Визуализация процесса RAG и реранкинга для контекста

Таблица ниже демонстрирует распределение времени по этапам:

d>262 мс
Этап С вызовом инструмента Без вызова инструмента
Speech-to-text (Scribe v2) 549 мс 391 мс
LLM selects tool 736 мс -
LLM answer, first token 685 мс 706 мс
Text-to-speech, first byte 208 мс
Оценочное время до первого аудио 2.4 с 1.4 с

Обратите внимание, что эти цифры — только серверная обработка. В реальном мире добавляется задержка сети, время на определение конца речи абонента (VAD) и буферизация аудио. Пример кода делает два запроса к LLM на каждый оборот (один для проверки инструментов, один для потока), что может увеличить задержку. Для продакшена рекомендуется использовать LiveKit Agents, который оптимизирует этот цикл.

05Стоимость голосового агента

Голосовые агенты могут быть дорогими, если не контролировать длину ответов. В нашем тесте синтез речи (TTS) составил около 90% всех затрат. Это логично: генерация аудио требует больше вычислительных ресурсов, чем генерация текста.

При промо-ценах, доступных во время тестирования (октябрь 2026), разговор из четырех оборотов стоил около $0.013 за минуту обработанной речи. Чтобы снизить стоимость, старайтесь делать ответы агента краткими. Длинные монологи не только дороже, но и менее эффективны в голосовом интерфейсе.

Темная тема визуализации данных о задержках
Темная тема визуализации данных о задержках
⚠️
Важно. Транскрипция имен сложнее, чем чисел. В нашем тесте имя «Siobhan Okafor» могло быть распознано с ошибкой. Всегда проектируйте сценарии так, чтобы агент просил подтверждение сложных данных. Не принимайте критических действий (списание денег, бронирование) без явного подтверждения от пользователя.

06Какие модели выбрать?

Выбор моделей зависит от баланса между качеством, скоростью и ценой.

Speech-to-Text (STT)

elevenlabs/scribe-v2 показал высокую точность в нашем тесте. Альтернативы, такие как Whisper от OpenAI, могут быть дешевле, но Scribe лучше справляется с шумом и естественной речью. Для русскоязычных проектов стоит также рассмотреть модели, специально обученные на русском языке, так как они лучше понимают акценты и специфические термины.

LLM

Для диалоговых агентов важна не только логика, но и способность следовать инструкциям (instruction following). openai/gpt-6-luna отлично справилась с ролью официанта. Для локального запуска в РФ, где доступ к некоторым API ограничен, можно использовать модели через прокси или локальные LLM, такие как Llama 3 или Mistral, но они потребуют более тщательной настройки промптов для стабильного вызова инструментов.

Text-to-Speech (TTS)

elevenlabs/eleven-flash-v2.5 обеспечивает быструю генерацию с естественной интонацией. Если скорость критичнее качества, можно использовать более простые модели. Однако для создания эффекта присутствия важно, чтобы голос не звучал роботизированно.

07Запуск с LiveKit Agents

Приведенный выше код работает с файлами WAV, что удобно для тестирования. Но для реального звонка нужна обработка аудио в реальном времени. Библиотека LiveKit Agents позволяет обрабатывать входящий аудио-поток, управлять прерываниями (когда пользователь перебивает агента) и отправлять аудио обратно в звонок.

LiveKit берет на себя сложную работу с буферизацией, VAD (Voice Activity Detection) и сетевыми задержками. Интеграция нашего Python-кода с LiveKit означает, что вместо сохранения файлов agent_1.wav, мы будем отправлять байты аудио напрямую в сессию звонка. Это позволяет реализовать функцию «перебивания» (interruptibility), когда агент замолкает, если пользователь начинает говорить.

08Типичные ошибки

  1. Отсутствие обработки ошибок в инструментах. Если база данных недоступна, агент должен сообщить об этом, а не зависнуть или выдать ошибку.
  2. Игнорирование контекста. LLM не помнит предыдущие сообщения автоматически. Вы должны явно передавать историю диалога в каждом запросе. Как мы видели, объем промпта растет с каждым оборотом, что может привести к превышению лимита токенов.
  3. Слишком длинные ответы. Длинные тексты увеличивают время TTS и стоимость. Разбивайте ответы на короткие предложения, которые можно отправлять в TTS по мере готовности.
  4. Отсутствие прерываний. В голосовом интерфейсе пользователь ожидает возможности перебить. Архитектура должна позволять остановить генерацию аудио, если поступил новый голосовой ввод.

09Нужны ли модели Speech-to-Speech?

Существуют модели, которые преобразуют речь сразу в речь, минуя текст. Теоретически, это должно быть быстрее. Однако на данный момент модели STT+LLM+TTS обеспечивают большую гибкость: мы можем использовать мощные LLM для логики, проверять ответы и интегрировать внешние инструменты. Speech-to-Speech модели пока уступают в качестве понимания сложных инструкций и интеграции с бизнес-логикой. Поэтому гибридный подход остается золотым стандартом.

10Что это значит на практике

Создание голосового AI-агента — это не просто вызов API. Это проектирование системы, которая должна быть быстрой, надежной и естественной. Используя OpenRouter, вы получаете доступ к лучшим моделям для каждого этапа конвейера. Ключевые выводы:

  • Потоковая генерация обязательна. Не ждите конца ответа LLM, чтобы начать говорить.
  • Контролируйте формат ответа. Запретите markdown и требуйте устного стиля в промптах.
  • Тестируйте на реальных данных. Транскрипция имен и чисел требует проверки и подтверждения.
  • Оптимизируйте стоимость. TTS — основная статья расходов. Делайте ответы краткими.

Этот код служит прочным фундаментом. Для перехода к продакшену добавьте обработку ошибок, интеграцию с LiveKit для реального времени и, возможно, кэширование часто используемых ответов. Голосовые агенты открывают новые возможности для автоматизации обслуживания клиентов, и правильная архитектура с самого начала сэкономит вам время и деньги в будущем.

11Часто задаваемые вопросы

Можно ли запустить это локально?
Да, вы можете использовать локальные LLM (например, через Ollama) и локальные STT/TTS модели. Однако это потребует мощного оборудования (GPU) и настройки прокси для доступа к некоторым облачным сервисам, если вы находитесь в РФ.

Как обработать перебивание пользователя?
В текущем коде этого нет. Для реализации нужно использовать LiveKit или аналогичный фреймворк, который позволяет прерывать поток TTS при обнаружении голоса в канале пользователя.

Какие языки поддерживаются?
Модели ElevenLabs и OpenAI хорошо работают с английским. Для русского языка проверьте поддержку в конкретных моделях STT и TTS, так как качество может варьироваться.

Источник: OpenRouter ↗