Traçage des appels d'outils d'agent IA : Que journaliser à chaque requête

Un utilisateur signale que l’agent « a fait quelque chose d’étrange » hier après-midi. Vous ouvrez les journaux et trouvez ceci :

INFO  agent run started
INFO  calling tool: updateOrder
INFO  tool returned 200
INFO  agent run completed

Essayez Apidog dès aujourd’hui

L’agent a appelé updateOrder, mais vous ignorez avec quels arguments, sur quelle commande, pourquoi il a choisi cet outil et ce qui est revenu. Un 200 ne permet pas de reconstruire une décision.

Les échecs d’agents ne deviennent souvent compréhensibles qu’après coup : le journal est donc un produit. Ce guide explique quoi tracer à chaque appel d’outil, comment relier la décision du modèle à la requête HTTP, quoi masquer et comment convertir les traces en tests. Pour la couche service, consultez l’observabilité des API.

Apidog devient particulièrement utile une fois la trace disponible : rejouez l’appel défaillant sur le même point de terminaison, inspectez la réponse et conservez le cas comme test.

Trois couches, une seule trace

Chaque action d’agent traverse trois couches :

1. Raisonnement : contexte fourni au modèle, outils disponibles, outil choisi et arguments générés.
2. Outil : validation, politique, transformation des arguments en requête HTTP, gestion du résultat.
3. HTTP : méthode, URL, en-têtes, corps, statut et latence.

Le débogage traverse presque toujours ces couches. Un mauvais identifiant client peut être généré par le modèle mais n’apparaître clairement que dans l’URL HTTP. À l’inverse, une API qui renvoie 200 avec un corps vide peut provoquer une décision absurde plusieurs étapes plus tard.

Utilisez donc :

• un trace_id par exécution d’agent ;
• un span_id par appel d’outil ;
• ces deux identifiants sur tous les événements, dans toutes les couches.

Les traces OpenTelemetry correspondent déjà à ce modèle. Les conventions sémantiques GenAI aident à nommer les attributs de façon portable.

Enregistrer chaque appel d’outil

Un événement utile ressemble à ceci :

{
  "trace_id": "run_01J8ZK3M2Q",
  "span_id": "call_004",
  "parent_span_id": "call_003",
  "timestamp": "2026-08-26T14:03:11.482Z",
  "agent": "billing",
  "step": 4,

  "tool_name": "refundOrder",
  "tool_args": {
    "orderId": "ord_92",
    "amount": 1200,
    "reason": "duplicate"
  },
  "tools_available": [
    "getOrder",
    "listOrders",
    "refundOrder",
    "voidInvoice"
  ],

  "http": {
    "method": "POST",
    "url": "/v1/orders/ord_92/refund",
    "request_body_hash": "sha256:1f4c...",
    "status": 200,
    "duration_ms": 412,
    "retry_count": 1,
    "idempotency_key": "9f2b7c14-6d3a-4b18"
  },

  "outcome": "success",
  "tokens": {
    "prompt": 8420,
    "completion": 96
  },
  "policy": {
    "approval_required": true,
    "approved_by": "user_31",
    "dry_run": false
  }
}

Les champs les plus importants sont les suivants :

• tool_args : enregistrez les arguments produits par le modèle avant normalisation par l’exécuteur. C’est là qu’un mauvais ID est visible.
• tools_available : explique le choix du modèle. Si l’outil sélectionné paraît étrange, vérifiez ses alternatives.
• retry_count : distingue un appel lent d’une API ayant échoué deux fois avant de réussir.
• outcome : utilisez une énumération explicite : success, failed, timed_out, blocked_by_policy, rejected_by_human. Un blocage de politique est un garde-fou réussi, pas une erreur.
• policy : fournit la piste d’audit : approbation requise, approbateur, simulation ou exécution réelle. Associez cela à des garde-fous d’agents IA.

Enregistrer la décision, pas uniquement l’action

Les bugs difficiles sont généralement des erreurs de choix. Tracez donc aussi :

• La définition ou le hachage des outils : si un comportement change, comparez le hachage entre une bonne et une mauvaise exécution. Une simple modification de description peut modifier la sélection ; c’est l’un des points clés de la conception de schémas d’outils.
• Le modèle et ses paramètres : ID du modèle, température et version du prompt. Sans eux, vous risquez d’enquêter sur votre code alors que le comportement a changé avec un modèle.
• Le contexte vu par le modèle : idéalement un hachage et un nombre de tokens. Un dump complet est coûteux et sensible ; un prompt deux fois plus grand que d’habitude est déjà un signal fort.
• La réponse brute de l’outil : stockez-la avant toute troncature. Si vous réduisez les réponses transmises au modèle pour préserver la fenêtre de contexte, comme expliqué dans ce guide, la trace doit conserver l’original.

Masquer avant de stocker

Les traces d’agents contiennent à la fois des requêtes et le contexte qui les explique ; elles peuvent donc inclure des données personnelles et des secrets.

Appliquez ces règles :

1. Ne stockez jamais les identifiants. Supprimez Authorization, clés API, cookies et URL signées. Conservez un ID de clé, pas sa valeur. Les clés API à privilège minimum permettent ensuite d’identifier l’agent concerné.
2. Masquez à la frontière. Le middleware de journalisation doit filtrer avant que l’événement ne quitte le processus. Filtrer à la lecture est trop tard : le secret a déjà été écrit, répliqué et sauvegardé.
3. Hachez les corps non stockables. Un hash permet de vérifier que deux appels étaient identiques sans retenir la charge utile.
4. Définissez une rétention par sensibilité. Par exemple : traces complètes pendant une semaine, résumés masqués pendant un an.

Transformer les traces en tests

Une trace exploitable est une source de tests réalistes.

Pour chaque exécution défaillante :

1. extrayez les appels d’outils ;
2. rejouez-les contre l’API ;
3. reconstruisez la requête comme cas enregistré dans Apidog ;
4. affirmez le comportement corrigé ;
5. exécutez ce test en CI.

Un incident ponctuel devient ainsi une couverture permanente.

Les traces indiquent aussi quoi simuler : les points de terminaison les plus utilisés et les statuts d’échec réellement rencontrés. Construisez vos mocks à partir de ces données, en suivant cette approche d’exécution d’agents contre des mocks plutôt que la production.

Elles révèlent enfin la dérive lente. Suivez chaque semaine :

• la distribution de sélection des outils ;
• le taux de réessais par point de terminaison ;
• les appels par tâche terminée ;
• le pourcentage d’exécutions bloquées par la politique.

Un changement est souvent un signal précurseur. Des tests de contrat d’API détectent fréquemment la modification amont responsable.

Trois enquêtes auxquelles vos traces doivent répondre

« L’agent a facturé le mauvais client »

Vous avez besoin des arguments du modèle, de l’URL résolue et de l’étape précédente. Souvent, un outil de recherche a retourné plusieurs correspondances et le modèle a choisi la première. La trace doit montrer l’ambiguïté, la réponse précédente et le choix final.

« Cela a cessé de fonctionner mardi »

Comparez une bonne et une mauvaise exécution champ par champ :

• ID du modèle ;
• hachage de l’ensemble d’outils ;
• version du prompt ;
• taille moyenne des réponses.

L’un de ces éléments identifie généralement le changement.

« Quelqu’un a-t-il approuvé cela ? »

Le bloc policy doit répondre directement, avec approval_required, approved_by et un horodatage écrits au moment de la décision. Ne tentez pas de reconstruire cette information après coup.

Aucune de ces enquêtes n’est résolue par « l’outil a renvoyé 200 ».

Échantillonner sans perdre les cas importants

Le traçage complet coûte du volume. Échantillonnez les bonnes exécutions, jamais les événements à forte valeur d’enquête.

Conservez systématiquement :

• chaque exécution échouée ;
• chaque exécution bloquée par la politique ;
• chaque exécution contenant une écriture.

Échantillonnez les exécutions réussies en lecture seule : elles constituent l’essentiel du trafic et servent surtout à calculer des références.

Le chapitre du livre SRE de Google sur la surveillance des systèmes distribués explique pourquoi il faut échantillonner pour le signal, pas pour le volume.

Même après suppression des charges utiles, gardez une trace squelette contenant les outils, résultats et durées. Les corps et prompts sont coûteux ; ce sont les premiers éléments à purger.

Attention à l’échantillonnage de queue : si une exécution paraît saine à l’étape 3 mais échoue à l’étape 9, conservez-la intégralement. Mettez les événements en mémoire tampon jusqu’à connaître le résultat final.

Où stocker la trace

Le stockage centralisé convient aux agents qui tournent dans vos services et appellent vos API.

Pour les agents de développement exécutés sur des machines locales, une autre approche est possible. Sharkly attache l’historique, le journal et le résultat d’exécution à la tâche assignée à l’agent. La question « pourquoi l’agent a-t-il fait cela ? » se résout alors depuis la tâche, son objectif, son statut et ses commentaires, plutôt qu’en retrouvant une machine et une session de terminal.

Cela ne remplace pas le traçage applicatif ni l’environnement d’exécution : Claude Code et Codex font toujours le travail. Cela améliore simplement la récupération du contexte lorsque l’agent n’est pas un service déployé.

Surveiller quatre chiffres

Ajoutez ces métriques à votre tableau de bord :

1. Appels par tâche terminée : mesure directe de l’efficacité. Une hausse signifie souvent que l’agent explore davantage, qu’un prompt s’est dégradé ou qu’un point de terminaison échoue.
2. Taux de réessais par point de terminaison : identifie les dépendances les moins fiables. Consultez ce guide de récupération d’erreurs d’agent pour traiter les principaux cas.
3. Taux de blocage par politique : il doit rester faible et stable. Un pic indique soit des actions inappropriées, soit une politique devenue goulot d’étranglement.
4. Temps jusqu’au premier appel d’outil : une hausse signale souvent un prompt gonflé.

Liste de contrôle

• [ ] Un ID de trace par exécution et un ID de span par appel d’outil, présents dans les trois couches.
• [ ] Arguments du modèle enregistrés avant normalisation.
• [ ] Liste des outils disponibles enregistrée à chaque appel.
• [ ] Résultat enregistré avec une énumération explicite, y compris les blocages de politique.
• [ ] Nombre de réessais distinct du nombre d’appels.
• [ ] Modèle, température, version du prompt et hachage des outils sur l’exécution.
• [ ] Réponses brutes d’outils conservées avant troncature.
• [ ] Identifiants supprimés dans le middleware et corps hachés si nécessaire.
• [ ] Rétention adaptée à la sensibilité.
• [ ] Traces défaillantes convertibles en tests rejouables.

L’objectif est simple : lorsqu’une personne demande pourquoi l’agent a agi ainsi, vous devez répondre à partir d’un enregistrement, pas d’une supposition. Téléchargez Apidog pour rejouer les appels d’une trace et conserver les reproductions comme tests.

Foire aux questions

Dois-je utiliser OpenTelemetry ou un outil d’observabilité dédié aux agents ?

Utilisez OpenTelemetry pour le transport et le modèle de trace : il gère déjà la corrélation et votre infrastructure le prend probablement en charge. Les outils dédiés ajoutent des vues utiles, mais les données sous-jacentes doivent rester portables.

Combien coûte le stockage d’un traçage complet ?

Moins que prévu si vous utilisez des niveaux de rétention : charges utiles complètes pendant quelques jours, puis enregistrements structurés sans corps sur une période plus longue. Les dumps de prompts coûtent le plus cher ; hachez-les et mesurez leur taille au lieu de les stocker par défaut.

Dois-je enregistrer le texte de raisonnement du modèle ?

Pas habituellement. L’outil choisi, les arguments générés et les alternatives disponibles expliquent la plupart des décisions. Si un fournisseur expose le raisonnement, conservez-le uniquement pour les échecs et traitez-le comme une donnée sensible.

Comment tracer plusieurs agents ?

Gardez un seul trace_id pour toute la tâche et donnez à chaque agent son propre span. Enregistrez chaque transfert comme événement, avec le contexte approprié, comme décrit dans ce guide sur le transfert multi-agent.

Que faire si l’agent s’exécute sur la machine d’un client ?

Journalisez localement, masquez agressivement et n’envoyez que des métriques agrégées sans consentement explicite. Les noms d’outils, résultats et durées suffisent généralement à surveiller une flotte sans faire sortir de charge utile de l’appareil.

Un hachage du corps de requête est-il réellement utile ?

Oui. Il permet de prouver que deux appels étaient identiques, ce qui résout la plupart des enquêtes sur les écritures en double sans stocker la charge utile. Associez-le à des clés d’idempotence qui auraient dû empêcher le doublon.