Голосовой агент на Next.js

Урок 3 из 20 курса «ElevenLabs: примеры»: официальный курс ElevenLabs Cookbook (Илевен Лабс) на русском языке. Этот урок бесплатный.

Прежде чем писать какой-либо код, вызовите навык /agents, чтобы изучить правильные паттерны ElevenLabs SDK.

1. package.json

  • Добавьте @elevenlabs/react (с поддержкой onGuardrailTriggered) и зависимости @elevenlabs/elevenlabs-js.

2. app/api/agent/route.ts

Защищенный маршрут, который создает или загружает голосового агента с guardrails. Никогда не раскрывайте ELEVENLABS_API_KEY клиенту.

  • POST создает нового голосового агента с разумными значениями по умолчанию (имя, первое сообщение, голос TTS). Используйте шаблон CLI voice-only в качестве эталона для структуры агента.
  • GET загружает существующего агента по agentId.
  • Используйте системный prompt банковского ассистента с разделом # Guardrails, содержащим правила поведения.
  • Включите guardrails: пользовательский guardrail (например, отсутствие инвестиционных рекомендаций), который прерывает разговор при срабатывании, плюс защита от prompt-инъекций.
  • Настройте как voice-first: реальный голос и модель TTS, только текст отключен, текстовый ввод виджета отключен.
  • Для англоязычных агентов (language: "en") используйте tts.modelId: "eleven_flash_v2". Не используйте eleven_flash_v2_5 для агентов, работающих только на английском языке, иначе создание агента может не пройти валидацию.
  • Включите клиентские события для рендеринга транскрипта, аудио и guardrail_triggered.
  • Верните { agentId, agentName }.

3. app/api/conversation-token/route.ts

Защищенный GET endpoint, который возвращает свежий conversation token для заданного agentId. Никогда не раскрывайте ELEVENLABS_API_KEY клиенту.

4. app/page.tsx

Минимальная Next.js демо-страница voice guardrails.

  • Используйте ConversationProvider из @elevenlabs/react.
  • Используйте гранулярные conversation hooks useConversationControls, useConversationStatus и useConversationMode.
  • Зарегистрируйте onGuardrailTriggered на провайдере.
  • Покажите кнопку Create Agent и редактируемое поле ввода agent-id. Автоматически заполняйте при создании; разрешите вставку другого id для его загрузки.
  • Начинайте голосовые сессии со свежим token из /api/conversation-token. Запросите доступ к микрофону перед началом.
  • Полагайтесь на вывод типа соединения SDK при запуске сессии; не прописывайте жестко connectionType: "webrtc", если нет особой причины.
  • Покажите переключатель Start/Stop, статус соединения и текущий транскрипт разговора (добавляйте сообщения, не заменяйте).
  • Представьте примеры prompts для тестирования guardrail (например, вопросы об инвестициях или Bitcoin).
  • Если guardrail срабатывает, покажите постоянное статусное сообщение и добавьте примечание к транскрипту.
  • Обрабатывайте ошибки корректно и разрешите переподключение. Сохраняйте UI простым и voice-first.

Полезные гиды