Logs et traces d'un agent : comprendre ce qu'il fait

Quand un agent IA se comporte mal, la plupart des équipes découvrent qu’elles n’ont aucun moyen de savoir pourquoi. L’agent a appelé des outils, enchaîné des étapes, produit une réponse, et rien n’a été conservé de ce cheminement. On relance, on espère, on ajuste le prompt à l’aveugle, et le problème revient ailleurs. C’est le signe d’un agent construit sans traces.

La différence entre un script déterministe et un agent tient à une chose : l’agent prend des décisions à l’exécution, qui dépendent de ce que les outils renvoient. Si l’on ne conserve pas l’historique de ces décisions, l’agent est une boîte noire. On sait ce qui est entré et ce qui est sorti, mais rien de ce qui s’est passé entre les deux, et c’est précisément là que se cachent les erreurs.

Voici ce qu’il faut journaliser, comment le structurer et avec quels outils, pour pouvoir répondre à la question « qu’a fait l’agent, dans quel ordre, et pourquoi » sans avoir à reproduire le problème.

Ce qu’il faut journaliser, et ce qu’on oublie toujours

Le premier réflexe est de journaliser les réponses finales, et c’est insuffisant. Une réponse finale ne dit rien du chemin. Ce qu’il faut conserver, c’est la séquence complète : chaque appel au modèle, le prompt exact envoyé, chaque appel d’outil (fonction ou serveur MCP), les arguments transmis, le résultat renvoyé, et la décision qui en découle. C’est cette séquence, et elle seule, qui rend l’agent rejouable et débogable.

Deux éléments sont presque toujours oubliés, et ce sont pourtant les plus utiles. Le premier, c’est la version exacte du prompt système et des instructions, au moment de l’exécution. Un prompt change en production, et si les traces anciennes n’en gardent pas la version, on ne peut plus savoir quelle configuration a produit tel comportement. Le second, c’est le coût : les tokens consommés par appel, le nombre d’itérations, la latence de chaque étape. Sans ces chiffres, on ne détecte pas un agent devenu plus cher ou plus lent au fil des changements, et on se prive de la base de toute observabilité LLM en production.

La règle pratique est donc : journaliser tout événement qui fait partie de la décision, avec sa version et son coût. Ce qui est purement technique, comme un heartbeat, n’a pas sa place dans la trace et doit rester dans les logs d’infrastructure.

La trace, la bonne unité de mesure

Une trace n’est pas un tas de lignes, c’est une structure. La bonne unité est la trace d’exécution : un enregistrement unique qui regroupe, dans l’ordre, toutes les étapes d’une seule exécution de l’agent. Chaque étape, chaque appel d’outil, chaque appel au modèle devient un span rattaché à cette trace, avec un horodatage, une durée et un statut.

Cette structure apporte trois choses. Elle permet de retrouver une exécution précise par son identifiant, à partir d’un identifiant de requête ou d’un numéro de ticket. Elle permet de comparer deux exécutions qui devaient se ressembler et de repérer où elles divergent. Elle permet enfin de calculer des agrégats : temps moyen par étape, taux d’échec d’un outil donné, nombre d’itérations avant réponse.

Le format à adopter est secondaire tant que la structure existe. Le standard OpenTelemetry, déjà répandu côté infrastructure, s’étend naturellement aux agents et évite de construire un format maison. Beaucoup d’équipes l’adoptent pour cette seule raison : les outils de visualisation existent déjà, de Grafana à Datadog, et les traces de l’agent y rejoignent celles du reste de l’application.

Les outils qui font le travail à votre place

Construire sa propre plateforme de traces est une erreur courante et coûteuse. Des outils spécialisés existent, et ils couvrent l’essentiel du besoin : Langfuse, LangSmith, ou encore les solutions de traçage compatibles OpenTelemetry. Ils capturent les appels au modèle, les appels d’outils, les tokens et les latences, et présentent l’ensemble sous forme de trace navigable. Les frameworks s’y branchent en quelques lignes : LangChain et LangGraph s’intègrent nativement à LangSmith et via un callback à Langfuse, et l’OpenAI Agents SDK embarque son propre traçage.

Langfuse a l’avantage d’être open source et auto-hébergeable, ce qui compte quand les données ne doivent pas sortir de l’entreprise. LangSmith est lié à l’écosystème LangChain mais fonctionne aussi avec d’autres frameworks, au prix d’une dépendance à un service fermé. Le choix se joue sur deux critères : la localisation des données et la profondeur d’intégration avec votre framework existant. Les traces contiennent les prompts et les réponses, donc souvent des données clients : si elles sont sensibles, l’hébergement de l’outil de traçage relève des mêmes exigences que le reste de votre IA souveraine.

Le point important n’est pas l’outil, c’est d’en brancher un avant le premier incident. Un agent sans trace est un agent qu’on ne peut ni déboguer ni améliorer sérieusement. L’intégration se fait en une journée sur la plupart des frameworks.

Déboguer avec les traces, pas avec l’intuition

Une trace bien construite change la façon de déboguer. Au lieu de reproduire un problème pour le comprendre, on ouvre la trace de l’exécution fautive et on lit la séquence. On voit que l’agent a choisi tel outil parce que tel résultat lui est parvenu, qu’il a mal interprété une réponse, qu’il a répété une étape inutilement. Le bug se lit, il ne se devine plus.

Prenons un exemple concret. Un agent chargé de réserver des créneaux échouait sur certains dossiers sans raison apparente. Les logs finaux montraient un échec, mais pas la cause. La trace a révélé que l’outil de réservation renvoyait ses erreurs sous forme de texte libre, que l’agent tentait alors de rejouer la requête en boucle jusqu’à atteindre sa limite d’itérations. Le correctif a consisté à normaliser les réponses d’erreur de l’outil. La trace n’a pas réparé le bug, elle l’a rendu visible.

Cette capacité à lire une exécution passée est aussi ce qui rend les agents améliorables. On collecte les traces des échecs, on repère les motifs récurrents, et on corrige à la racine : un prompt ambigu, un outil mal décrit, une limite d’itérations mal calibrée. Sans traces, ces motifs restent invisibles.

Les traces comme base de l’évaluation

Les traces ne servent pas qu’au débogage, elles nourrissent l’évaluation. Pour mesurer si un agent s’améliore, il faut des données de référence : des exécutions réelles, annotées, avec leur résultat attendu. Les traces fournissent exactement cela, à condition de les conserver de façon structurée et interrogeable.

À partir des traces, on peut constituer un jeu d’évaluation (Langfuse et LangSmith permettent de verser une trace dans un dataset en un clic), rejouer les mêmes cas après chaque changement de prompt ou de modèle, par exemple avec Promptfoo ou DeepEval, et comparer les résultats. C’est le principe des tests de non-régression appliqués à l’IA, et il ne fonctionne que si les traces existent au préalable. Commencer à tracer tard, c’est repartir de zéro sur la donnée d’évaluation.

La traçabilité est la condition minimale pour traiter un agent comme un composant d’ingénierie : compréhensible, débogable, mesurable, améliorable.

En pratique : industrialiser vos agents

Mettre en place une traçabilité sérieuse est un travail d’intégration qui se fait mieux tôt. Pour savoir où vous en êtes, prenez la dernière réponse incorrecte signalée par un utilisateur et essayez de retrouver, en moins de dix minutes, le prompt exact envoyé, les outils appelés et leurs résultats. Si c’est impossible, l’agent tourne encore à l’aveugle.

Chez Agenticiel, les traces font partie du socle de chaque agent qu’on livre, au même titre que les evals et les garde-fous : branchées sur tous les appels au modèle et aux outils, versionnées avec les prompts, et raccordées au jeu d’évaluation pour que chaque changement soit mesurable. La façon dont ces briques s’articulent est décrite dans notre méthode de mise en production, et on peut l’appliquer à un agent déjà en service.