Débogage d'agent IA : votre tableau de bord connaît le coût, pas la cause.

Le débogage d'un agent IA commence là où votre tableau de bord d'observabilité s'arrête. Quand un agent de codage IA casse quelque chose et que l'exécution est déjà terminée, le tableau de bord peut vous indiquer le coût de l'exécution (jetons, dollars, latence), mais il restera muet sur la seule question que vous vous posez réellement : pourquoi l'agent a-t-il modifié ce fichier ? L'artefact qui y répond est une trace enregistrée que vous pouvez ouvrir, lire et rejouer, car elle vous rend l'exécution au lieu de la décrire de l'extérieur.

Cela a cessé d’être un événement rare dès l’instant où les agents ont commencé à faire du vrai travail. Un agent va balayer un dépôt, modifier plusieurs fichiers, exécuter les vérifications et rapporter un succès, le tout entre deux invites que vous avez tapées à quelques minutes d’intervalle. Si l’une de ces modifications est erronée, vous vous en rendez compte plus tard : après la fermeture du terminal, après la disparition du scrollback, après la sortie du processus qui aurait pu s’expliquer. Ce qui suit dépend entièrement de ce que vous avez conservé. Si la réponse est un tableau de bord des coûts, vous vous apprêtez à faire de l’archéologie. Si la réponse est un enregistrement, vous vous apprêtez à faire de la lecture.

L'échec que vous ne pouvez pas reproduire

Voici à quoi cela ressemble. Vous revenez sur le dépôt et un fichier que vous n'avez jamais demandé à personne de toucher a été réécrit, supprimé, ou vidé de la fonction dont tout le reste dépend. Vous demandez à l'agent ce qui s'est passé ; la session est fermée, et même lorsqu'il reste une transcription, le compte rendu que l'agent donne de sa propre exécution est une reconstruction, pas un enregistrement. Vous faites donc la chose naturelle : vous relancez, et vous obtenez une exécution différente. Des appels d'outils différents, des modifications différentes, peut-être aucun échec du tout, car la trajectoire d'origine dépendait de l'échantillonnage, de l'état du dépôt, du timing. L'exécution que vous devez inspecter n'existe plus.

C'est pire que non reproductible. C'est non reproductible et marqué comme succès. Une exécution sort avec le code 0 lorsque l'agent sort avec le code 0, même si une vérification à l'intérieur de l'exécution est sortie avec le code 1 : le pipeline peut être vert alors qu'une étape de vérification à l'intérieur de l'exécution a échoué, et le code de sortie auquel vous vous fieriez naturellement ne vous dit rien.

Peu importe le modèle que le routeur a choisi pour l'exécution (GLM 5.3 Flash ou tout autre) : une fois le processus terminé, le raisonnement disparaît avec lui. Les preuves n'existaient que pendant que l'exécution était en cours : les prompts, les appels d'outils, les sorties, les diffs. Si rien ne les a enregistrés, « pourquoi a-t-il modifié ce fichier » n'a pas de réponse. Il n'a que des théories.

C'est le mode de défaillance qui sépare les agents de codage IA de tous les outils qui les ont précédés : les dégâts et l'explication se produisent au même endroit, et l'endroit se ferme.

Que mesure un tableau de bord, et que laisse-t-il de côté ?

L'instinct après une exécution qui s'est mal passée est d'ouvrir le tableau de bord d'observabilité, et ce tableau de bord fera parfaitement son travail. Son travail, c'est le trafic : tokens par jour, coût par modèle, latence, taux d'erreur. Pour la planification de capacité et la facturation, c'est exactement l'outil qu'il faut, et si vous faites tourner des agents en production, vous devriez le garder ouvert.

Mais votre question n’est pas une question d’agrégat. Elle est singulière et causale : pourquoi cette exécution a-t-elle modifié ce fichier ? L’agrégation saute précisément par-dessus la granularité qui y répond. En faisant la moyenne sur les exécutions, celle qui vous intéresse n’est que du bruit ; au sein de cette exécution, l’appel d’outil qui vous intéresse est à nouveau du bruit.

Un tableau de bord décrit une exécution de l'extérieur : qu'elle a eu lieu, ce qu'elle a pesé, ce qu'elle a coûté. Il ne peut pas vous remettre l'exécution elle-même, et le « pourquoi » n'est pas une propriété de la description. C'est une propriété de la séquence.

• Combien a coûté l’exécution ? — Le tableau des coûts y répond vs la trace enregistrée y répond

• Pourquoi l'agent a-t-il modifié ce fichier ? — Tableau de bord des coûts Aucune réponse vs trace enregistrée La modification, dans l'ordre, avec son diff

• Quel contrôle a échoué lors d'une exécution verte ? — Tableau de bord des coûts : aucune réponse vs trace enregistrée. Le contrôle, avec son code de sortie.

• Puis-je relancer exactement la même défaillance ? — Tableau de bord des coûts : Non vs Trace enregistrée : Oui, hors ligne, sans frais

La couche qui y répond se trouve en dessous : les journaux de requêtes enregistrés, capturés pendant l’exécution, avec chaque prompt envoyé, chaque appel d’outil émis, chaque réponse reçue, dans l’ordre. Pas un résumé de l’exécution. L’exécution elle-même.

Lire une exécution comme une chronologie

Avec un enregistrement, le débogage ne relève plus de l'archéologie, mais de la lecture. L'archéologie, c'est ce qu'on fait sans enregistrement : git reflog, entrées de stash, historique du shell, votre propre souvenir de ce que vous avez demandé plus tôt dans la journée. La lecture, c'est ce qu'on fait avec un enregistrement : ouvrez la chronologie et faites défiler.

La chronologie présente le déroulement dans l’ordre où il s’est produit : le prompt qui l’a déclenché, chaque appel d’outil, chaque modification de fichier avec son diff, chaque vérification, chaque code de sortie. Une capture du système de fichiers est effectuée une fois par tour plutôt qu’une fois par appel d’outil, ce qui suffit pour voir l’état du dépôt à chaque étape de la conversation, sans se noyer dans le bruit de chaque appel. Ce qui en fait du débogage plutôt que de la consultation, c’est l’adjacence : la modification et la vérification qui a détecté l’erreur se suivent dans l’ordre, sans qu’aucun élément intermédiaire ne donne matière à spéculation. Le « pourquoi » tient surtout à l’adjacence.

Un exemple concret, extrait d'une correction enregistrée : 14 événements, dont la modification de fichier affichée comme +1 -3 et un contrôle ayant échoué avec le code de sortie 1. La modification, puis le contrôle qui a échoué à cause d'elle, sont adjacents dans l'enregistrement. C'est là toute la différence entre reconstruire une exécution à partir de fragments et en lire une. Cela importe avant tout pour les agents de codage en terminal, dont l'espace de travail est un terminal qui se ferme dès que la tâche est terminée : la chronologie est le tampon de défilement qui survit.

Enregistré ou déduit : ce que la trace sait par rapport à ce qu'elle a déduit

Une chronologie vous dit ce qui s'est passé dans l'ordre. Le graphe causal vous dit ce qui a mené à quoi, et l'écart entre les deux est l'espace où la confiance doit être gagnée.

Le graphe relie des événements : cette modification, puis ce contrôle qui échoue. Certaines de ces arêtes sont des faits enregistrés : l'appel d'outil qui a produit le diff est présent dans la trace. D'autres sont inférées : la conclusion du graphe selon laquelle le contrôle a échoué à cause de ce diff. orca graph étiquette chaque arête comme enregistrée ou inférée et nomme la règle utilisée dans les deux cas, si bien que vous savez toujours si vous regardez quelque chose que l'exécution a fait ou quelque chose que l'outil a déduit à propos de l'exécution.

Cette distinction est appliquée, pas simplement souhaitée : les arêtes inférées ne sont jamais réécrites dans la trace. La trace reste un enregistrement fidèle de ce qui s'est passé ; l'inférence est une vue qui s'y superpose, que vous pouvez inspecter, remettre en question et contester. Cela importe surtout lorsque plusieurs agents sont impliqués. Quand un agent de refactorisation et un agent d'écriture de tests touchent aux mêmes fichiers, « quel agent a causé ce changement » est précisément la question à laquelle l'attribution multi-agents a pour but de répondre. Une arête qui se promeut en silence du statut d'inférence à celui de fait, voilà comment on finit par déboguer un récit au lieu d'une exécution.

Le reproduire aussi souvent que vous le souhaitez, gratuitement

Lire explique. Rejouer prouve. Une fois que vous avez une hypothèse (le contrôle a échoué parce que la modification a supprimé l'appel de réinitialisation), vous voulez le relancer et voir le phénomène se produire. Relancer l'agent en direct vous vaut une nouvelle trajectoire et une nouvelle facture.

Rejouer l'enregistrement vous donne la même exécution : la relecture se fait avec le réseau bloqué, elle ne coûte donc aucun jeton et ne comporte aucune variance. Mêmes événements, à chaque fois, hors ligne. C'est cette propriété qui fait passer le débogage d'agents du pari à l'ingénierie : l'échec est devenu déterministe, et les échecs déterministes se corrigent.

L'outillage n'est pas non plus une boîte noire. OrcaReplay est open source sous licence Apache-2.0 et le format de trace est en CC BY 4.0, donc n'importe qui peut le réimplémenter : vos enregistrements ne sont pas otages d'un format propriétaire, les nôtres non plus. Et il est mis à l'épreuve, pas seulement présenté : 1393 tests sur Node 20 et Node 22. Vous pouvez lire le code source, vérifier le format et exécuter la suite vous-même avant de faire confiance à tout cela pour les exécutions de votre équipe.

Le point à retenir

Un tableau de bord est une facture. Une trace enregistrée est l’exécution. Si votre plan de débogage d’agents IA s’arrête à un tableau de bord des coûts, vous n’avez pas de plan de débogage : vous avez un système de facturation. Le tableau de bord pourra toujours vous dire combien une exécution a coûté, et il ne pourra jamais vous dire pourquoi l’agent a supprimé votre fichier, car le « pourquoi » vit dans la séquence, et la séquence n’existe que si vous l’avez conservée.

La méthode complète comporte quatre étapes :

• Enregistrez les courses.

• Lisez la chronologie.

Vérifiez les arêtes du graphe.

Rejouez ceux qui vous effraient, gratuitement, aussi souvent que vous le souhaitez.

Note sur les sources : chaque chiffre de cet article est rapporté par le fournisseur et provient de notre propre produit, du dépôt OrcaReplay et de sa documentation : le comportement du code de sortie d’une exécution, le correctif enregistré de 14 événements avec son diff +1 -3 et sa vérification du code de sortie 1, l’étiquetage des arêtes du graphe orca, la cadence d’un instantané par tour, le rejeu hors ligne avec le réseau bloqué et la suite de 1393 tests sur Node 20 et Node 22. Aucune mesure de tiers n’est citée dans cet article. La suite de 1393 tests est la seule affirmation que vous pouvez vérifier vous-même : clonez le dépôt et exécutez-la. Tous les éléments ont été vérifiés pour la dernière fois le 4 septembre 2026.