WebSocket multicontexto
Esta guía te muestra cómo crear agentes de voz en tiempo real con la API de WebSocket multicontexto.
Orquestar agentes de voz mediante esta API de WebSocket multicontexto es una tarea compleja recomendada para desarrolladores avanzados. Para una solución más gestionada, considera explorar nuestro producto Agents Platform, que simplifica muchos de estos retos.
Descripción general
Crear agentes de voz ágiles requiere poder gestionar flujos de audio de forma dinámica, manejar las interrupciones adecuadamente y mantener un habla natural durante los turnos de conversación. Nuestra API de WebSocket multicontexto para Texto a Voz (TTS) está diseñada específicamente para estos casos.
Esta API amplía nuestra funcionalidad estándar de WebSocket para TTS al introducir el concepto de «contextos». Cada contexto funciona como un flujo independiente de generación de audio dentro de una única conexión WebSocket. Esto te permite:
- Gestionar varias líneas de habla simultáneamente (por ejemplo, el agente habla mientras prepara una respuesta a una interrupción del usuario).
- Gestionar sin interrupciones las intervenciones del usuario cerrando un contexto de habla existente e iniciando uno nuevo.
- Mantener la coherencia prosódica de los enunciados dentro del mismo contexto lógico.
- Optimizar el uso de recursos cerrando selectivamente los contextos que ya no necesites.
La API de WebSocket multicontexto está optimizada para aplicaciones de voz y no está diseñada para generar varios flujos de audio no relacionados de forma simultánea. Por ello, cada conexión está limitada a 5 contextos simultáneos.
Esta guía te explicará cómo conectarte al WebSocket multicontexto, gestionar contextos y aplicar buenas prácticas para crear agentes de voz atractivos.
Buenas prácticas
Estas buenas prácticas son esenciales para crear agentes de voz ágiles y eficientes con nuestra API de WebSocket multicontexto.
Usa una sola conexión WebSocket
Establece una conexión WebSocket para cada sesión de usuario final. Esto reduce la sobrecarga y la latencia en comparación con crear varias conexiones. Dentro de esta única conexión, puedes gestionar varios contextos para distintas partes de la conversación.
Transmite las respuestas por bloques y genera frases
Al generar respuestas largas, transmite el texto en bloques más pequeños y usa la marca flush: true
al final de frases completas. Esto mejora la calidad del audio generado y la capacidad de respuesta.
Gestiona las interrupciones adecuadamente
Transmite texto a un contexto hasta que se produzca una interrupción; después, crea un contexto nuevo y cierra el existente. Este enfoque garantiza transiciones fluidas cuando cambia el flujo de la conversación.
Gestiona el ciclo de vida de los contextos
Cierra cuanto antes los contextos que no uses. El servidor puede mantener hasta 5 contextos simultáneos por conexión, pero debes cerrar los contextos cuando ya no los necesites.
Evita los tiempos de espera de los contextos
De forma predeterminada, los contextos agotan el tiempo de espera tras 20 segundos y se cierran automáticamente. El tiempo de inactividad es un parámetro a nivel de WebSocket que se aplica a todos los contextos y puede ser de hasta 180 segundos si es necesario. Envía un mensaje de texto vacío a un contexto para reiniciar el contador del tiempo de espera.
Gestión de interrupciones
Cuando un usuario interrumpa a tu agente, debes cerrar el contexto actual y crear uno nuevo:
Mantener activo un contexto
Los contextos agotan automáticamente el tiempo de espera tras 20 segundos de inactividad de forma predeterminada. Si necesitas mantener un contexto activo sin generar texto (por ejemplo, durante un retraso de procesamiento), puedes enviar un mensaje de texto vacío para reiniciar el contador del tiempo de espera.
Cerrar la conexión WebSocket
Cuando termine la conversación, puedes limpiar todos los contextos cerrando el socket:
Ejemplo completo de agente conversacional
Requisitos
- Una cuenta de ElevenLabs con una clave de API (descubre cómo encontrar tu clave de API).
- Python o Node.js (u otro entorno de ejecución de JavaScript) instalado en tu equipo.
- Familiaridad con la comunicación mediante WebSocket. Te recomendamos leer nuestra guía sobre streaming WebSocket estándar para conocer los conceptos básicos.
Configuración
Instala las dependencias necesarias para el lenguaje que hayas elegido:
Crea un archivo .env en el directorio de tu proyecto para almacenar tu clave de API: