Construire des agents LiveKit

Cette compétence explique comment structurer un agent vocal. Elle n'a pas de spécificités API, car celles-ci changent ; récupérez-les via reading-livekit-docs.

Elle suppose LiveKit Cloud, le chemin recommandé : infrastructure gérée, plus LiveKit Inference pour les modèles afin que vous ne gériez pas les clés API par fournisseur.

L'endroit où l'agent s'exécute et quel LiveKit le projet utilise sont des questions distinctes. Un agent que l'utilisateur auto-héberge (sur ses propres serveurs au lieu de l'hébergement d'agents de LiveKit Cloud) se connecte toujours à LiveKit Cloud et peut toujours utiliser LiveKit Inference. Inference est une fonctionnalité de LiveKit Cloud, donc elle n'est hors jeu que quand le projet s'exécute sur LiveKit OSS. Les conseils d'architecture s'appliquent de toute façon ; sur LiveKit OSS, les modèles proviennent du plugin propre à chaque fournisseur et des clés API.

Avant d'écrire du code

1. Chargez reading-livekit-docs et cherchez les API que vous allez utiliser. N'écrivez pas de code LiveKit de mémoire.
2. Confirmez que le projet est connecté à un projet LiveKit Cloud (ou un serveur LiveKit OSS) : LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET, généralement dans .env. L'CLI peut les configurer.
3. Décidez de la forme du workflow avant d'écrire la première classe d'agent (voir « Structure » ci-dessous). Diviser un monolithe en transferts plus tard est beaucoup plus de travail que de commencer avec deux agents.
4. Planifiez comment vous allez le vérifier. Décidez maintenant si vous utiliserez debugging-livekit-agents (conduire une vraie conversation), testing-livekit-agents (affirmer sur les tours), ou les deux, car cela affecte la façon dont vous structurez le code.

Comment la voix change les exigences

Un agent vocal est plus qu'un agent de chat avec un haut-parleur. Ces contraintes conduisent la plupart des décisions de conception :

Latence. Les utilisateurs attendent une réponse en quelques centaines de millisecondes. La taille du contexte, le nombre d'outils, qu'un appel d'outil soit sur le chemin critique, et si les réponses se diffusent en continu ajoutent tous à ce budget ou en soustraient. Prévoyez les ralentissements réseau et les délais d'expiration des fournisseurs ; ils arrivent régulièrement.

Taille du contexte. Un prompt système de 10 000 tokens avec 50 définitions d'outils semble lent sur n'importe quel modèle, car le modèle relit tout cela à chaque tour. Donnez à chaque phase seulement les outils qu'elle peut atteindre et les instructions dont elle a besoin.

Écoute. Les utilisateurs ne peuvent pas survoler ou faire défiler en arrière, et ils vont parler par-dessus l'agent. Les longues réponses sont un bug, le silence semble défectueux, et les interruptions sont normales.

Structure : transferts et tâches

L'échec habituel est un agent qui fait tout. Il collecte chaque outil, instruction et état jusqu'à devenir lent et peu fiable, et à ce stade, le diviser est une réécriture.

Les transferts passent le contrôle d'un agent à un autre. Placez-les aux limites naturelles de la conversation, comme accueil → prise d'informations → résolution, ou support général → spécialiste facturation. Chaque agent ne porte alors que ses propres outils et instructions. Choisissez une limite où le contexte peut être résumé pour l'agent suivant. Si l'agent suivant a besoin de tout ce que le précédent avait, la limite est mal placée.

Les tâches sont des prompts étroitement ciblés vers un seul résultat. Utilisez-les pour des opérations discrètes qui ne nécessitent pas un agent complet, ou quand un prompt ciblé fonctionne mieux qu'un prompt général.

Si vous ne pouvez pas dire en une phrase de quoi un agent est responsable, divisez-le.

Outils

• Les descriptions d'outils conduisent le comportement. Quand un agent appelle le mauvais outil ou l'appelle au mauvais moment, vérifiez la description avant de blâmer le modèle. La cause la plus courante est une description qui ne dit pas quand utiliser l'outil.
• Gardez les outils hors du chemin critique autant que vous pouvez. Les utilisateurs entendent chaque appel d'outil comme de la latence.
• Planifiez l'échec des outils. Décidez ce que l'agent dit quand un backend est en panne ou ne retourne rien. Un agent qui invente une réponse quand un outil échoue est très difficile à attraper plus tard.

Le modèle interprète ; votre code possède l'état

Le modèle lit la conversation et propose des actions. Le code de l'application possède les enregistrements, les vérifications de permissions, les transitions d'état, et chaque effet externe. La plupart des agents qui « fonctionnent dans la démo et échouent en production » ont cette ligne floue quelque part.

• Ne classifiez jamais l'intention avec du code. Approbation, refus, correction, annulation, « mardi prochain » — le modèle à l'exécution interprète cela. Une regex, une liste de mots-clés, ou une liste blanche de phrases se trompera de façons que vous ne testez jamais, et en ajouter une comme deuxième filtrage « conservateur » a le même défaut. Validez la structure en code (dates typées, enums, champs obligatoires) ; laissez la signification au modèle.
• Un appel d'outil est l'interprétation du modèle, pas une preuve qu'il avait raison. Conservez l'origine des messages, les vérifications de version, l'ordre, et les règles métier en code, où elles peuvent être vérifiées.
• Les outils retournent des faits, pas des phrases. Des données compactes, des résultats, et des erreurs actionnables ; le modèle choisit la formulation. Scriptez du texte exact seulement quand la tâche impose une divulgation textuelle.
• Suivez l'utilisateur, pas un formulaire. Acceptez les faits que l'appelant fournit ensemble, demandez seulement ce qui manque ou est ambigu, et ne demandez jamais une formulation rituelle (« dites oui pour confirmer ») après une réponse claire.
• Un objet d'état autoritaire par session, et gardez les faits fournis par le modèle séparés de l'identité de confiance, l'horloge, les ids, et les reçus.

Faites en sorte que chaque changement signifie exactement une chose

Les bugs d'agent les plus coûteux sont des mutations qui ont fait plus ou moins que l'appelant le visait : « pas de note pour lui » vidant toute la liste, une correction qui a aussi réinitialisé un champ confirmé, une valeur réaffirmée qui a invalidé une approbation. Avant d'écrire un outil qui mute, énoncez sa cible, ce qui change, et ce qui doit rester pareil — puis associez-le à la demande la plus proche qui doit faire quelque chose de différent.

Les règles en résumé : l'omission préserve ; manquant, vide, inconnu et vidé sont quatre choses différentes ; les collections obtiennent des ids émis par l'application ; validez avant d'appliquer ; une négative ciblée ne vide jamais une collection ; les valeurs inchangées sont des no-ops. Quand une tâche nécessite une révision avant un effet, l'approbation est un message utilisateur ultérieur réel pour cette version, la livraison est suivie à la limite de la parole, et le succès est publié seulement après que l'écriture se valide. Le traitement complet — incluant la fermeture, la propriété de la sortie, et comment les entrées texte et audio prennent des chemins de hook différents — est dans references/state-and-effects.md. Lisez-le avant de construire tout ce qui réserve, édite, confirme, ou termine des appels.

Commencez par un test de chemin complet défaillant

Avant d'élargir la surface des outils ou de peaufiner la persona, choisissez un objectif utilisateur ordinaire et conduisez-le à travers l'agent réel jusqu'à son effet requis — la réservation existe, l'enregistrement a changé, l'appel s'est terminé. Écrivez le résultat attendu à partir de la demande de l'utilisateur, pas de l'export de l'application. Ensuite, associez-le au premier garde qui doit refuser, car un test qui rejette tout ne prouve rien du garde. Gardez cette paire verte pendant que vous ajoutez tout le reste.

Vérifiez avant de dire que c'est fait

Les changements de prompt cassent le comportement de l'agent aussi facilement que les changements de code, et l'essayer une fois à la main ne compte pas comme une vérification.

• Pendant la construction, conduisez des conversations avec debugging-livekit-agents. Cela exécute votre agent localement en mode texte, vous permet d'envoyer des tours, et montre les appels d'outils derrière chaque réponse.
• Avant de dire que c'est fait, écrivez des tests avec testing-livekit-agents. Au minimum, couvrez le comportement principal que l'utilisateur a demandé, l'invocation d'outils avec les bons arguments s'il y a des outils, et un chemin d'échec.
• Avant de déployer un changement vers un agent en direct, exécutez des simulations avec writing-livekit-scenarios et running-livekit-simulations.

Si l'utilisateur demande pas de tests, construisez sans eux, mentionnez une fois que vous recommanderiez avant la production, et passez à autre chose.

Erreurs courantes

• Commencer avec un agent « juste pour maintenant ». Vous décidez la structure d'avance ; l'implémentation peut quand même être simple.
• Repousser la latence. Elle s'accumule, et c'est de plus en plus cher à corriger.
• Copier un exemple que vous ne comprenez pas. Un exemple montre un modèle. Collé en entier, il apporte du contexte supplémentaire et des composants que vous ne pouvez pas expliquer.
• Supposer que votre connaissance des modèles est à jour. Elle ne l'est pas. Voir reading-livekit-docs.
• Déployer sur les tests manuels seuls. Les éditions de prompt changent le comportement sans erreur visible, et les tests vous laissent le découvrir avant les utilisateurs.

Compétences connexes

• Faits, APIs, changelogs : reading-livekit-docs
• Conduire une conversation en direct pendant la construction : debugging-livekit-agents
• Tests au niveau des tours : testing-livekit-agents
• Tests de conversation complète : writing-livekit-scenarios, running-livekit-simulations
• État, approbations, commits, livraison, fermeture : references/state-and-effects.md
• Le déployer et le maintenir sain en production : operating-livekit-agents