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.
Cet article décrit ce qu’il faut journaliser pour rendre un agent compréhensible : les événements, leur structure, les niveaux de détail, et les outils qui existent pour le faire sans réinventer la roue. L’objectif est simple : 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, 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.
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à.
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.
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.
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, et ce temps est largement rentabilisé au premier bug évité.
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, rejouer les mêmes cas après chaque changement de prompt ou de modèle, et comparer les résultats. C’est le principe des tests de non-régression appliqué aux agents, 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.
En résumé, la traçabilité n’est pas un luxe d’équipes matures, c’est la condition minimale pour traiter un agent comme un composant d’ingénierie : compréhensible, débogable, mesurable, améliorable. Un agent sans traces n’est pas un produit, c’est un pari.
L’accompagnement Agenticiel pour industrialiser vos agents
Mettre en place une traçabilité sérieuse est un travail d’intégration qui se fait mieux tôt, et avec une méthode éprouvée. Agenticiel aide les PME et les éditeurs à équiper leurs agents de traces structurées, à brancher l’outil adapté, et à transformer ces traces en évaluation continue.
Nous commençons par regarder comment votre agent est construit, puis nous intégrons la traçabilité sur l’ensemble des appels au modèle et aux outils, avec la structure et les métriques qui comptent. Nous raccordons ensuite ces traces à un jeu d’évaluation, pour que chaque changement soit mesurable. Le travail est mené par une équipe de développeurs offshore francophones, basée à Madagascar, qui échange avec vous dans votre langue et sur vos horaires. La sous-traitance de développement rend cette industrialisation accessible sans recruter une équipe dédiée en interne.
Notre approche consiste à rendre chaque exécution de l’agent lisible et rejouable, pour que les erreurs se corrigent à la racine au lieu de se deviner.