WebSocket multi-contexte
WebSocket multi-contexte
Ce guide explique comment créer des agents vocaux en temps réel avec l’API WebSocket multi-contexte.
L’orchestration d’agents vocaux avec cette API WebSocket multi-contexte est une tâche complexe, recommandée aux développeurs expérimentés. Pour une solution davantage gérée, consultez notre produit Agents Platform, qui simplifie bon nombre de ces difficultés.
Vue d’ensemble
La création d’agents vocaux réactifs exige de pouvoir gérer dynamiquement les flux audio, traiter les interruptions avec fluidité et préserver une voix naturelle tout au long des tours de conversation. Notre API WebSocket multi-contexte pour Text to Speech (TTS) est spécifiquement conçue pour ces scénarios.
Cette API étend notre fonctionnalité WebSocket TTS standard en introduisant le concept de « contextes ». Chaque contexte fonctionne comme un flux indépendant de génération audio au sein d’une même connexion WebSocket. Vous pouvez ainsi :
- Gérer plusieurs lignes de parole simultanément, par exemple un agent qui parle tout en préparant une réponse à l’interruption d’un utilisateur.
- Gérer sans rupture les interventions des utilisateurs en fermant un contexte de parole existant et en en démarrant un nouveau.
- Préserver la cohérence prosodique des énoncés au sein d’un même contexte logique.
- Optimiser l’utilisation des ressources en fermant sélectivement les contextes qui ne sont plus nécessaires.
L’API WebSocket multi-contexte est optimisée pour les applications vocales et n’est pas destinée à générer simultanément plusieurs flux audio sans lien entre eux. Chaque connexion est donc limitée à 5 contextes simultanés.
Ce guide vous accompagne pour vous connecter au WebSocket multi-contexte, gérer les contextes et appliquer les bonnes pratiques de création d’agents vocaux engageants.
Bonnes pratiques
Ces bonnes pratiques sont essentielles pour créer des agents vocaux réactifs et efficaces avec notre API WebSocket multi-contexte.
Utiliser une seule connexion WebSocket
Établissez une connexion WebSocket pour chaque session d’utilisateur final. Cela réduit la surcharge et la latence par rapport à la création de plusieurs connexions. Au sein de cette même connexion, vous pouvez gérer plusieurs contextes pour différentes parties de la conversation.
Diffuser les réponses par fragments, générer des phrases
Pour générer des réponses longues, diffusez le texte en petits fragments et utilisez l’indicateur
flush: true à la fin des phrases complètes. Cela améliore la qualité de l’audio généré et la
réactivité.
Gérer les interruptions avec fluidité
Diffusez le texte dans un contexte jusqu’à ce qu’une interruption survienne, puis créez un nouveau contexte et fermez celui qui existe. Cette approche garantit des transitions fluides lorsque le fil de la conversation change.
Gérer le cycle de vie des contextes
Fermez rapidement les contextes inutilisés. Le serveur peut maintenir jusqu’à 5 contextes simultanés par connexion, mais vous devez fermer les contextes lorsqu’ils ne sont plus nécessaires.
Éviter l’expiration des contextes
Par défaut, les contextes expirent après 20 secondes et sont fermés automatiquement. Le délai d’inactivité est un paramètre au niveau du WebSocket qui s’applique à tous les contextes et peut aller jusqu’à 180 secondes si nécessaire. Envoyez un message texte vide dans un contexte pour réinitialiser le délai d’expiration.
Gestion des interruptions
Lorsqu’un utilisateur interrompt votre agent, vous devez fermer le contexte actuel et en créer un nouveau :
Maintenir un contexte actif
Les contextes expirent automatiquement après 20 secondes d’inactivité par défaut. Si vous devez maintenir un contexte actif sans générer de texte, par exemple pendant un délai de traitement, vous pouvez envoyer un message texte vide pour réinitialiser le délai d’expiration.
Fermer la connexion WebSocket
Lorsque votre conversation se termine, vous pouvez nettoyer tous les contextes en fermant le socket :
Exemple complet d’agent conversationnel
Prérequis
- Un compte ElevenLabs avec une clé API, découvrez comment trouver votre clé API.
- Python ou Node.js, ou un autre environnement d’exécution JavaScript, installé sur votre machine.
- Une connaissance des communications WebSocket. Nous recommandons de lire notre guide du streaming WebSocket standard pour en maîtriser les concepts fondamentaux.
Configuration
Installez les dépendances nécessaires pour le langage de votre choix :
Créez un fichier .env dans le répertoire de votre projet afin d’y stocker votre clé API :