Configuration de session avec session.update

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

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 cinq voix disponibles :

• Eve : énergique et enjouée (féminin)
• Ara : chaleureuse et amicale (féminin)
• Rex : confiant et clair (masculin)
• Sal : doux et équilibré (neutre)
• Leo : autoritaire et puissant (masculin)

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

Chaque session.update remplace les paramètres spécifiés. Les paramètres non mentionnés conservent leur valeur précédente.

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
• Cinq voix sont disponibles : Eve, Ara, Rex, Sal et Leo
• La configuration audio et les outils sont personnalisables
• Vous pouvez envoyer session.update plusieurs fois pour modifier le comportement en cours de conversation