Domina los eventos de WebSocket
En esta página
Una conversación compuesta por eventos JSON
En esencia, un intercambio de voz con el Voice Agent es simplemente un flujo de mensajes JSON que circulan en ambas direcciones a través de la conexión WebSocket. Cada mensaje incluye un campo type que indica de qué se trata. Mientras no conozcas este vocabulario, tu cliente funcionará por suerte. En cuanto lo domines, sabrás exactamente dónde intervenir para cortar una respuesta, mostrar una transcripción o recuperarte de un error.
Los eventos se dividen en dos familias, según la dirección en la que viajan. Los que tú envías dirigen la sesión; los que recibes te informan de lo que ocurre en el servidor.
Lo que envía tu aplicación
Tus mensajes salientes cubren cuatro necesidades: configurar la sesión, alimentar el búfer de audio, gestionar el historial de la conversación y controlar la generación de respuestas.
| Evento | Propósito |
|---|---|
session.update | Configura o reconfigura la sesión (voz, instrucciones, herramientas, VAD, formato de audio) |
input_audio_buffer.append | Envía un fragmento de audio codificado en base64 de forma continua mientras el usuario habla |
input_audio_buffer.commit | Confirma el contenido actual del búfer como mensaje del usuario; solo necesario en modo manual |
input_audio_buffer.clear | Vacía el búfer de audio sin procesarlo |
conversation.item.create | Añade un elemento a la conversación: un mensaje de texto, historial anterior o el resultado de una llamada a función |
conversation.item.delete | Elimina un elemento de la conversación por su ID |
response.create | Solicita al modelo que genere una respuesta; automático en modo VAD, explícito en modo manual |
response.cancel | Cancela una respuesta que se está generando |
Dos de estos mensajes merecen una atención especial. conversation.item.create es la forma de inyectar contexto: es lo que utilizas para restaurar el historial de una llamada anterior al inicio de una nueva sesión. En cuanto a input_audio_buffer.clear, resulta útil cuando el usuario claramente no ha dicho nada que merezca la pena procesar (un carraspeo captado por un micrófono demasiado sensible) y prefieres empezar de cero con un búfer limpio en lugar de dejar que el modelo interprete ruido.
Lo que envía el servidor
El flujo entrante es más activo, ya que ofrece un comentario en tiempo real de cada paso del procesamiento.
| Evento | Significado |
|---|---|
session.created | La sesión está abierta |
session.updated | Se ha aplicado una actualización de configuración |
conversation.created | La conversación está configurada |
input_audio_buffer.speech_started | El VAD detecta que el usuario ha empezado a hablar |
input_audio_buffer.speech_stopped | El VAD detecta que el usuario ha dejado de hablar |
input_audio_buffer.committed | El búfer de audio se ha confirmado, ya sea por el VAD o manualmente |
response.created | Se está generando una respuesta |
response.output_audio.delta | Un fragmento de audio de la respuesta, en base64 |
response.output_audio.done | El audio de la respuesta está completo |
response.output_audio_transcript.delta | La transcripción de texto del audio, transmitida en flujo |
response.done | La respuesta ha terminado completamente |
conversation.item.input_audio_transcription.completed | La transcripción del mensaje del usuario está disponible |
response.text.delta | Texto transmitido en flujo, para respuestas que no son de voz |
response.function_call_arguments.delta | Los argumentos de una llamada a función, transmitidos en flujo |
response.function_call_arguments.done | La llamada a función está completa y lista para ejecutarse |
error | Se ha producido un error; la mayoría son recuperables |
Este último requiere una advertencia. Recibir un evento error no significa que la sesión se haya perdido. Según la referencia de xAI, la mayoría de los errores son recuperables y la sesión permanece abierta, por lo que un cliente que cierre la conexión ante el primer error romperá una conversación que podría haber continuado. Regístralo, informa al usuario si es necesario, pero mantén el socket abierto.
La estructura básica de un cliente
En la práctica, todo se reduce a un switch sobre msg.type. Esta es la forma mínima de un cliente en JavaScript:
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
switch (msg.type) {
case "session.created":
// Envía session.update con la configuración
break;
case "input_audio_buffer.speech_started":
// El usuario está hablando: detén el audio de respuesta que se está reproduciendo
break;
case "response.output_audio.delta":
// Decodifica el base64 y reproduce el audio
playAudioChunk(msg.delta);
break;
case "response.function_call_arguments.done":
// Ejecuta la función y envía el resultado de vuelta
handleFunctionCall(msg);
break;
case "error":
console.error("Error del Voice Agent:", msg.error);
break;
}
};
Cuatro ramas son suficientes para ejecutar un agente: configurar al abrir la sesión, reaccionar cuando el usuario empieza a hablar, reproducir el audio entrante y ejecutar funciones. Los demás eventos enriquecen la interfaz y pueden esperar a una segunda iteración.
La parte delicada: las interrupciones
El «barge-in», cuando el usuario empieza a hablar mientras el agente aún está respondiendo, es donde se nota una implementación descuidada. El servidor cancela la respuesta actual por su cuenta y comienza a generar una nueva a partir de lo que acaba de oír. Pero mientras el servidor ha dejado de enviar datos, tu aplicación todavía tiene varios segundos de audio ya recibido en su búfer de salida.
Si no haces nada, el usuario seguirá oyendo la frase que acaba de interrumpir mientras habla por encima, y el agente dará la impresión de no estar escuchando. Por tanto, en cuanto recibas speech_started, detén el audio que se está reproduciendo, vacía el búfer de salida para no reproducir sonido obsoleto y deja que el servidor procese la nueva entrada. Estos dos pasos requieren pocas líneas de código y marcan la diferencia entre un agente al que puedes interrumpir y uno que habla al vacío.
Puntos clave
- Los eventos del cliente cubren la configuración, el envío de audio, la gestión de la conversación y el control de las respuestas
- Los eventos del servidor informan de la detección de voz, fragmentos de audio, transcripciones y llamadas a funciones
- El VAD gestiona las interrupciones (barge-in) automáticamente
- La mayoría de los eventos
errorson recuperables: no cierres la conexión, gestiona el error - En modo manual, debes llamar explícitamente a
commity luego aresponse.create