Configuration de session avec session.update

Leçon corrigée le 3 novembre 2026 d’après les pages Speech to Speech et Text to Speech de xAI : 28 voix intégrées et non cinq, sans genre attribué par xAI ; turn_detection se règle par son seul type (avec idle_timeout_ms en option), les réglages threshold, silence_duration_ms et prefix_padding_ms de l’ancien exemple n’étant pas documentés (leçon 6). Sources : Speech to Speech · Text to Speech.

Configurer votre agent vocal

Une fois la connexion WebSocket établie et l’événement session.created reçu, vous devez configurer la session en envoyant un message session.update. C’est dans cet événement que vous définissez le comportement de votre agent vocal : sa personnalité, sa voix, les outils qu’il peut utiliser et la manière dont il détecte les tours de parole.

Structure complète de session.update

Voici un exemple de configuration détaillée :

{
  "type": "session.update",
  "session": {
    "instructions": "Vous êtes un assistant vocal professionnel pour un cabinet d'avocats. Répondez de manière concise et précise. Utilisez un ton formel.",
    "voice": "Rex",
    "tools": [
      {"type": "web_search"},
      {
        "type": "function",
        "name": "consulter_dossier",
        "description": "Consulte un dossier client par numéro",
        "parameters": {
          "type": "object",
          "properties": {
            "numero_dossier": {
              "type": "string",
              "description": "Numéro du dossier client"
            }
          },
          "required": ["numero_dossier"]
        }
      }
    ],
    "turn_detection": {
      "type": "server_vad"
    },
    "audio": {
      "input": {
        "format": {"type": "audio/pcm", "rate": 24000}
      },
      "output": {
        "format": {"type": "audio/pcm", "rate": 24000}
      }
    }
  }
}

Les paramètres en détail

Instructions (prompt système)

Le champ instructions est l’équivalent du prompt système des API texte : il définit la personnalité, le contexte et les contraintes de votre agent vocal. La rédaction obéit toutefois à une contrainte propre au vocal — la concision. Chaque token du prompt est traité avant la première réponse, et un prompt-fleuve se paie en latence perceptible au décrochage : visez l’essentiel, quitte à déporter les détails dans la logique applicative. Dans ce budget resserré, trois éléments méritent leur place : le ton (formel, amical, technique — l’agent vocal incarne littéralement votre marque à l’oreille du client), la langue (précisez « réponds en français », sans quoi l’agent peut suivre la langue de l’utilisateur ou de la question), et les limites — ce que l’agent peut faire et surtout ce qu’il doit refuser ou transférer à un humain, car au téléphone, une réponse hors périmètre part avant que quiconque ait pu la relire.

Voix

Le paramètre voice accepte l’une des 28 voix intégrées de xAI (relevé du 3 novembre 2026), communes à l’agent vocal et à la synthèse vocale, ou l’identifiant d’une voix personnalisée créée avec l’API Custom Voices. Les identifiants ne tiennent pas compte de la casse : eve, Eve et EVE désignent la même voix. Toutes les voix parlent toutes les langues prises en charge.

Les cinq voix d’origine, avec la description qu’en donne xAI :

• eve : énergique et enjouée, accent britannique
• ara : chaleureuse et amicale
• rex : confiant et clair
• sal : doux et équilibré
• leo : autoritaire et puissant, accent britannique

S’y ajoutent 23 voix plus récentes : carina, zagan, helix, orion, luna, iris, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora et liora. La liste à jour, avec le ton et les usages de chacune, s’obtient par GET /v1/tts/voices ou sur la page Text to Speech de xAI.

Outils

Le tableau tools définit les outils que l’agent peut invoquer pendant la conversation. Vous pouvez combiner plusieurs types : recherche web, recherche X, fonctions personnalisées, collections RAG et serveurs MCP. Les outils seront détaillés dans les leçons suivantes.

Configuration audio

L’objet audio définit les formats d’entrée et de sortie. Vous pouvez utiliser des formats différents pour l’entrée et la sortie si votre architecture le nécessite (par exemple, recevoir du G.711 depuis un système téléphonique et envoyer du PCM vers un navigateur).

Mettre à jour la session en cours de conversation

Vous pouvez envoyer session.update plusieurs fois pendant une conversation. Cela permet de modifier dynamiquement le comportement de l’agent :

// Changer la voix en cours de conversation
ws.send(JSON.stringify({
  type: "session.update",
  session: {
    voice: "Ara"
  }
}));

// Ajouter un outil supplémentaire
ws.send(JSON.stringify({
  type: "session.update",
  session: {
    tools: [
      { type: "web_search" },
      { type: "x_search" }
    ]
  }
}));

La documentation de xAI prévoit explicitement ces changements en cours de session pour plusieurs réglages — langue de transcription, mots-clés, remplacements de prononciation, transport audio — et session.updated en accuse réception : vérifiez-y la configuration appliquée.

Points clés à retenir

• session.update est le premier message à envoyer après session.created
• Le champ instructions définit la personnalité et les contraintes de l’agent
• 28 voix intégrées sont disponibles (dont eve, ara, rex, sal et leo), ainsi que les voix personnalisées
• La configuration audio et les outils sont personnalisables
• Vous pouvez envoyer session.update plusieurs fois pour modifier le comportement en cours de conversation