Audit de Session agenttrace
Vue d'ensemble
Utilisez cette compétence pour inspecter les sessions d'agents de codage IA locales avec agenttrace. Elle se concentre sur le processus derrière une exécution : les pics de tokens et de coûts, les échecs d'outils, les boucles de réessai, les écarts de latence, les anomalies, les scores de santé et les différences entre sessions.
Agentrace est un outil local qui lit les journaux de sessions provenant d'outils tels que Claude Code, Codex CLI, Gemini CLI, Aider, les exports Cursor, OpenCode, Qwen Code, Kimi, et les traces génériques JSON ou JSONL.
Quand Utiliser Cette Compétence
- Utilisez-la lorsqu'un utilisateur demande pourquoi une exécution d'IA a été lente, coûteuse, superficielle ou peu fiable.
- Utilisez-la lors de la révision des journaux d'agents locaux avant de réessayer une tâche échouée ou suspecte.
- Utilisez-la lors de la construction d'une porte de contrôle CI légère pour les sessions de codage assisté par IA.
- Utilisez-la lorsque vous comparez deux tentatives et cherchez des chemins d'outils modifiés, des réessais ou des modèles de coûts.
Comment Cela Fonctionne
Étape 1 : Découvrir les Sessions Disponibles
Préférez un binaire agenttrace installé lorsqu'il est disponible dans le PATH. Si le
dépôt actuel est luoyuctl/agenttrace, utilisez go run ./cmd/agenttrace à la place.
agenttrace --doctor
agenttrace --overview
Si aucune session n'est détectée, signalez les répertoires vérifiés par --doctor et
demandez le fichier de session exporté ou le répertoire de journaux.
Étape 2 : Produire un Audit Lisible par un Humain
Utilisez Markdown lorsque l'utilisateur souhaite un rapport concis qu'il peut inspecter ou partager.
agenttrace --overview -f markdown -o agenttrace-overview.md
Dans le rapport, mettez en avant les sessions à plus haut risque et expliquez pourquoi elles sont importantes : anomalies critiques, échecs d'outils répétés, gaspillage de tokens ou de coûts, longs écarts de latence, scores de santé faibles et sessions anormalement superficielles.
Étape 3 : Inspecter une Session ou un Répertoire
Utilisez la dernière session pour une vérification rapide, ou passez un chemin d'export explicite lorsque l'utilisateur en fournit un.
agenttrace --latest
agenttrace --latest -f json
agenttrace path/to/session-or-export.json
agenttrace --overview -d path/to/session-dir
Étape 4 : Comparer les Tentatives Lorsque la Sémantique Compte
Les métriques de tokens et de latence peuvent sembler saines même lorsqu'un agent prend avec confiance la mauvaise voie d'implémentation. Lorsque le risque est une dérive sémantique, associez l'audit de trace à une différence par rapport à une tentative précédente ou connue comme bonne.
Recherchez :
- des fichiers ou commandes modifiés qui s'écartent de la tâche prévue
- des tests ou étapes de vérification manquants par rapport à la tentative de référence
- des modifications répétées autour des mêmes fichiers sans raison claire
- un coût plus faible résultant de l'omission d'explorations nécessaires
Étape 5 : Ajouter des Portes d'Automatisation
Pour les flux de travail CI ou d'équipe répétables, utilisez la sortie JSON ou des seuils de santé.
agenttrace --overview -f json -o agenttrace-overview.json
agenttrace --overview --fail-under-health 80 --fail-on-critical --max-tool-fail-rate 15
Ajustez les seuils au projet. Une porte stricte est utile pour les flux de travail critiques ; une commande de rapport uniquement est préférable pendant que l'équipe apprend sa ligne de base.
Exemples
Révision Locale Rapide
agenttrace --overview
agenttrace --latest
Utilisez ceci après une longue exécution d'agent de codage pour décider si l'invite suivante doit fractionner la tâche, éviter un chemin d'outil défaillant, ajouter des tests manquants ou réinitialiser le contexte.
Vérification de Santé CI
agenttrace --overview --fail-under-health 80 --fail-on-critical
Utilisez ceci lorsque les journaux de session d'agent sont disponibles dans CI et que l'équipe souhaite une protection simple contre les anomalies critiques ou les exécutions malsaines.
Bonnes Pratiques
- Commencez par
--doctorlorsque la découverte de session est incertaine. - Signalez clairement les champs manquants ; n'inventez pas de données de coût, de modèle, de latence ou de santé.
- Traitez les invites, le code et le contenu des sessions comme des données locales privées.
- Préférez la sortie JSON pour l'automatisation et la sortie Markdown pour la révision humaine.
- Utilisez les métriques de trace pour les échecs de processus et la révision des différences/références pour la dérive sémantique.
Limitations
- Agenttrace ne peut analyser que les journaux présents localement ou fournis en tant qu'exportations.
- Certains agents n'exposent pas suffisamment de champs pour déduire le coût, le modèle, l'utilisation du cache ou la latence.
- Des métriques de trace saines ne prouvent pas que le code final est correct ; exécutez toujours des tests et révisez les différences.
- Les portes CI devraient commencer comme consultatives jusqu'à ce que l'équipe comprenne le comportement de base normal.
Notes de Sécurité et de Sûreté
- Ne téléchargez pas de journaux de session privés vers des services externes sauf si l'utilisateur l'approuve explicitement.
- N'écrasez pas les rapports de l'utilisateur sauf s'il a demandé ce chemin de sortie exact.
- Évitez d'afficher les secrets trouvés dans les invites, les sorties d'outils, les variables d'environnement ou les journaux.
Pièges Courants
-
Problème : Aucune session n'est trouvée. Solution : Exécutez
agenttrace --doctor, puis pointez agenttrace vers le fichier exporté ou le répertoire de journaux. -
Problème : Une exécution semble bon marché et rapide mais a produit le mauvais refactoring. Solution : Comparez la session avec une tentative précédente ou une différence connue comme bonne ; les métriques de coût seules manqueront la dérive sémantique.
-
Problème : Le CI échoue trop souvent après l'ajout d'une porte de santé. Solution : Commencez par des rapports JSON ou Markdown, inspectez les lignes de base normales, puis resserrez les seuils progressivement.
Compétences Connexes
@langfuse- Utilisez pour le traçage et l'évaluation des applications LLM en production.@observability-engineer- Utilisez pour une surveillance de service plus large, des SLO et des flux de travail d'incidents.