Déboguer un agent LiveKit en direct
lk agent debugger exécute l'agent de l'utilisateur localement en tant que processus d'arrière-plan en mode texte et vous permet de conduire une conversation un tour à la fois. C'est conçu pour les agents de codage : vous jouez l'utilisateur, choisissez chaque ligne suivante en fonction de la dernière réponse, et inspectez ce que l'agent a fait entre les deux.
La parole est désactivée et rien ne va à une salle LiveKit, donc un tour coûte seulement les appels LLM et tool de l'agent lui-même. C'est assez bon marché pour utiliser constamment pendant la construction.
Avant la première utilisation, confirmez que la commande existe et lisez son aide :
lk agent debugger --helpL'aide est exhaustive et est la source de vérité pour les sous-commandes et les flags, donc cette skill ne les restate pas. Si la commande est manquante, la CLI installée la précède. Dites à l'utilisateur de mettre à jour lk et d'utiliser testing-livekit-agents jusqu'à alors. Ne devinez pas la forme d'une ancienne commande.
La boucle
Démarrez l'agent, dites les tours utilisateur, inspectez ce qui s'est passé, éditez le code, redémarrez, répétez, et arrêtez quand vous avez terminé. À peu près :
lk agent debugger start
lk agent debugger say "Hi, what can you do?"
lk agent debugger say "Book me a table for two tonight"
lk agent debugger stopChaque say affiche tout ce que l'agent a fait en réponse (appels tool avec arguments et résultats, handoffs, erreurs) suivi de la réponse. Entre les tours, vous pouvez consulter l'historique de chat de l'agent, un flux d'événements en direct, les logs du processus et l'état ; --help liste les sous-commandes.
Redémarrez après chaque modification du code. Une session en cours garde l'ancien code, et il est facile de perdre du temps en déboguant un comportement que le fichier n'a plus.
Déboguer avec
- Lisez les appels tool ainsi que la réponse. La réponse montre ce qui s'est mal passé ; l'appel tool et ses arguments montrent généralement pourquoi. Un mauvais argument pointe vers le prompt ou la description du tool. Aucun appel du tout signifie généralement que la description du tool ne dit jamais quand l'utiliser.
- Entrelacez les logs quand un tool ne fonctionne pas correctement. Une option affiche les lignes de log de l'agent sous le tour auquel elles appartiennent, donc la traceback du tool apparaît juste en dessous de l'erreur assainie que l'utilisateur aurait entendue. C'est le chemin le plus rapide du symptôme à la cause.
- Vérifiez l'historique de chat de l'agent au lieu de compter sur votre mémoire de la conversation. Il enregistre ce que le LLM a vu, y compris les changements d'instruction et de tool dans les handoffs. Quand le comportement semble impossible, l'historique montre généralement que le contexte n'est pas ce que vous aviez supposé.
- Reproduisez avant de réparer, puis réexécutez les mêmes tours. Conservez la séquence de lignes
sayqui ont déclenché le bug pour pouvoir comparer avant et après. - Conduisez des conversations entières. La plupart des bugs prennent plusieurs tours pour se manifester : les détails collectés tôt qui sont perdus, un utilisateur qui change d'avis en plein flux, un handoff qui perd le contexte. Un seul tour ne les trouvera pas.
- Scénárisez-le si un programme décide les tours. Il y a une sortie lisible par machine et des codes de sortie significatifs. Vérifiez
--helppour le format actuel au lieu de supposer les noms de champs.
Quand utiliser quelque chose d'autre
| Situation | Utiliser |
|---|---|
| Vous voulez l'entendre, ou confier quelque chose à l'utilisateur pour qu'il essaie | lk agent console (mic et haut-parleurs, un humain au clavier) |
| La même panne revient constamment | Un test au niveau des tours (testing-livekit-agents) |
| Vous avez besoin de résultats de conversation entière notés à l'échelle | Simulations (running-livekit-simulations) |
| Le bug concerne la parole : prise de parole, interruptions, transcription | Simulations audio. Le debugger est texte uniquement et ne peut pas voir celles-ci |
Le debugger est pour trouver des bugs de façon interactive. Une fois que vous en avez trouvé un, écrivez un test pour celui-ci afin qu'une modification ultérieure ne puisse pas le réintroduire sans être remarquée.
Skills connexes
- Construire l'agent :
building-livekit-agents - Épingler un bug trouvé comme test :
testing-livekit-agents - Vérifications de conversation entière :
writing-livekit-scenarios,running-livekit-simulations - Pannes exclusives à la production (processus worker, fournisseurs, shutdown) :
operating-livekit-agents - Flags CLI et faits API :
reading-livekit-docs