Implementa un agente de voz con guardrails (Next.js)

Antes de escribir cualquier código, invoca la habilidad /agents para aprender los patrones correctos del SDK de ElevenLabs.

1. package.json

• Añade las dependencias @elevenlabs/react (con soporte onGuardrailTriggered) y @elevenlabs/elevenlabs-js.

2. app/api/agent/route.ts

Ruta segura que crea o carga un agente de voz con guardrails. Nunca expongas ELEVENLABS_API_KEY al cliente.

• POST crea un nuevo agente de voz con valores predeterminados sensatos (nombre, primer mensaje, voz TTS). Usa la plantilla CLI voice-only como referencia para la forma del agente.
• GET carga un agente existente por agentId.
• Usa un prompt de sistema de asistente bancario con una sección # Guardrails que contenga reglas de comportamiento.
• Habilita los guardrails: un guardrail personalizado (por ejemplo, sin recomendaciones de inversión) que termina la conversación cuando se activa, además de protección contra prompt-injection.
• Configura como voz-primero: voz y modelo TTS reales, solo texto deshabilitado, entrada de texto del widget deshabilitada.
• Para agentes en inglés (language: "en"), usa tts.modelId: "eleven_flash_v2". No uses eleven_flash_v2_5 para agentes solo en inglés, o la creación del agente podría fallar la validación.
• Habilita los eventos del cliente para la renderización de transcripciones, audio y guardrail_triggered.
• Devuelve { agentId, agentName }.

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

Endpoint GET seguro que devuelve un token de conversación nuevo para un agentId dado. Nunca expongas ELEVENLABS_API_KEY al cliente.

4. app/page.tsx

Página de demostración mínima de guardrails de voz con Next.js.

• Usa ConversationProvider de @elevenlabs/react.
• Usa los hooks de conversación granulares useConversationControls, useConversationStatus y useConversationMode.
• Registra onGuardrailTriggered en el proveedor.
• Muestra un botón Create Agent y un campo de entrada de ID de agente editable. Rellena automáticamente al crear; permite pegar un ID diferente para cargarlo en su lugar.
• Inicia sesiones de voz con un token nuevo de /api/conversation-token. Solicita acceso al micrófono antes de iniciar.
• Confía en la inferencia del tipo de conexión del SDK al iniciar la sesión; no codifiques connectionType: "webrtc" a menos que haya una razón específica.
• Muestra un interruptor de Inicio/Parada, estado de conexión y transcripción de conversación en curso (añade mensajes, no reemplaces).
• Muestra prompts de ejemplo para probar el guardrail (por ejemplo, preguntar sobre inversiones o Bitcoin).
• Si el guardrail se activa, muestra un mensaje de estado persistente y añade una nota a la transcripción.
• Maneja los errores con elegancia y permite la reconexión. Mantén la interfaz de usuario simple y voz-primero.