Comment Déboguer un Agent IA en Production (Guide de Terrain)

Table des matières

Mis à jour juin 2026.

TL;DR : Déboguer un agent IA en production consiste surtout à isoler la couche qui a échoué — prompt, appel d’outil, sortie du modèle ou orchestration. Je journalise chaque étape avec un ID de trace, je rejoue les entrées exactes et je dichotomise à partir de là. Dans mes agents, environ 70 % de ce qui ressemble à un « bug IA » s’avère être de la tuyauterie : un résultat d’outil malformé, une entrée tronquée, une exception silencieusement avalée.

Lecture de l’opérateur : J’exploite plus de 100 agents en production — flux de réservation pour Pickleland, pipelines de contenu, tri de boîtes de réception. Ils cassent comme tout logiciel casse, plus quelques nouvelles façons. Voici le guide de terrain que j’aurais aimé avoir : comment trouver la couche défaillante sans fixer un mur de tokens.

Quand un agent se comporte mal en production, l’instinct est de blâmer le modèle. « Claude a halluciné. » Parfois vrai. Généralement non. Le modèle est une couche dans une pile de cinq ou six, et le bug est bien plus souvent dans la couche que vous avez écrite que dans celle qu’Anthropic a livrée. Cet article décrit la manière systématique dont je le trouve.

Rendez chaque exécution traçable avant de déboguer quoi que ce soit

Vous ne pouvez pas déboguer ce que vous ne pouvez pas voir. La chose la plus efficace que vous puissiez faire — avant qu’un bug spécifique n’apparaisse — est d’attacher un ID de trace à chaque exécution de l’agent et de journaliser chaque étape qu’il franchit.

Une « étape » est tout ce qui traverse une frontière : le déclencheur entrant, chaque appel au modèle (avec le tableau complet des messages), chaque appel d’outil (avec les arguments), chaque résultat d’outil et la sortie finale. Journalisez-les sous forme de JSON structuré indexé par l’ID de trace.

function logStep(traceId: string, step: string, payload: unknown) {
  console.log(JSON.stringify({
    traceId,
    step,            // "trigger" | "model_call" | "tool_call" | "tool_result" | "output"
    ts: Date.now(),
    payload,
  }));
}

Sur Cloudflare Workers, je les envoie vers une file d’attente et dans une table ; en local, ils vont vers stdout. La règle est absolue : si une étape n’est pas journalisée, elle n’a pas eu lieu du point de vue du débogage. Cela reflète l’instrumentation que je décris dans la stack d’agents que j’utilise — l’ID de trace est la colonne vertébrale à laquelle tout le reste est accroché.

Isolez la couche : prompt, outil, modèle ou orchestration

Une fois que vous avez une trace, le débogage devient une dichotomie. Il y a quatre couches et le bug réside dans exactement l’une d’entre elles la plupart du temps.

1. La couche d’entrée (le coupable le plus fréquent)

Extrayez le tableau messages exact qui est entré dans l’appel au modèle défaillant. Pas une reconstruction — le payload littéral du journal. Puis lisez-le comme le ferait un inconnu. La moitié de mes bugs « le modèle a ignoré les instructions » sont en réalité :

• Un résultat d’outil revenu sous la forme "[object Object]" parce que quelque chose a été mal converti en chaîne.
• Une entrée tronquée en plein milieu d’une phrase parce qu’elle a fait exploser la fenêtre de contexte et qu’un découpage naïf l’a coupée.
• Une variable interpolée en undefined qui a silencieusement empoisonné le prompt.

Si l’entrée est mauvaise, le modèle a parfaitement fait son travail sur des déchets. Réparez la tuyauterie.

2. La couche outil

Si l’entrée semble propre, vérifiez si un outil a renvoyé une erreur que l’agent a traitée comme un succès. Un classique : une API renvoie 200 avec un corps { "error": "rate limited" }, votre wrapper d’outil ne vérifie pas le corps, et l’agent agit avec assurance sur un message d’erreur. Journalisez les résultats d’outil bruts et vérifiez leur forme.

3. La couche modèle

Ce n’est qu’après avoir écarté 1 et 2 que je soupçonne le modèle. Même alors, « bug du modèle » signifie généralement « mon prompt est ambigu ». Prenez l’entrée exacte défaillante, déposez-la dans un script ponctuel contre le même modèle et la même température, et voyez si cela se reproduit. Si c’est le cas, la solution est un travail de prompt ou une eval plus serrée, pas un changement frénétique de modèle.

4. La couche d’orchestration

Si une seule étape fonctionne en isolation mais que l’exécution multi-étapes échoue, le bug est dans le passage de relais — état perdu entre les étapes, condition de concurrence, nouvelle tentative qui a réexécuté une action non idempotente. Ce sont les plus pernicieux et je couvre les patrons dans les patrons d’orchestration multi-agents.

Reproduisez le non-déterminisme au lieu de le combattre

Ce qui rend les agents apparemment indéboguables, c’est le non-déterminisme : la même entrée produit une sortie différente selon les exécutions. Vous pouvez le dompter.

D’abord, figez ce que vous pouvez. Mettez temperature: 0 pendant le débogage. Cela ne rendra pas Claude totalement déterministe, mais cela réduit fortement la variance pour que vous puissiez distinguer un vrai bug du bruit d’échantillonnage.

Ensuite, exécutez-le N fois. Si une défaillance se reproduit 1 fois sur 20, bouclez l’entrée exacte 50 fois et capturez chaque sortie. Vous avez maintenant un échantillon, pas une anecdote. Un bug qui se déclenche 5 % du temps est un vrai bug — il vous faut juste du volume pour le voir.

for i in $(seq 1 50); do
  node replay.mjs --trace=abc123 >> runs.jsonl
done
# puis comptez les échecs
grep -c '"status":"fail"' runs.jsonl

Troisièmement, comparez les exécutions réussies et échouées. Avec la température figée et la même entrée, une différence de sortie signifie une différence d’entrée que vous n’avez pas encore repérée — un horodatage dans le prompt, un résultat d’outil qui varie, un document récupéré qui a changé.

Construisez un harnais de rejeu pour cesser de déboguer en production

Déboguer en redéclenchant l’agent en direct est lent et risqué — il envoie de vrais e-mails, réserve de vrais terrains. À la place, capturez la trace et rejouez-la hors ligne.

Le harnais de rejeu charge une trace journalisée, reconstruit les entrées exactes de n’importe quelle étape et réexécute uniquement cette étape contre le modèle. Comme vous avez journalisé le tableau complet messages, vous n’avez pas du tout besoin du système en amont. Cela transforme un aller-retour de 10 minutes en production en une boucle locale de 2 secondes, et c’est la plus grande accélération de mon flux de débogage.

Un bon harnais de rejeu vous permet aussi de muter et réexécuter : changez une ligne du prompt système, rejouez les mêmes 50 traces défaillantes et voyez combien passent désormais. C’est le pont entre le débogage et l’eval — une fois que vous avez un corpus de traces défaillantes, vous avez le début d’une suite de régression.

Surveillez les métriques qui prédisent réellement les pannes

Certaines défaillances ne lèvent jamais d’exception. L’agent s’exécute, renvoie quelque chose de plausible et fait silencieusement la mauvaise chose. Pour les attraper, vous surveillez des métriques comportementales, pas seulement des taux d’erreur :

• Taux de réussite des appels d’outil par outil. Une baisse ici précède souvent une défaillance visible.
• Validité du schéma de sortie — quel % des sorties parsent contre la structure attendue. Je valide chaque sortie avec Zod et j’alerte quand la validité baisse.
• Longueur de boucle — nombre moyen d’étapes par exécution. Un pic soudain signifie généralement que l’agent est coincé à réessayer.
• Coût par exécution — une boucle incontrôlée apparaît comme un pic de coût avant d’apparaître comme une plainte. (Quand le coût compte, les calculs Haiku vs Sonnet valent la peine d’être connus.)

Je suis ces métriques comme je suis tout le reste — voir comment je mesure si un agent IA fonctionne réellement. La métrique qui attrape une défaillance silencieuse en vaut dix qui attrapent les bruyantes.

La checklist de triage de 5 minutes

Quand un agent casse et que je suis contre la montre, je déroule ceci dans l’ordre :

1. Récupérez l’ID de trace de l’exécution défaillante.
2. Lisez l’entrée exacte de l’étape défaillante. Est-elle bien formée ? (Résout ~50 % des cas ici.)
3. Vérifiez les résultats d’outil dans cette trace pour des erreurs déguisées en succès.
4. Rejouez l’étape hors ligne à temperature: 0. Se reproduit-elle ?
5. Si elle se reproduit, c’est un problème de prompt/modèle — corrigez et réexécutez le corpus de traces. Sinon, c’est du non-déterminisme ou un bug d’état/orchestration — bouclez-le 50× pour le caractériser.

Une isolation disciplinée bat un prompting astucieux à tous les coups. Le modèle est rarement le problème ; le système autour de lui l’est généralement.

FAQ

Comment déboguer un agent IA qui n’échoue que parfois ?

Capturez l’entrée exacte d’une trace journalisée et rejouez-la plus de 50 fois à température 0. Les défaillances intermittentes sont de vrais bugs à faible taux de déclenchement — le volume transforme l’anecdote en un échantillon reproductible que vous pouvez comparer et corriger.

Le bug est-il généralement dans le modèle ou dans mon code ?

Dans mes agents de production, environ 70 % des apparents « bugs IA » sont de la tuyauterie : résultats d’outil malformés, entrées tronquées, exceptions avalées ou état perdu entre les étapes. Écartez les couches d’entrée et d’outil avant de soupçonner le modèle.

Quel est le minimum de journalisation nécessaire pour déboguer des agents ?

Un ID de trace sur chaque exécution, plus des journaux structurés du déclencheur, de chaque appel au modèle (tableau complet des messages), de chaque appel d’outil et de son résultat brut, et de la sortie finale. Si une étape n’est pas journalisée, vous ne pouvez pas la déboguer.

Comment cesser de déboguer contre la production en direct ?

Construisez un harnais de rejeu qui charge une trace journalisée et réexécute n’importe quelle étape unique hors ligne en utilisant les entrées capturées. Il transforme un aller-retour lent et risqué en production en une boucle locale rapide et devient la graine de votre suite de régression.