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
L'agent a appelé updateOrder. Vous ne savez pas avec quels arguments, sur quelle commande, pourquoi il a choisi cet outil, ni ce qui est revenu. L'exécution a réussi selon toutes les mesures que vous avez enregistrées, et vous ne pouvez pas reconstituer une seule décision qu'il a prise.
Les systèmes d'agents échouent d'une manière qui n'a de sens qu'après coup, ce qui signifie que le journal est le produit. Ce guide couvre ce qu'il faut enregistrer à chaque appel d'outil, comment corréler une décision de modèle avec la requête HTTP qu'elle a produite, ce qu'il faut masquer, et comment transformer les traces en tests. Notre article sur l'observabilité des API couvre le côté service ; celui-ci couvre la couche agent qui le surmonte.
Apidog est utile une fois que vous avez une trace, car la manière la plus rapide de comprendre un mauvais appel est de le rejouer sur le même point de terminaison et d'observer ce qui se passe.
Trois couches, une trace
Un agent produit des événements à trois niveaux, et la plupart des équipes n'enregistrent que le niveau intermédiaire.
La **couche de raisonnement** est l'endroit où le modèle prend des décisions. Ce qui était dans le contexte, quels outils ont été proposés, lequel il a choisi, et avec quels arguments.
La **couche outil** est votre exécutor. Elle valide les arguments, applique la politique, mappe l'appel à une requête HTTP, et gère le résultat.
La **couche HTTP** est le fil. Méthode, URL, en-têtes, corps, statut, latence.
Le débogage traverse presque toujours les couches. « L'agent a envoyé le mauvais identifiant client » est un problème de raisonnement visible uniquement au niveau de la couche HTTP. « L'API a renvoyé un 200 avec un corps vide » est un problème HTTP qui se manifeste par un raisonnement étrange trois étapes plus tard. Si les trois couches ne sont pas liées par un identifiant partagé, vous êtes obligé de corréler par horodatage, ce qui cesse de fonctionner dès que deux exécutions se chevauchent.
Donc, la première règle : un ID de trace par exécution d'agent, un ID de span par appel d'outil, et les deux estampillés sur chaque enregistrement à chaque couche. Les traces OpenTelemetry modélisent déjà exactement cette forme, et il existe un ensemble croissant de conventions sémantiques GenAI pour nommer les attributs afin que vos données soient portables.
Ce qu'il faut enregistrer à chaque appel d'outil
Un enregistrement qui répond à de vraies questions a en gros cette forme :
{
"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 }
}
Cinq champs accomplissent un travail disproportionné.
tool_args est celui qui manque le plus souvent, et c'est celui que vous voulez toujours. Enregistrez les arguments produits par le modèle, avant que votre exécutor ne les normalise. Lorsqu'un agent envoie le mauvais ID, c'est là que c'est visible.
tools_available explique la sélection. Si le modèle a choisi un outil étrange, la première question est de savoir ce qu'il avait d'autre à choisir. Ce champ coûte quelques octets et y répond instantanément.
retry_count distingue « l'API était lente » de « l'API a échoué deux fois puis a fonctionné ». Sans cela, trois tentatives ressemblent à un seul appel.
outcome devrait être une énumération explicite, et non quelque chose inféré d'un code de statut. success, failed, timed_out, blocked_by_policy, rejected_by_human. Les deux derniers sont importants car un appel bloqué est un garde-fou fonctionnel, pas une erreur, et les mélanger corrompt votre taux d'échec.
policy est votre piste d'audit. Lorsque quelqu'un demande si une action destructive a été approuvée, c'est la réponse. Cela s'associe à l'application décrite dans notre article sur les garde-fous des agents IA.
Enregistrez la décision, pas seulement l'action
Les bugs d'agent les plus difficiles sont des choix, alors enregistrez suffisamment pour les reconstituer.
Conservez les définitions d'outils utilisées pour l'exécution, ou un hachage de celles-ci. Lorsque la précision de la sélection change, le premier suspect est une description que quelqu'un a modifiée, et un hachage vous indique immédiatement si l'ensemble d'outils a changé entre une bonne exécution et une mauvaise. Notre article sur la conception de schémas d'outils explique pourquoi ce texte modifie tant le comportement.
Enregistrez le modèle et ses paramètres. L'ID du modèle, la température et la version du prompt figurent dans l'enregistrement de l'exécution. Le comportement change entre les versions de modèles, et sans ce champ, vous passerez une journée à enquêter sur votre propre code.
Enregistrez ce que le modèle a vu, ou du moins sa taille. Un dump complet du prompt est coûteux à stocker et souvent sensible. Un nombre de tokens plus un hachage vous donnent la plupart de la valeur diagnostique : une exécution dont le prompt est deux fois la taille habituelle est une exécution où quelque chose a été ajouté qui n'aurait pas dû l'être.
Enregistrez le résultat brut de l'outil avant de le tronquer. Si votre exécutor réduit les réponses avant de les transmettre au modèle, comme dans notre article sur la maintien des réponses d'outils hors de la fenêtre de contexte, stockez la charge utile complète dans la trace. Sinon, vous ne pouvez pas savoir si les données manquaient ou si vous les avez supprimées.
Masquez avant de stocker
Les traces d'agents sont inhabituellement dangereuses car elles contiennent à la fois la requête et le raisonnement qui l'entoure, et les prompts ont tendance à collecter des données personnelles.
Quatre règles permettent de gérer cela.
Ne jamais stocker les identifiants. Supprimez Authorization, les clés API, les cookies et toute URL signée. Enregistrez l'identifiant de l'identifiant, comme un ID de clé, et non la valeur. Notre article sur les clés API à privilège minimum pour les agents explique pourquoi vous voulez cet identifiant : il vous indique quel agent a agi.
Masquez à la frontière, pas dans la requête. Filtrer au moment de la lecture signifie que le secret a été écrit sur le disque, répliqué et sauvegardé. Masquez dans le middleware de journalisation avant que l'enregistrement ne quitte le processus.
Hachez les corps que vous ne pouvez pas stocker. Un hachage du corps de la requête vous permet toujours de prouver que deux appels étaient identiques, ce qui est la plupart de ce dont vous avez besoin pour les enquêtes sur les doublons, sans conserver la charge utile.
Définissez la rétention par sensibilité. Traces complètes pendant une semaine, résumés masqués pendant un an. La plupart des débogages se font en quelques jours ; la plupart des questions d'audit arrivent en quelques mois.
Transformez les traces en tests
L'avantage d'un bon traçage n'est pas seulement un débogage plus rapide. C'est une source de cas de test réalistes.
Chaque exécution échouée est un scénario. Prenez les appels d'outils d'une mauvaise trace, rejouez-les contre votre API, et vous avez une reproduction. Lorsque la correction est déployée, conservez la relecture comme test de régression. Dans Apidog, vous pouvez reconstruire la requête défaillante comme un cas enregistré, affirmer le comportement corrigé, et l'exécuter en CI, ce qui est la façon dont un incident ponctuel se transforme en couverture permanente.
Les traces vous indiquent également ce qu'il faut simuler. Les points de terminaison que votre agent appelle le plus souvent, et les statuts d'échec qu'il rencontre réellement, proviennent directement des données plutôt que de suppositions. Construisez les mocks autour de ceux-ci, en suivant notre article sur l'exécution d'agents contre des mocks plutôt que la production.
Et elles révèlent la dérive lente que vous auriez autrement manquée. Suivez quelques chiffres par semaine : distribution de la sélection d'outils, taux de réessais par point de terminaison, appels par tâche terminée, et pourcentage d'exécutions bloquées par la politique. Un changement dans l'un d'entre eux est un signal avant qu'il ne devienne un incident. Les vérifications au niveau du contrat, comme dans notre guide de tests de contrat d'API, détectent le changement en amont qui en est généralement la cause.
Trois enquêtes auxquelles la trace doit survivre
« L'agent a facturé le mauvais client. » Vous avez besoin des arguments produits par le modèle, de l'URL résolue et de l'étape précédente. Neuf fois sur dix, l'ID provenait d'un résultat d'outil antérieur qui a renvoyé plus d'une correspondance et le modèle a choisi la première. La trace montre le résultat antérieur, l'ambiguïté et le choix. Sans tool_args, vous avez un 200 et un client très mécontent.
« Ça a cessé de fonctionner mardi. » Comparez une bonne exécution et une mauvaise exécution champ par champ. ID du modèle, hachage de l'ensemble d'outils, version du prompt, taille moyenne de la réponse. Quelque chose a changé, et l'un de ces quatre éléments le nomme généralement. C'est pourquoi l'enregistrement d'exécution contient la configuration et pas seulement les événements : un diff n'est possible que lorsque les deux côtés ont enregistré les mêmes champs.
« Quelqu'un a-t-il approuvé cela ? » Le bloc de politique est la réponse complète, et il doit être écrit au moment de la décision, et non reconstitué ultérieurement. approval_required, approved_by et un horodatage transforment une conversation tendue en une recherche.
Remarquez ce qu'ils ont en commun. Aucun d'entre eux n'est résolu par « l'outil a renvoyé 200 ». Les trois sont résolus par des champs qui ne coûtent presque rien à écrire et sont impossibles à récupérer après coup.
Échantillonnage, et ce qu'il ne faut jamais échantillonner
Le traçage complet sur chaque exécution devient coûteux en volume, les équipes échantillonnent donc. Échantillonnez avec soin, car le trafic des agents n'est pas uniforme.
Conservez toujours chaque exécution échouée, chaque exécution qui a rencontré un bloc de politique et chaque exécution contenant une écriture. Ce sont les exécutions dont tout le monde posera des questions. Échantillonnez les exécutions réussies en lecture seule, car elles représentent la majeure partie du volume et sont les moins intéressantes individuellement, bien que vous en vouliez suffisamment pour calculer vos lignes de base.
Le chapitre du livre SRE de Google sur la surveillance des systèmes distribués reste la déclaration la plus claire de la raison pour laquelle vous échantillonnez pour le signal plutôt que pour le volume, et le raisonnement s'applique directement.
Conservez l'enregistrement d'exécution même lorsque vous supprimez les charges utiles. Une trace squelette avec les noms des outils, les résultats et les durées est petite et prend toujours en charge les quatre métriques ci-dessus. Les parties coûteuses sont les corps et les prompts, et ce sont les parties que vous pouvez supprimer en premier.
Un avertissement concernant l'échantillonnage de queue : si vous décidez quoi conserver après la fin d'une exécution, assurez-vous que la décision est prise une fois le résultat connu. Une exécution qui semble correcte à l'étape trois et échoue à l'étape neuf doit être conservée intégralement, ce qui signifie la mettre en mémoire tampon plutôt que de la jeter au fur et à mesure.
Où la trace devrait résider
Tout ce qui précède suppose que vous possédez le stockage. C'est la bonne hypothèse lorsque l'agent est votre propre service appelant vos propres API. C'est une mauvaise adaptation lorsque les agents sont des environnements d'exécution de code sur des machines de développeurs, car la trace réside alors dans le terminal qui l'a exécutée.
Sharkly adopte l'autre approche : la trace d'exécution est attachée à la tâche assignée à l'agent. L'historique d'exécution, le journal d'exécution et le résultat se trouvent à côté de l'objectif, du statut et du fil de commentaires où un humain a examiné le travail. La différence pratique est la récupération. « Pourquoi l'agent a-t-il fait cela » devient une question à laquelle vous répondez en ouvrant la tâche, plutôt qu'en trouvant la machine, la session et le défilement.
Cela ne remplace pas le traçage décrit ici, ni l'environnement d'exécution ; Claude Code et Codex font toujours le travail. Ce que cela change, c'est l'endroit où l'enregistrement se retrouve lorsque l'agent n'est pas un service que vous avez déployé.
Surveillez quatre chiffres
Les traces ne sont utiles que si quelqu'un les regarde. Ces quatre-là méritent leur place sur un tableau de bord.
Appels par tâche terminée. La mesure d'efficacité la plus claire. Si elle augmente, l'agent explore davantage, généralement parce qu'une description s'est détériorée ou qu'un point de terminaison a commencé à échouer.
Taux de réessais par point de terminaison. Classe vos dépendances les moins fiables et montre quand l'une d'entre elles se dégrade. Notre article sur la récupération d'erreurs d'agent couvre ce qu'il faut faire concernant le haut de cette liste.
Taux de blocage par politique. Devrait être faible et stable. Un pic signifie soit que l'agent tente des choses qu'il ne devrait pas, soit qu'une politique est trop stricte et devient maintenant le goulot d'étranglement.
Temps jusqu'au premier appel d'outil. Un démarrage lent signifie généralement un prompt gonflé, et la taille du prompt est la chose qui augmente sans que personne ne décide de l'augmenter.
Une liste de contrôle
- Un ID de trace par exécution, un ID de span par appel d'outil, estampillé à toutes les trois couches.
- Arguments du modèle enregistrés avant normalisation.
- La liste des outils disponibles enregistrée à chaque appel.
- Résultat enregistré sous forme d'énumération explicite, y compris les blocs de politique.
- Nombre de réessais séparé du nombre d'appels.
- Modèle, température, version du prompt et hachage de l'ensemble d'outils sur l'enregistrement d'exécution.
- Résultats bruts des outils stockés, pas seulement la version tronquée transmise au modèle.
- Identifiants supprimés dans le middleware, corps hachés là où ils ne peuvent pas être stockés.
- Rétention échelonnée par sensibilité.
- Traces échouées convertibles en cas de test rejouables.
L'objectif est simple à énoncer : quand quelqu'un demande pourquoi l'agent a fait cela, vous pouvez répondre à partir de l'enregistrement au lieu d'une supposition. Téléchargez Apidog pour rejouer les appels dans une trace et conserver les reproductions comme tests.
Foire aux questions
Dois-je utiliser OpenTelemetry ou un outil d'observabilité d'agent dédié ? Utilisez OpenTelemetry pour le transport et le modèle de trace, car il gère déjà la corrélation et votre infrastructure le parle probablement. Les outils spécifiques aux agents ajoutent des vues utiles par-dessus ; les données sous-jacentes devraient toujours être portables.
Combien coûte le stockage d'un traçage complet ? Moins que ce que les gens s'attendent, si vous le classez par niveaux. Des charges utiles complètes pendant quelques jours et des enregistrements structurés sans corps pendant plus longtemps maintiennent la majeure partie du volume à un niveau bas. Les dumps de prompts sont la partie coûteuse, alors hachez-les et dimensionnez-les au lieu de les stocker par défaut.
Dois-je enregistrer le texte de raisonnement du modèle ? Pas habituellement. L'outil qu'il a choisi, les arguments qu'il a produits et les options qu'il avait expliquent la plupart des décisions. Lorsqu'un fournisseur expose le contenu de raisonnement, ne le stockez que pour les exécutions échouées et traitez-le comme sensible.
Comment tracer à travers plusieurs agents ? Conservez un seul ID de trace pour l'ensemble de la tâche et donnez à chaque agent son propre span, avec le transfert enregistré comme un événement. Notre article sur le transfert multi-agent couvre ce qui doit figurer dans cet enregistrement de transfert.
Que se passe-t-il si l'agent s'exécute sur la machine d'un client ? Enregistrez localement, masquez agressivement et n'envoyez que des métriques agrégées, sauf si l'utilisateur y consent. Les noms d'outils, les résultats et les durées sont généralement suffisants pour une surveillance au niveau de la flotte sans qu'aucune charge utile ne quitte l'appareil.
Un hachage du corps de la requête est-il vraiment utile ? Oui, pour les questions les plus courantes. Il prouve que deux appels étaient identiques, ce qui résout la plupart des enquêtes sur les écritures en double, sans conserver la charge utile elle-même. Associez-le aux clés d'idempotence qui auraient dû empêcher le doublon.