Configuration de session avec session.update — Voice Agent API : conversations temps réel

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 pour les API texte. Il définit la personnalité, le contexte et les contraintes de votre agent vocal. Quelques conseils :

Soyez concis : l’agent vocal doit répondre rapidement, un prompt trop long ralentit la première réponse
Précisez le ton : formel, amical, technique, selon votre cas d’usage
Indiquez la langue : si vous voulez que l’agent parle français, précisez-le dans les instructions
Définissez les limites : ce que l’agent peut et ne peut pas faire

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