Observabilité des agents IA : comprendre ce qu'a fait l'agent et que journaliser pour cela

Qu'est-ce que l'observabilité d'un agent IA

L'observabilité d'un agent IA, c'est la capacité de répondre à trois questions à partir des artefacts, et non à partir de sa mémoire ni de ses propres affirmations : qu'a-t-il fait, pourquoi l'a-t-il fait ainsi et qu'est-ce qui prouve que le résultat est correct. Si, après vingt minutes de travail, l'agent dit « c'est fait, mais deux tests échouent, peut-être à cause d'un problème de timing », et qu'à la question « quels chemins ont été touchés ? » il répond « donnez-moi le code à regarder », il n'y a pas d'observabilité. L'agent n'est pas bête : il n'a simplement rien à vous présenter.

Le problème est systémique. Le même agent peut dire dix fois en une semaine « c'est fait », et chaque fois cela voudra dire autre chose : parfois tous les tests ont été lancés, parfois un seul, parfois aucun. Plus le projet vit longtemps, plus chaque nouvelle session coûte cher, car elle commence par des fouilles.

Deux couches : l'exécution et le processus

On confond souvent l'observabilité avec les journaux, mais les journaux ne sont qu'une moitié.

Seule l'exécution : on voit ce qui a échoué, mais on ne sait pas ce qu'on voulait obtenir. Seul le processus : on sait ce qu'on voulait, mais on ne voit pas pourquoi cela n'a pas marché. Il faut les deux.

Pourquoi l'agent ne peut pas le faire seul

Dire à l'agent « journalise mieux » ne fonctionne pas, pour trois raisons.

• Il ne sait pas ce qu'il ignore. L'agent ne journalisera pas un signal dont il ne soupçonne pas l'importance.
• Le format varie. Dans une session il écrit en détail, dans une autre sur une seule ligne. Impossible alors de comparer les sessions ou de calculer des agrégats.
• Le processus ne se referme pas avec des journaux. La réponse à « pourquoi comme ça ? » se trouve dans les documents rédigés avant le travail, et non dans la sortie des commandes.

C'est pourquoi l'observabilité se conçoit dans le harnais, c'est-à-dire dans l'environnement de l'agent : modèles, hooks, scripts, format de rapport obligatoire.

Que journaliser : le minimum

Un bon journal n'est pas une transcription de tout, mais un ensemble de faits qui permettent de reconstituer le déroulement du travail et de calculer des statistiques.

• Identifiants : identifiant de la session, identifiant de la tâche ou de la fonctionnalité, modèle de l'agent.
• Actions à effets de bord : quelles commandes ont été lancées, quels fichiers ont été modifiés. La lecture de fichiers, en général, n'a pas besoin d'être consignée.
• Résultats des contrôles : quelle commande de contrôle, code de retour, nombre de tests réussis et échoués.
• Relances : combien de tentatives ont été nécessaires pour une étape et en quoi elles différaient.
• Consommation : tokens et temps, si l'outil les fournit.
• Issue : tâche acceptée, rejetée ou abandonnée, et pourquoi.

Ce qu'il ne faut pas écrire : les secrets, les jetons d'accès, les données personnelles extraites de la sortie des commandes. Le journal peut être partagé ou réintroduit dans le contexte du modèle.

Journal des actions via les hooks de Claude Code

Dans Claude Code, le journal se tient le plus simplement avec les hooks : des commandes lancées par l'outil lui-même et non par le modèle, donc elles se déclenchent systématiquement. Le hook reçoit en entrée un JSON décrivant l'événement, dont l'identifiant de session, le nom de l'outil et ses paramètres. Exemple de configuration dans .claude/settings.json qui ajoute une ligne au journal après chaque appel de Bash, Edit ou Write :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/log-action.sh" }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
# .claude/hooks/log-action.sh — une ligne JSON par action
mkdir -p .agent/logs
jq -c '{ts: (now | todate), session: .session_id, tool: .tool_name,
        cmd: .tool_input.command, file: .tool_input.file_path}' \
  >> .agent/logs/actions.jsonl || true

Le format JSONL (un enregistrement JSON par ligne) est pratique : on le filtre facilement avec jq et on peut le charger dans n'importe quel outil d'analyse. Par ailleurs, Claude Code conserve localement l'historique complet des sessions dans le répertoire ~/.claude/projects/ : on peut l'ouvrir pour voir le raisonnement et la sortie complète, mais pour les statistiques, votre propre journal compact est plus commode.

Traçage : une trace par session, un span par tâche

Lorsque les agents sont nombreux ou travaillent selon un calendrier, les journaux textuels ne suffisent plus : il faut des agrégats. Les outils classiques de traçage distribué et le standard OpenTelemetry sont alors utiles.

• Trace — une session de l'agent.
• Span — une tâche à l'intérieur de la session.
• Spans imbriqués — les étapes de vérification : build, tests, e2e.

Attributs minimaux par span : identifiant de la fonctionnalité et de la session, modèle, résultat du contrôle, tokens, nombre de relances. Ces données se lisent dans Jaeger, Grafana Tempo ou Honeycomb et répondent aux questions qu'une seule session ne montre pas : quel type de tâche demande le plus de relances, où l'agent dépense le plus de tokens, après quel changement du harnais la part des tâches acceptées a chuté. Claude Code propose aussi un export intégré des métriques et des événements via OpenTelemetry, activé par des variables d'environnement ; les détails figurent dans la documentation de l'outil.

Les commits comme journal

Le journal le moins cher et le plus fiable existe déjà : c'est git. Il suffit de le rendre lisible.

1. Un commit — une tâche. Ainsi, git log correspond à la liste de ce qui a été fait, et l'annulation d'une tâche tient en un seul git revert.
2. Dans le message — ce qui a été fait et comment c'est vérifié. Non pas « fix », mais « ce qui a changé, pourquoi, avec quelle commande c'est vérifié ».
3. Commit seulement après un contrôle vert. Ainsi, chaque point de l'historique est un état de travail, et git bisect trouve le coupable.

fix(payments) : arrondi de la remise au centime

Remise calculée en float, sur un montant de 999.99 un centime se perdait.
Calcul passé en int, en centimes.
Vérifié : make test (142 passed), make e2e checkout — ok.
Hors périmètre : arrondi dans les rapports, noté dans BACKLOG.md.

Le rapport de l'agent : des preuves plutôt que des impressions

Le message final de l'agent est lui aussi un artefact d'observabilité, à condition d'avoir une forme fixe. Inscrivez un modèle dans AGENTS.md ou CLAUDE.md :

## Rapport en fin de tâche
- Ce qui a été fait : liste des modifications (fichier — essentiel)
- Comment c'est vérifié : commandes exactes et leur résultat
- Ce qui N'A PAS été vérifié et pourquoi
- Écarts par rapport au contrat de la tâche
- Questions ouvertes pour l'humain

Règle principale : chaque affirmation renvoie à une preuve — un fichier et une ligne, la sortie d'un test, une entrée du journal. « Ça a l'air correct » et « je pense que c'est bon » ne comptent pas comme un rapport. Le point « ce qui n'a pas été vérifié » est particulièrement précieux : il montre honnêtement les limites de la confiance.

Le contrat avant le code et la grille après

La couche de processus commence avant le travail. Un contrat court sur la tâche (sprint contract) fixe le périmètre, les critères d'acceptation, une section « hors périmètre » et les questions ouvertes que tranche l'humain. La section « hors périmètre » évite à elle seule la moitié des désaccords sur le résultat.

Après le travail, le résultat s'évalue selon une grille, et non selon une impression. Sinon, deux relecteurs expérimentés donneront des verdicts différents, et l'évaluation devient une loterie.

Chaque dimension est notée de A à D, et une note sans référence n'est pas valable. Règle de décision simple : un D ou deux C — refus, avec la liste de ce qu'il faut corriger. Cette même grille peut être appliquée par un agent vérificateur distinct.

Comment analyser ce qu'a fait l'agent pendant une session

Si le rapport manque ou qu'on ne peut pas s'y fier, parcourez les artefacts dans cet ordre.

1. État de l'arbre : git status — ce qui n'est pas commité, s'il reste des fichiers parasites.
2. Historique : git log --stat depuis le début de la session — quels commits et quels fichiers.
3. Ampleur des modifications : git diff --stat main...HEAD, puis le diff complet des fichiers importants.
4. Journal des actions : quelles commandes ont été lancées et ce que les contrôles ont renvoyé.
5. Nouvelle vérification : relancez vous-même le build et les tests. Faites confiance à la sortie d'une commande, pas à sa paraphrase.

# quelles commandes l'agent a lancées dans la dernière session
jq -r 'select(.tool=="Bash") | .cmd' .agent/logs/actions.jsonl | tail -n 30
# quels fichiers ont été modifiés le plus souvent
jq -r '.file // empty' .agent/logs/actions.jsonl | sort | uniq -c | sort -rn | head

Erreurs fréquentes

• Tout journaliser. Des gigaoctets de transcriptions que personne ne lit. Consignez les actions à effets de bord et les résultats des contrôles.
• Format libre. Si c'est l'agent qui définit le format du journal, il n'y aura pas d'agrégats. Le format doit être fixé par le harnais.
• Croire le rapport sans la sortie des commandes. « Les tests sont verts », sans la sortie, c'est une opinion.
• Relances aveugles. Sans cause identifiée, l'agent corrige au hasard. Exigez d'abord un diagnostic avec référence au journal, puis la correction.
• « On nettoiera plus tard ». Les fichiers de débogage et les modifications non commitées désorientent la session suivante : elle ne distingue pas le provisoire de l'intentionnel.

En résumé

L'observabilité des agents IA repose sur deux couches : l'exécution (journal des actions via les hooks, traces, commits décrivant les contrôles) et le processus (contrat sur la tâche avant le code, grille et rapport avec des preuves). Ainsi, « c'est fait » signifie la même chose d'une session à l'autre, et l'analyse du travail d'un agent prend quelques minutes. Ce sujet est traité en pratique dans le cours sur l'ingénierie des harnais, sur un projet de backend de paiement.