Audio agents
Les agents Audio mènent des conversations vocales bidirectionnelles en temps réel. Le SDK Audio Agents gère pour vous l'ensemble du pipeline : il capture la voix de l'utilisateur, la transcrit, génère une réponse avec un modèle, la convertit en parole, puis la restitue. C'est vous qui écrivez l'application autour de ce pipeline : ce que l'agent sait, quels outils il peut appeler et ce qui se passe quand un appel se termine. Les utilisateurs peuvent interrompre l'agent en pleine phrase, et l'agent peut effectuer une recherche sur le Web, interroger vos bibliothèques de documents, appeler les connecteurs de votre espace de travail ou exécuter vos propres fonctions.
Fonctionnement
Chaque tour de parole traverse les mêmes étapes. Les modèles s'exécutent chez Mistral, et votre application capture et restitue l'audio.
Chaque étape a un seul rôle :
| Étape | Rôle | En savoir plus |
|---|---|---|
| Transcription | Transforme la parole de l'utilisateur en texte au fur et à mesure qu'il parle, et détecte quand il a terminé son tour de parole. | Tours de parole et prise de tour |
| Modèle | Lit la conversation et rédige la réponse. Quand il a besoin de données ou d'une action, il appelle un outil : les outils côté serveur s'exécutent chez Mistral, les outils côté client exécutent vos propres fonctions dans votre application. | Outils |
| Speech | Prononce la réponse avec la voix de l'agent. | Voix |
Les étapes forment une chaîne, chacune s'ajoute donc au temps que l'utilisateur attend avant la réponse : voir Latence. L'utilisateur peut aussi couper la parole à l'agent pendant qu'il s'exprime ; voir Interruptions dans les agents Audio.
Sur une ligne téléphonique, le téléphone de l'appelant tient lieu de microphone et de haut-parleur, et aucune ligne de votre code ne s'exécute pendant l'appel : les outils côté client y échouent, utilisez donc des outils côté serveur pour tout ce dont un agent téléphonique a besoin.
Agents et sessions
L'agent est ce que vous configurez, et la session est une conversation qui l'exécute. Ils n'ont pas la même durée de vie et ne contiennent pas les mêmes choses :
| Agent | Session | |
|---|---|---|
| Définition | Une configuration enregistrée et versionnée | Une conversation en cours |
| Durée | Jusqu'à ce que vous le supprimiez | De sa connexion jusqu'à ce que votre application la ferme ou qu'une erreur fatale y mette fin |
| Contenu | Le comportement de l'agent : instructions, modèles, voix, déclarations d'outils, message de bienvenue, et la possibilité pour l'utilisateur d'interrompre | Ce qui est propre à cette conversation : l'interface audio, les gestionnaires de vos outils côté client, et toute option que vous remplacez |
| Nombre | Un par usage, par exemple une ligne d'assistance | Une par conversation, démarrée à partir d'un agent enregistré ou d'une configuration que vous transmettez à la connexion |
| Modification | Créer une nouvelle version | Remplacez des options de l'agent à la connexion, pour cette session uniquement |
Quand enregistrer un agent
Une session peut s'exécuter sans agent enregistré : vous transmettez la configuration complète à la connexion, ce qui est le moyen le plus rapide de tester. Enregistrez-la comme agent dès que la configuration doit dépasser le cadre d'un seul script :
- Réutilisez-le partout. Les sessions issues du SDK, d'un navigateur et d'une ligne téléphonique partent du même agent et se comportent de la même façon.
- Modifiez-le en toute sécurité. Chaque modification crée une nouvelle version. Par défaut, les sessions partent de la dernière version, et vous pouvez en épingler une pour conserver une configuration connue en production pendant que vous testez la suivante. Voir Versions.
- Attachez des numéros de téléphone et des webhooks.
Quand une session démarre à partir d'un agent enregistré, les options que vous transmettez remplacent celles qui sont enregistrées, pour cette session uniquement, et l'agent ne change pas. Voir Configuration inline ou enregistrée.
Déroulement d'une session
Une session traverse trois phases, et votre application suit chacune d'elles grâce aux événements de session :
| Phase | Ce qui se passe | Ce que reçoit votre application |
|---|---|---|
| Démarrage | Votre application ouvre la session, ou votre serveur s'en charge pour une page de navigateur. L'agent peut accueillir l'utilisateur avec son message de bienvenue. | Un événement de connexion |
| Conversation | L'utilisateur et l'agent alternent : l'agent écoute, réfléchit, parle et appelle des outils quand il en a besoin. | Transcriptions, changements d'état de l'agent et appels d'outils |
| Fin | Votre application ferme la session, ou une erreur fatale y met fin. | Un événement de déconnexion, accompagné de la raison quand la fermeture n'est pas normale |
Les événements de session parviennent au code qui exécute la session pendant que la conversation se poursuit : utilisez-les pour mettre à jour votre interface. Les webhooks atteignent votre backend quand un appel démarre, se termine ou échoue : utilisez-les comme trace de chaque appel, par exemple pour stocker la transcription. Pour la liste des événements, voir Gérer les sessions d'agents. Pour les états de l'agent et les interruptions, voir Tours de parole et prise de tour.
Le SDK s'appuie sur LiveKit pour le transport audio en temps réel, et ajoute les bindings Python et TypeScript ainsi que le pont vers les modèles Mistral. Vous n'avez pas besoin de connaître LiveKit pour l'utiliser.
Choisir votre parcours
| Vous voulez | Construire avec | À savoir |
|---|---|---|
| Un agent qui s'exécute sur votre machine ou votre serveur | Le SDK en Python ou Node.js | Le SDK gère l'ensemble du pipeline et utilise le microphone et les haut-parleurs de la machine. Commencez par le guide de démarrage. |
| La voix dans une application web | Le SDK dans le navigateur (TypeScript) | Votre serveur crée la session pour que la clé API n'atteigne jamais le navigateur, puis la page se connecte avec les identifiants qu'il renvoie. Voir le guide du navigateur. |
| Un agent qui répond aux appels téléphoniques | Téléphonie (SIP) | Disponible au lancement pour les clients Entreprise, via votre équipe de compte. Voir Téléphonie. |
| Un contrôle total sur chaque étape | Votre propre pipeline : la transcription en temps réel, un modèle conversationnel et de la parole en streaming | Vous maîtrisez le transport, la latence et la gestion des tours de parole. |
Utilisez le SDK quand vous voulez que la capture, la transcription, le modèle, la parole et la lecture soient gérés de bout en bout. Construisez votre propre pipeline quand vous avez besoin de contrôler chaque étape séparément, par exemple pour changer la façon dont les tours de parole sont détectés ou l'endroit où l'audio est traité.
Outils
Vous choisissez le modèle de chaque étape, au niveau de l'agent ou de la session ; voir Configuration de l'agent. Les outils permettent à l'agent d'agir pendant la conversation : la recherche sur le Web intégrée, les bibliothèques de documents et les connecteurs d'espace de travail s'exécutent côté Mistral, et vos propres fonctions s'exécutent dans votre code. Une courte phrase de remplissage, dite à voix haute, couvre l'attente pendant qu'un outil s'exécute ; voir Outils. En production, des webhooks signés notifient votre backend quand un appel démarre, se termine ou échoue.
Problèmes courants
| Symptôme | Solution |
|---|---|
| Le SDK s'installe, mais aucun audio n'est capturé ni lu | Installez les outils audio natifs : PortAudio pour Python, SoX et FFmpeg pour Node.js. Voir Installer le SDK. |
Un avertissement livekit::rtc_engine concernant un canal de données fermé apparaît à l'ouverture ou à la fermeture de la session | Rien à corriger : c'est un avertissement LiveKit sans gravité, pas une erreur dans votre session. |