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

Configura la sesión con session.update

Lección 3 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Configura tu agente de voz
  2. La estructura completa de session.update
  3. Los ajustes en detalle
  4. Actualiza la sesión en mitad de la conversación
  5. Puntos clave

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_detection definido únicamente por su type (con idle_timeout_ms opcional). 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.update es el primer mensaje que debes enviar tras session.created
  • El campo instructions define 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.update varias veces para cambiar el comportamiento en mitad de la conversación