Configurer une Session Vocale

Leçon corrigée le 3 novembre 2026 d’après la page Speech to Speech et le guide de prompts vocaux de xAI : turn_detection ne se règle que par son type (server_vad ou null) et par idle_timeout_ms — les réglages threshold, silence_duration_ms et prefix_padding_ms de l’ancienne version ne sont pas documentés par xAI ; le mode manuel s’obtient en passant le type à null, et non en omettant le bloc ; le format audio/opus complète la liste. Sources : Speech to Speech · Prompting Guide.

Le message qui définit tout : session.update

La connexion WebSocket établie, rien ne se passe encore. C’est le message session.update qui donne son caractère à l’agent : la voix qu’il prend, les instructions qu’il suit, la manière dont il repère les tours de parole et les outils auxquels il a droit. Considérez-le comme l’acte de naissance de la session — tout le reste de la conversation en découle.

{
  "type": "session.update",
  "session": {
    "instructions": "Vous êtes un assistant vocal professionnel pour une entreprise de e-commerce. Répondez de manière concise et aidez les clients avec leurs commandes.",
    "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" }
    ]
  }
}

Le serveur accuse réception par un événement session.updated. Rien ne vous oblige à n’envoyer ce message qu’une fois : vous pouvez le réémettre en cours de conversation pour changer un paramètre à la volée, par exemple basculer d’une voix à une autre quand l’échange passe du service commercial au support technique, sans jamais couper la connexion.

Écrire des instructions pour l’oreille, pas pour l’œil

Le champ instructions joue le rôle du prompt système. Vous y posez la personnalité de l’agent — formel, décontracté, technique —, le périmètre des sujets qu’il a le droit d’aborder, les contraintes de ses réponses en longueur, en format et en langue, et le contexte métier dont il a besoin : nom de l’entreprise, gamme de produits, procédures internes.

La difficulté est que ce qui fait un bon prompt à l’écrit fait souvent un mauvais agent vocal. Un modèle laissé libre produit des réponses de dix lignes ; lues à haute voix, elles deviennent interminables et l’utilisateur décroche avant la fin. Demandez donc explicitement des réponses courtes et directes. Précisez aussi la langue attendue si votre application est monolingue, faute de quoi l’agent risque de suivre l’accent de son interlocuteur. Et dites-lui quoi faire quand il ne comprend pas : une consigne du type « posez une question de clarification plutôt que de deviner » évite qu’un numéro de commande mal entendu déclenche une recherche dans le vide. Le guide de prompts vocaux de xAI propose d’ailleurs une structure en cinq rubriques — rôle et persona, objectif, déroulé de la conversation, garde-fous et escalade, style vocal — et conseille une ou deux phrases courtes par tour, sauf si l’interlocuteur demande plus de détails.

La détection des tours de parole

Le bloc turn_detection décide de qui parle et quand, et la documentation de xAI n’y prévoit que deux réglages. Le premier est le type. En mode "server_vad", le serveur détecte lui-même la fin de chaque intervention, valide l’audio, lance la réponse et gère les interruptions : vous n’avez qu’à envoyer l’audio avec input_audio_buffer.append. Le second, facultatif, est idle_timeout_ms : si l’utilisateur se tait pendant ce nombre de millisecondes après une réponse, le serveur le relance de lui-même, et recommence à chaque nouveau silence de la même durée.

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

Aucun seuil de sensibilité ni aucune durée de silence ne se règle : les paramètres threshold, silence_duration_ms et prefix_padding_ms, que l’on croise dans les exemples écrits pour l’API Realtime d’OpenAI, ne figurent pas dans la documentation de xAI.

Si ce fonctionnement automatique ne vous convient pas, passez le type à null : vous reprenez la main. Il vous revient alors d’accumuler l’audio avec input_audio_buffer.append, de valider explicitement le tour avec input_audio_buffer.commit, puis de déclencher la génération par response.create. Ce mode manuel est le bon choix pour une interface à bouton push-to-talk, ou dès que vous voulez maîtriser précisément le moment où l’agent prend la parole.

Choisir le bon format audio

Le bloc audio fixe les formats d’entrée et de sortie, indépendamment l’un de l’autre :

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

Quatre types sont acceptés ; sans précision, c’est du PCM à 24000 Hz :

Le canal de diffusion tranche la question. Une application web dans un navigateur se contente très bien de PCM à 24000 Hz, bon compromis entre qualité perçue et bande passante consommée. Une intégration téléphonique SIP, elle, n’a pas le choix : le réseau transporte du G.711 à 8000 Hz, et lui imposer un format supérieur ne fait qu’ajouter une conversion inutile.

Ouvrir l’agent aux outils

Le tableau tools énumère ce que l’agent a le droit d’appeler pendant l’échange, et rien n’empêche de mélanger les genres dans une même session :

{
  "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"]
      }
    }
  ]
}

Vous déclarez la palette, l’agent choisit l’instrument. C’est lui qui décide, au fil de la conversation, qu’une question sur l’actualité appelle une recherche web quand un numéro de commande appelle get_order_status. Votre travail consiste donc moins à orchestrer les appels qu’à décrire clairement chaque outil pour que ce choix soit le bon.

Points clés à retenir

• Le message session.update configure la voix, les instructions, le VAD et les outils
• Le VAD côté serveur (server_vad) détecte les tours de parole et gère les interruptions ; seul idle_timeout_ms se règle
• Le mode manuel (turn_detection.type à null) permet un contrôle précis avec push-to-talk
• Les formats audio PCM, G.711 et Opus couvrent les cas web et téléphonie
• Vous pouvez modifier la configuration en cours de session sans couper la connexion