Développement d'agents LiveKit pour LiveKit Cloud

Cette skill fournit des recommandations structurées pour construire des agents IA vocaux avec LiveKit Cloud. Elle suppose que vous utilisez LiveKit Cloud (le chemin recommandé) et encode comment approcher le développement d'agents, pas les spécificités des API. Toutes les informations factuelles concernant les APIs, méthodes et configurations doivent provenir de la documentation en direct.

Cette skill est destinée aux développeurs LiveKit Cloud. Si vous auto-hébergez LiveKit, certaines recommandations (particulièrement autour de LiveKit Inference) ne s'appliqueront pas directement.

OBLIGATOIRE : Lisez cette checklist avant de commencer

Avant d'écrire N'IMPORTE QUEL code, complétez cette checklist :

1. Lisez l'intégralité de ce document skill - Ne sautez pas de sections même si MCP est disponible
2. Assurez-vous que votre projet LiveKit Cloud est connecté - Vous avez besoin de LIVEKIT_URL, LIVEKIT_API_KEY et LIVEKIT_API_SECRET de votre projet Cloud
3. Configurez l'accès à la documentation - Utilisez MCP si disponible, sinon utilisez la recherche web
4. Prévoyez d'écrire des tests - Chaque implémentation d'agent DOIT inclure des tests (voir la section tests ci-dessous)
5. Vérifiez tous les APIs contre la documentation en direct - Ne vous fiez jamais à la mémoire du modèle pour les APIs LiveKit

Cette checklist s'applique indépendamment de la disponibilité de MCP. MCP fournit l'accès à la documentation mais N'ÉLIMINE PAS les recommandations de cette skill.

Configuration de LiveKit Cloud

LiveKit Cloud est le moyen le plus rapide de mettre en place un agent vocal. Il fournit :

• Infrastructure gérée (pas de serveurs à déployer)
• LiveKit Inference pour les modèles IA (pas de clés API séparées nécessaires)
• Suppression du bruit intégrée, détection de tours et autres fonctionnalités vocales
• Gestion simple des identifiants

Connectez-vous à votre projet Cloud

1. Inscrivez-vous sur cloud.livekit.io si vous ne l'avez pas déjà fait

2. Créez un projet (ou utilisez un existant)

3. Récupérez vos identifiants dans les paramètres du projet :

   • LIVEKIT_URL - URL WebSocket de votre projet (ex : wss://your-project.livekit.cloud)
   • LIVEKIT_API_KEY - Clé API pour l'authentification
   • LIVEKIT_API_SECRET - Secret API pour l'authentification

4. Définissez ces variables d'environnement (généralement dans .env.local) :

   LIVEKIT_URL=wss://your-project.livekit.cloud
   LIVEKIT_API_KEY=your-api-key
   LIVEKIT_API_SECRET=your-api-secret

La CLI LiveKit peut automatiser la configuration des identifiants. Consultez la documentation CLI pour les commandes actuelles.

Utilisez LiveKit Inference pour les modèles IA

LiveKit Inference est le moyen recommandé d'utiliser les modèles IA avec LiveKit Cloud. Il fournit l'accès aux principaux fournisseurs de modèles IA—tout à travers vos identifiants LiveKit sans clés API séparées nécessaires.

Avantages de LiveKit Inference :

• Pas de clés API séparées à gérer pour chaque fournisseur IA
• Facturation consolidée via votre compte LiveKit Cloud
• Optimisé pour les charges de travail IA vocales

Consultez la documentation pour les modèles disponibles, fournisseurs supportés et modèles d'utilisation actuels. La documentation contient toujours les informations les plus à jour.

Règle critique : Ne faites jamais confiance à la mémoire du modèle pour les APIs LiveKit

LiveKit Agents est un SDK en rapide évolution. Les données d'entraînement du modèle sont obsolètes au moment où elles sont créées. Lorsque vous travaillez avec LiveKit :

• Ne supposez jamais les signatures d'API, noms de méthodes ou options de configuration de mémoire
• Ne devinez jamais le comportement du SDK ou les valeurs par défaut
• Vérifiez toujours contre la documentation en direct avant d'écrire du code
• Citez toujours la source de documentation lors de l'implémentation de fonctionnalités

Cette règle s'applique même quand vous êtes confiant à propos d'une API. Vérifiez quand même.

REQUIS : Utilisez le serveur LiveKit MCP pour la documentation

Avant d'écrire n'importe quel code LiveKit, assurez-vous d'avoir accès au serveur MCP de documentation LiveKit. Cela fournit des informations API actuelles et vérifiées et évite la dépendance aux connaissances stéréotypées du modèle.

Vérifiez la disponibilité de MCP

Cherchez les outils MCP livekit-docs. S'ils sont disponibles, utilisez-les pour toutes les recherches de documentation :

• Consultez la documentation avant d'implémenter n'importe quelle fonctionnalité
• Vérifiez les signatures d'API et paramètres de méthode
• Recherchez les options de configuration et leurs valeurs valides
• Trouvez des exemples fonctionnels pour la tâche spécifique à accomplir

Si MCP n'est pas disponible

Si le serveur MCP LiveKit n'est pas configuré, informez l'utilisateur et recommandez l'installation. Les instructions d'installation pour toutes les plates-formes supportées sont disponibles sur :

https://docs.livekit.io/intro/mcp-server/

Récupérez les instructions d'installation appropriées pour l'agent de codage de l'utilisateur depuis cette page.

Solution de secours quand MCP n'est pas disponible

Si MCP ne peut pas être installé dans la session actuelle :

1. Informez l'utilisateur immédiatement que la documentation ne peut pas être vérifiée en temps réel
2. Utilisez la recherche web pour récupérer la documentation actuelle de docs.livekit.io
3. Marquez explicitement tout le code spécifique à LiveKit avec un commentaire comme # UNVERIFIED: Please check docs.livekit.io for current API
4. Déclarez clairement quand vous ne pouvez pas vérifier quelque chose : "I cannot verify this API signature against current documentation"
5. Recommandez à l'utilisateur de vérifier contre https://docs.livekit.io avant d'utiliser le code

Principes de l'architecture d'agents vocaux

Les agents IA vocaux ont des exigences fondamentalement différentes des agents basés sur le texte ou des logiciels traditionnels. Internalisez ces principes :

La latence est critique

Les conversations vocales sont en temps réel. Les utilisateurs s'attendent à des réponses en centaines de millisecondes, pas en secondes. Chaque décision architecturale doit considérer l'impact sur la latence :

• Minimisez la taille du contexte du LLM pour réduire le temps d'inférence
• Évitez les appels d'outils inutiles pendant la conversation active
• Préférez les réponses en streaming aux réponses par lot
• Concevez pour le scénario défavorable (retards réseau, délais d'expiration d'API)

L'encombrement du contexte tue la performance

Les grandes invites système et les listes d'outils étendues augmentent directement la latence. Un agent vocal avec 50 outils et une invite système de 10 000 tokens sera lent, indépendamment de la vitesse du modèle.

Concevez des agents avec un contexte viable minimal :

• N'incluez que les outils pertinents pour la phase de conversation actuelle
• Gardez les invites système focalisées et concises
• Supprimez les outils et le contexte qui ne sont pas activement nécessaires

Les utilisateurs n'lisent pas, ils écoutent

Les contraintes de l'interface vocale diffèrent du texte :

• Les réponses longues frustrent les utilisateurs—gardez les sorties concises
• Les utilisateurs ne peuvent pas faire défiler en arrière—assurez la clarté dès la première livraison
• Les interruptions sont normales—concevez pour une gestion gracieuse
• Le silence semble cassé—accusez réception du traitement quand nécessaire

Architecture de flux : Remises et tâches

Les agents vocaux complexes ne doivent pas être monolithiques. LiveKit Agents supporte les flux structurés qui maintiennent une faible latence tout en traitant des cas d'usage sophistiqués.

Le problème avec les agents monolithiques

Un seul agent gérant l'ensemble du flux de conversation accumule :

• Des outils pour chaque action possible (liste d'outils gonflée)
• Des instructions pour chaque phase de conversation (contexte gonflé)
• Gestion d'état pour tous les scénarios (complexité)

Cela crée de la latence et réduit la fiabilité.

Remises : transitions agent-à-agent

Les remises permettent à un agent de transférer le contrôle à un autre. Utilisez les remises pour :

• Séparer les phases de conversation distinctes (salutation → entrée → résolution)
• Isoler les capacités spécialisées (support général → spécialiste facturation)
• Gérer les frontières de contexte (chaque agent n'a que ce dont il a besoin)

Concevez les remises autour des frontières naturelles de conversation où le contexte peut être résumé plutôt que transféré en bloc.

Tâches : opérations limitées

Les tâches sont des invites fortement limitées conçues pour atteindre un résultat spécifique. Utilisez les tâches pour :

• Les opérations discrètes qui ne nécessitent pas l'ensemble des capacités de l'agent
• Les situations où une invite focalisée surpasse un agent à usage général
• Réduire le contexte quand seule une capacité spécifique est nécessaire

Consultez la documentation pour les détails d'implémentation sur les remises et tâches.

REQUIS : Écrivez des tests pour le comportement de l'agent

Le comportement de l'agent vocal est du code. Chaque implémentation d'agent DOIT inclure des tests. Livrer un agent sans tests, c'est livrer du code non testé.

Flux de test obligatoire

Lors de la construction ou modification d'un agent LiveKit :

1. Créez un répertoire tests/ s'il n'existe pas
2. Écrivez au moins un test avant de considérer l'implémentation complète
3. Testez le comportement principal que l'utilisateur a demandé
4. Exécutez les tests pour vérifier qu'ils passent

Processus de développement piloté par les tests

Lors de la modification du comportement de l'agent—instructions, descriptions d'outils, flux—commencez par écrire des tests pour le comportement désiré :

1. Définissez ce que l'agent devrait faire dans des scénarios spécifiques
2. Écrivez des cas de test qui vérifient ce comportement
3. Implémentez la fonctionnalité
4. Itérez jusqu'à ce que les tests passent

Cette approche évite de livrer des agents qui « semblent fonctionner » mais qui échouent en production.

Ce que chaque test d'agent devrait couvrir

Au minimum, écrivez des tests pour :

• Flux de conversation basique : L'agent répond correctement à une salutation
• Invocation d'outil (si les outils existent) : Les outils sont appelés avec les bons paramètres
• Gestion d'erreurs : L'agent traite l'entrée inattendue de manière gracieuse

Focalisez les tests sur :

• Invocation d'outil : L'agent appelle-t-il les bons outils avec les bons paramètres ?
• Qualité de réponse : L'agent produit-il des réponses appropriées pour les entrées données ?
• Transitions de flux : Les remises et tâches se déclenchent-elles correctement ?
• Cas limites : Comment l'agent traite-t-il l'entrée inattendue, les interruptions, le silence ?

Modèle d'implémentation de test

Utilisez le framework de test LiveKit. Consultez la documentation de test via MCP pour les modèles actuels :

search: "livekit agents testing"

Le framework supporte :

• Entrée utilisateur simulée
• Vérification des réponses de l'agent
• Assertions d'appel d'outil
• Test de transition de flux

Pourquoi c'est non-négociable

Les agents qui « semblent fonctionner » en test manuel échouent fréquemment en production :

• Les changements d'invite cassent silencieusement le comportement
• Les descriptions d'outils affectent quand les outils sont appelés
• Les mises à jour du modèle changent les modèles de réponse

Les tests attrapent ces problèmes avant que les utilisateurs ne les découvrent.

Ignorer les tests

Si un utilisateur demande explicitement pas de tests, procédez sans eux mais informez-le :

"I've built the agent without tests as requested. I strongly recommend adding tests before deploying to production. Voice agents are difficult to verify manually and tests prevent silent regressions."

Erreurs courantes à éviter

Surcharger l'agent initial

Commencer avec un agent qui « fait tout » et ajouter des outils/instructions au fil du temps. Au lieu de cela, concevez la structure du flux dès le départ, même si l'implémentation initiale est simple.

Ignorer la latence jusqu'à ce que ce soit un problème

Les problèmes de latence s'aggravent. Un agent qui semble « un peu lent » en développement devient inutilisable en production avec des conditions réseau réelles. Mesurez et optimisez la latence continuellement.

Copier des exemples sans comprendre

Les exemples de la documentation démontrent des modèles spécifiques. Copier du code sans comprendre son but conduit à des agents gonflés et mal structurés. Comprenez ce que chaque composant fait avant de l'inclure.

Ignorer les tests parce que « ce sont juste des invites »

Le comportement de l'agent est du code. Les changements d'invite affectent le comportement autant que les changements de code. Testez le comportement de l'agent avec la même rigueur que le logiciel traditionnel. Ne livrez jamais une implémentation d'agent sans au moins un fichier de test.

Supposer que la connaissance du modèle est actuelle

Réitérant la règle critique : ne faites jamais confiance à la mémoire du modèle pour les APIs LiveKit. Le SDK évolue plus vite que les cycles d'entraînement des modèles. Vérifiez tout.

Quand consulter la documentation

Consultez toujours la documentation pour :

• Signatures de méthode API et paramètres
• Options de configuration et leurs valeurs valides
• Fonctionnalités ou changements spécifiques à la version du SDK
• Configuration du déploiement et infrastructure
• Détails d'intégration du fournisseur de modèle
• Commandes et drapeaux CLI

Cette skill fournit des conseils sur :

• Approche architecturale et principes de conception
• Décisions de structure de flux
• Stratégie de test
• Pièges courants à éviter

La distinction importe : cette skill vous dit comment penser à la construction d'agents vocaux. La documentation vous dit comment implémenter des fonctionnalités spécifiques.

Boucle de rétroaction

Lorsque vous utilisez la documentation LiveKit via MCP, notez les lacunes, informations obsolètes ou contenu confus. Signaler les problèmes de documentation aide à améliorer l'écosystème pour tous les développeurs.

Résumé

Construire des agents vocaux efficaces avec LiveKit Cloud nécessite :

1. Utilisez LiveKit Cloud + LiveKit Inference comme fondation—c'est le chemin le plus rapide vers la production
2. Vérifiez tout contre la documentation en direct—ne faites jamais confiance à la mémoire du modèle
3. Minimisez la latence à chaque point de décision architecturale
4. Structurez les flux en utilisant les remises et tâches pour gérer la complexité
5. Testez le comportement avant et après les changements—ne livrez jamais sans tests
6. Gardez le contexte minimal—n'incluez que ce qui est nécessaire pour la phase actuelle

Ces principes restent valides indépendamment de la version du SDK ou des changements d'API. Pour tous les détails d'implémentation, consultez la documentation LiveKit via MCP.