Configurer une Session Vocale

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",
      "threshold": 0.85,
      "silence_duration_ms": 500,
      "prefix_padding_ms": 333
    },
    "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.

La détection des tours de parole

Le bloc turn_detection décide de qui parle et quand. Le mode recommandé est server_vad, où le serveur fait ce travail à votre place. Trois réglages en pilotent le comportement :

• threshold (0.0 à 1.0, défaut ~0.5) : sensibilité de détection. À 0.85, le VAD exige un signal vocal plus net avant de considérer que l’utilisateur parle, ce qui réduit les faux positifs dans les environnements bruyants
• silence_duration_ms (défaut ~500) : durée de silence après laquelle le serveur considère que l’utilisateur a fini de parler. Augmentez cette valeur si vos utilisateurs font des pauses fréquentes
• prefix_padding_ms (défaut ~333) : quantité d’audio conservée avant le début détecté de la parole, pour ne pas perdre les premiers mots

Ces valeurs se règlent au terrain. Un assistant destiné à un open space bruyant demande un seuil élevé, quitte à rater un murmure ; un agent qui interroge des personnes âgées, plus lentes à formuler, gagne à voir son silence_duration_ms allongé, sinon l’agent leur coupe la parole en pleine hésitation.

Si ce fonctionnement automatique ne vous convient pas, omettez simplement turn_detection : 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 } }
}

Trois types sont acceptés :

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 détecte automatiquement les tours de parole avec des seuils réglables
• Le mode manuel (sans VAD) permet un contrôle précis avec push-to-talk
• Les formats audio PCM et G.711 couvrent les cas web et téléphonie
• Vous pouvez modifier la configuration en cours de session sans couper la connexion