Configurer une Session Vocale

Le message session.update

Apres avoir etabli la connexion WebSocket, la premiere etape consiste a configurer votre session vocale. Le message session.update definit le comportement de l’agent : quelle voix utiliser, quelles instructions suivre, comment detecter les tours de parole, et quels outils rendre disponibles.

Voici un exemple complet de configuration :

{
  "type": "session.update",
  "session": {
    "instructions": "Vous etes un assistant vocal professionnel pour une entreprise de e-commerce. Repondez de maniere 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 confirme la mise a jour avec un evenement session.updated. Vous pouvez envoyer plusieurs session.update au cours d’une meme session pour modifier les parametres a la volee.

Les instructions systeme

Le champ instructions fonctionne comme un prompt systeme pour l’agent vocal. C’est ici que vous definissez :

• La personnalite de l’agent (formel, decontracte, technique)
• Le perimetre des sujets qu’il peut aborder
• Les contraintes de reponse (longueur, format, langue)
• Le contexte metier (nom de l’entreprise, produits, procedures)

Quelques bonnes pratiques pour les instructions vocales :

• Demandez des reponses courtes et directes : a l’oral, les longues tirades sont penibles
• Precisez la langue attendue si votre application est monolingue
• Indiquez comment gerer les ambiguites : poser une question de clarification plutot que deviner

La detection des tours de parole (VAD)

Le parametre turn_detection controle comment le serveur detecte quand l’utilisateur parle et quand il a fini. Le type server_vad (Voice Activity Detection) est le mode recommande :

Parametres de reglage

• threshold (0.0 a 1.0, defaut ~0.5) : sensibilite de detection. A 0.85, le VAD exige un signal vocal plus net avant de considerer que l’utilisateur parle, ce qui reduit les faux positifs dans les environnements bruyants
• silence_duration_ms (defaut ~500) : duree de silence apres laquelle le serveur considere que l’utilisateur a fini de parler. Augmentez cette valeur si vos utilisateurs font des pauses frequentes
• prefix_padding_ms (defaut ~333) : quantite d’audio conservee avant le debut detecte de la parole, pour ne pas perdre les premiers mots

Mode manuel (sans VAD)

Si vous preferez gerer les tours de parole vous-meme, omettez turn_detection. Dans ce mode :

1. Vous accumulez l’audio avec input_audio_buffer.append
2. Vous validez manuellement avec input_audio_buffer.commit
3. Vous declenchez la reponse avec response.create

Ce mode est utile pour les interfaces avec un bouton push-to-talk ou pour les scenarios ou vous voulez un controle precis sur le moment ou l’agent repond.

Configuration audio

Le bloc audio definit les formats d’entree et de sortie :

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

Les formats supportes sont :

• audio/pcm : PCM Linear16, little-endian. Sample rates : 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz
• audio/pcmu : G.711 mu-law, 8000 Hz uniquement (telephonie nord-americaine)
• audio/pcma : G.711 A-law, 8000 Hz uniquement (telephonie europeenne)

Le choix du format depend de votre cas d’usage. Pour une application web, PCM 24000 Hz offre un bon equilibre qualite/bande passante. Pour de la telephonie SIP, G.711 a 8000 Hz est le standard.

Ajouter des outils

Le tableau tools liste les outils disponibles pendant la conversation. Vous pouvez combiner plusieurs types :

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

L’agent decide lui-meme quand utiliser un outil en fonction du contexte de la conversation.

Points cles a retenir

• Le message session.update configure la voix, les instructions, le VAD et les outils
• Le VAD cote serveur detecte automatiquement les tours de parole avec des seuils reglables
• Le mode manuel (sans VAD) permet un controle precis avec push-to-talk
• Les formats audio PCM et G.711 couvrent les cas web et telephonie
• Vous pouvez modifier la configuration en cours de session sans couper la connexion