Configura la sesión con session.update
En esta página
Actualizado el 3 de noviembre de 2026, según las páginas Speech to Speech y Text to Speech de xAI: 28 voces integradas y
turn_detectiondefinido únicamente por sutype(conidle_timeout_msopcional). Fuentes: Speech to Speech · Text to Speech.
Configura tu agente de voz
Una vez establecida la conexión WebSocket y recibido el evento session.created, configura la sesión enviando un mensaje session.update. Aquí es donde defines el comportamiento de tu agente de voz: su personalidad, su voz, las herramientas que puede utilizar y cómo detecta los turnos de palabra.
La estructura completa de session.update
A continuación se muestra un ejemplo detallado de configuración:
{
"type": "session.update",
"session": {
"instructions": "Eres un asistente de voz profesional para un bufete de abogados. Responde de forma concisa y precisa. Utiliza un tono formal.",
"voice": "Rex",
"tools": [
{"type": "web_search"},
{
"type": "function",
"name": "look_up_case",
"description": "Busca un caso de cliente por número",
"parameters": {
"type": "object",
"properties": {
"case_number": {
"type": "string",
"description": "Número de caso del cliente"
}
},
"required": ["case_number"]
}
}
],
"turn_detection": {
"type": "server_vad"
},
"audio": {
"input": {
"format": {"type": "audio/pcm", "rate": 24000}
},
"output": {
"format": {"type": "audio/pcm", "rate": 24000}
}
}
}
}
Los ajustes en detalle
Instrucciones (prompt del sistema)
El campo instructions equivale al prompt del sistema en las API de texto: define la personalidad, el contexto y las restricciones de tu agente de voz. Sin embargo, redactarlo conlleva una restricción específica de la voz: la brevedad. Cada token del prompt se procesa antes de la primera respuesta, y un prompt extenso te costará una latencia notable en el instante en que se establece la llamada. Cíñete a lo esencial y traslada los detalles a la lógica de tu aplicación. Dentro de ese presupuesto ajustado, tres aspectos merecen un lugar prioritario. El tono (formal, amigable, técnico), ya que el agente de voz encarna literalmente tu marca en el oído del cliente. El idioma: especifícalo («responde en inglés»), o el agente podría seguir el idioma del usuario o de la pregunta. Y los límites: qué puede hacer el agente y, sobre todo, qué debe rechazar o derivar a un humano, porque en una llamada telefónica una respuesta fuera de contexto sale antes de que nadie pueda revisarla.
Voz
El ajuste voice acepta una de las 28 voces integradas de xAI (a fecha de 3 de noviembre de 2026), compartidas por el agente de voz y la síntesis de texto a voz, o el ID de una voz personalizada creada con la API de Custom Voices. Los ID de voz no distinguen entre mayúsculas y minúsculas: eve, Eve y EVE hacen referencia a la misma voz. Todas las voces hablan todos los idiomas admitidos.
Las cinco voces originales, tal como las describe xAI:
- eve: enérgica y optimista, acento británico
- ara: cálida y amigable
- rex: segura y clara
- sal: suave y equilibrada
- leo: autoritaria y potente, acento británico
Veintitrés voces más recientes se suman a ellas: carina, zagan, helix, orion, luna, iris, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora y liora. Puedes obtener la lista actual, con el tono y los casos de uso de cada voz, mediante GET /v1/tts/voices o en la página Text to Speech de xAI.
Herramientas
El array tools define las herramientas que el agente puede invocar durante la conversación. Puedes combinar varios tipos: búsqueda web, búsqueda en X, funciones personalizadas, colecciones RAG y servidores MCP. Las siguientes lecciones cubren las herramientas en detalle.
Configuración de audio
El objeto audio establece los formatos de entrada y salida. Puedes utilizar formatos diferentes para la entrada y la salida si tu arquitectura lo requiere (por ejemplo, recibir G.711 desde un sistema telefónico y enviar PCM a un navegador).
Actualiza la sesión en mitad de la conversación
Puedes enviar session.update varias veces durante una conversación. Esto te permite cambiar el comportamiento del agente sobre la marcha:
// Cambia la voz en mitad de la conversación
ws.send(JSON.stringify({
type: "session.update",
session: {
voice: "Ara"
}
}));
// Añade otra herramienta
ws.send(JSON.stringify({
type: "session.update",
session: {
tools: [
{ type: "web_search" },
{ type: "x_search" }
]
}
}));
La documentación de xAI admite explícitamente cambios a mitad de sesión para varios ajustes (idioma de transcripción, palabras clave, sustituciones de pronunciación, transporte de audio), y session.updated los confirma: revísalo para verificar la configuración que se ha aplicado.
Puntos clave
session.updatees el primer mensaje que debes enviar trassession.created- El campo
instructionsdefine la personalidad y las restricciones del agente - Hay disponibles 28 voces integradas (incluidas eve, ara, rex, sal y leo), además de voces personalizadas
- La configuración de audio y las herramientas son personalizables
- Puedes enviar
session.updatevarias veces para cambiar el comportamiento en mitad de la conversación