Ir al contenido principal
Español— Elegir un idioma
Menú

Configurar una sesión de voz

Lección 2 de 14 Actualizado el 3 de noviembre de 2026 Intermedio
En esta página
  1. El mensaje que lo define todo: session.update
  2. Escribe instrucciones para el oído, no para la vista
  3. Detección de turnos
  4. Elige el formato de audio adecuado
  5. Proporciona herramientas al agente
  6. Puntos clave

Actualizado el 3 de noviembre de 2026, basándose en la página Speech to Speech de xAI y en la guía de indicaciones de voz. Fuentes: Speech to Speech · Prompting Guide.

El mensaje que lo define todo: session.update

Una vez establecida la conexión WebSocket, aún no ocurre nada. El mensaje session.update es el que dota al agente de su carácter: la voz que utiliza, las instrucciones que sigue, cómo detecta los turnos de palabra y qué herramientas puede invocar. Piensa en ello como el acta de nacimiento de la sesión. Todo lo demás en la conversación se deriva de este mensaje.

{
  "type": "session.update",
  "session": {
    "instructions": "You are a professional voice assistant for an e-commerce company. Keep your answers short and help customers with their orders.",
    "voice": "Ara",
    "turn_detection": {
      "type": "server_vad"
    },
    "audio": {
      "input": { "format": { "type": "audio/pcm", "rate": 24000 } },
      "output": { "format": { "type": "audio/pcm", "rate": 24000 } }
    },
    "tools": [
      { "type": "web_search" }
    ]
  }
}

El servidor lo confirma con un evento session.updated. No es necesario enviar este mensaje una única vez. Puedes volver a enviarlo en mitad de la conversación para modificar un parámetro sobre la marcha; por ejemplo, para cambiar de voz cuando la llamada pasa del departamento de ventas al de soporte técnico, sin necesidad de cortar la conexión en ningún momento.

Escribe instrucciones para el oído, no para la vista

El campo instructions desempeña el papel del prompt del sistema. Úsalo para definir la personalidad del agente (formal, informal, técnica), los temas que puede tratar, las restricciones sobre sus respuestas (longitud, formato, idioma) y el contexto empresarial necesario: el nombre de tu empresa, la gama de productos y los procedimientos internos.

La trampa reside en que lo que funciona bien en un prompt escrito suele dar lugar a un agente de voz deficiente. Si se le deja actuar por su cuenta, el modelo genera respuestas de diez líneas. Leídas en voz alta, se hacen interminables y el usuario desconecta antes de que terminen. Por tanto, pide explícitamente respuestas breves y directas. Si tu aplicación funciona en un único idioma, indícalo; de lo contrario, el agente podría cambiar de idioma para adaptarse al acento del interlocutor. Además, especifica qué debe hacer cuando no entienda algo: una instrucción como «haz una pregunta de clarificación en lugar de adivinar» evita que un número de pedido mal escuchado desencadene una búsqueda inútil. La guía de indicaciones de voz de xAI sugiere incluso una estructura de cinco partes (rol y persona, objetivo, flujo de conversación, límites y escalado, estilo de voz) y recomienda usar una o dos frases cortas por turno, a menos que el interlocutor solicite más detalles.

Detección de turnos

El bloque turn_detection decide quién habla y cuándo. La documentación de xAI solo ofrece dos ajustes para ello. El primero es type. En el modo "server_vad", el servidor detecta por sí mismo el final de cada intervención, confirma el audio, inicia la respuesta y gestiona las interrupciones: tú solo tienes que enviar audio mediante input_audio_buffer.append. El segundo ajuste, idle_timeout_ms, es opcional. Si el usuario guarda silencio durante ese número de milisegundos tras una respuesta, el servidor le incita a hablar, y lo vuelve a hacer tras cada nuevo silencio de la misma duración.

{
  "turn_detection": { "type": "server_vad", "idle_timeout_ms": 8000 }
}

No existe ningún umbral de sensibilidad ni duración de silencio que debas ajustar. Los parámetros threshold, silence_duration_ms y prefix_padding_ms que verás en ejemplos escritos para la API Realtime de OpenAI no aparecen en la documentación de xAI.

Si el comportamiento automático no se adapta a tus necesidades, establece el tipo en null y toma el control. En ese caso, corresponderá a ti almacenar el audio en el búfer con input_audio_buffer.append, confirmar el turno explícitamente con input_audio_buffer.commit y desencadenar la generación con response.create. El modo manual es la opción correcta para una interfaz de «pulsar para hablar» (push-to-talk) o siempre que necesites un control preciso sobre cuándo habla el agente.

Elige el formato de audio adecuado

El bloque audio define los formatos de entrada y salida de forma independiente:

{
  "audio": {
    "input": { "format": { "type": "audio/pcm", "rate": 24000 } },
    "output": { "format": { "type": "audio/pcm", "rate": 24000 } }
  }
}

Se aceptan cuatro tipos. Si no especificas ninguno, obtendrás PCM a 24.000 Hz:

TypeEncodingSample rates
audio/pcmPCM Linear16, little-endian8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz
audio/pcmuG.711 mu-law (telefonía norteamericana)8000 Hz only
audio/pcmaG.711 A-law (telefonía europea)8000 Hz only
audio/opusOpus, un paquete por mensaje24000 Hz

Tu canal de entrega determina la elección. Una aplicación web en un navegador funciona perfectamente con PCM a 24.000 Hz, un buen equilibrio entre calidad percibida y ancho de banda. Una integración con teléfono SIP no tiene opción: la red transporta G.711 a 8.000 Hz, y forzar un formato de mayor calidad solo añadiría una conversión innecesaria.

Proporciona herramientas al agente

El array tools enumera lo que el agente puede invocar durante la conversación, y puedes mezclar diferentes tipos en la misma sesión:

{
  "tools": [
    { "type": "web_search" },
    { "type": "x_search", "allowed_x_handles": ["gaborit_music"] },
    {
      "type": "function",
      "name": "get_order_status",
      "parameters": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" }
        },
        "required": ["order_id"]
      }
    }
  ]
}

Tú proporcionas la caja de herramientas; el agente elige la herramienta. A medida que avanza la conversación, decide que una pregunta sobre las noticias requiere una búsqueda web, mientras que un número de pedido requiere get_order_status. Por tanto, tu tarea consiste menos en orquestar las llamadas y más en describir cada herramienta con claridad, para que el agente tome la decisión correcta.

Puntos clave

  • El mensaje session.update configura la voz, las instrucciones, el VAD y las herramientas
  • El VAD del lado del servidor (server_vad) detecta los turnos y gestiona las interrupciones; idle_timeout_ms es el único ajuste disponible
  • El modo manual (turn_detection.type establecido en null) te ofrece un control preciso, por ejemplo, con una interfaz de pulsar para hablar
  • Los formatos de audio PCM, G.711 y Opus cubren tanto casos de uso web como de telefonía
  • Puedes cambiar la configuración en mitad de la sesión sin cortar la conexión