Observabilité des agents

Pourquoi observer un agent change tout

Un agentagentIASystème qui enchaîne des appels d'outils de façon autonome pour atteindre un objectif : il planifie, agit, observe, recommence. Sa fiabilité décroît exponentiellement avec le nombre d'étapes.Voir dans le glossaire LLMLLMIAGrand modèle de langage (Large Language Model) entraîné sur d'énormes corpus pour prédire et générer du texte.Voir dans le glossaire qui enchaîne plusieurs appels de modèle et plusieurs outilstool callingIACapacité d'un agent ou d'un LLM à invoquer des outils externes (API, calcul, recherche) pendant le raisonnement.Voir dans le glossaire est un système distribué comme un autre : il échoue partiellement, il consomme du budget à chaque étape, et son comportement dépend d'entrées non déterministes. Sans instrumentation, un agent en production est une boîte noire dont on découvre les dérives après coup — facture surprise en fin de mois, utilisateur qui signale une réponse incohérente trois semaines après l'incident, ou pire, un outil qui échoue silencieusement sans que personne ne s'en aperçoive avant l'audit trimestriel.

Observer un agent, ce n'est pas ajouter des traces de débogage disséminées dans le code au moment où quelque chose casse. C'est construire une chaîne complète, présente dès le premier déploiement : trace de bout en bout pour chaque requête, coût calculé à chaque appel, taxonomie des échecs d'outils, et seuils d'alerte qui déclenchent une action avant que l'utilisateur ne s'en plaigne. C'est un sujet d'ingénierie, pas de reporting a posteriori.

Un appel de fonction classique échoue de façon binaire : exception ou succès. Un agent peut « réussir » techniquement — code 200, réponse bien formée, aucune exception levée — tout en produisant un résultat inutile ou faux. L'observabilité d'un agent doit donc couvrir la qualité du résultat produit, pas seulement la disponibilité du service qui l'a généré.

Anatomie d'une trace

Une trace représente le parcours complet d'une requête, depuis la sollicitation initiale de l'utilisateur jusqu'à la réponse finale renvoyée. Elle se décompose en spans : des segments de temps nommés, imbriqués les uns dans les autres, chacun portant un identifiant propre (span_id) et la référence de son parent (parent_span_id), le tout rattaché à un trace_id commun à toute la requête.

Pour un agent typique, une trace contient au minimum :

• un span racine représentant la requête utilisateur de bout en bout ;
• un span par appel au modèle, avec le promptpromptIAConsigne ou contexte fourni à un modèle de langage pour orienter sa réponse. La qualité du prompt conditionne souvent la qualité du résultat.Voir dans le glossaire envoyé, le nombre de tokenstokenIAFragment de texte manipulé par un modèle de langage, généralement plus court qu'un mot — trois à quatre caractères en français. La tarification et la limite de contexte se comptent en tokens.Voir dans le glossaire consommés en entrée et en sortie, la latence et le modèle effectivement utilisé ;
• un span par appel d'outil, avec le nom de l'outil, les arguments transmis, le résultat renvoyé et le code d'erreur éventuel ;
• le cas échéant, un span pour chaque étape de raisonnement intermédiaire exposée par l'agent (planification, relecture, validation d'un résultat avant de le renvoyer).

Un agent de support reçoit « où en est ma commande #4821 ? ». La trace montre : un premier appel modèle qui décide d'appeler l'outil get_order_status, un appel outil de 0,9 seconde qui renvoie un statut, un second appel modèle qui reformule la réponse en langage naturel. Coût total : 0,018 $. Latence totale : 2,1 secondes. Sans cette trace, seul le résultat final est visible — impossible de savoir si les 2,1 secondes viennent du modèle ou de l'outil.

Le format qui s'est imposé : OpenTelemetry

OpenTelemetry (OTel) fournit un modèle de donnéesdonnéesIAEnsemble d'informations structurées ou non utilisées pour entraîner, évaluer ou alimenter un modèle. La qualité, la quantité et la représentativité des données sont les facteurs décisifs pour les performances en apprentissage automatique.Voir dans le glossaire standard pour les traces, indépendant du langage et du fournisseur de modèle. Un groupe de travail a défini des conventions sémantiques spécifiques aux systèmes d'IAintelligence artificielleIAEnsemble des techniques permettant à un programme d'accomplir une tâche qui demanderait de l'intelligence humaine. Le terme couvre aussi bien les systèmes à règles écrites que ceux qui apprennent de données.Voir dans le glossaire générative, préfixées gen_ai.* : gen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, gen_ai.response.finish_reason. Ces attributs, posés sur chaque span d'appel modèle, permettent à n'importe quel outil compatible OTel de calculer coûts et latences sans connaître l'implémentation interne de l'agent.

L'intérêt pratique : un exporteur OTel peut envoyer les mêmes traces vers plusieurs destinations en parallèle (un outil spécialisé en observabilité LLMgrand modèle de langageIAModèle entraîné à prédire le token suivant d'une séquence de texte. Toutes ses capacités apparentes — résumer, traduire, coder — découlent de cette unique tâche.Voir dans le glossaire pour l'analyse fine, un système de logs générique pour l'archivage long terme) sans dupliquer le code d'instrumentation.

Un format de log maison, propre à un projet, coûte cher à long terme : chaque nouvel outil d'analyse nécessite un connecteur sur mesure. S'appuyer sur OpenTelemetry, même a minima avec quelques attributs gen_ai.* posés sur les spans existants, évite ce piège et ouvre l'accès à tout l'écosystème d'exporteurs déjà écrits.

Suivre les coûts à la source

Le coût d'une requête agent se calcule à partir de deux nombres par appel modèle : les tokens d'entrée (prompt complet, historique inclus) et les tokens de sortie (réponse générée), chacun facturé à un tarif différent selon le modèle.

(ordres de grandeur illustratifs — les tarifs réels varient par fournisseur et évoluent régulièrement ; ne jamais coder un tarif en dur, toujours le lire depuis une configuration à jour.)

Ce tarif par token ne dit rien du coût réel d'une conversation agent, car le nombre de tokens consommés dépend du nombre d'itérations de la boucle et de la taille de l'historique réinjecté à chaque tour.

Chaque itération de la boucle agent (appel outil → nouvel appel modèle avec tout l'historique) réinjecte l'intégralité du contextefenêtre de contexteIAQuantité de texte qu'un modèle peut prendre en compte simultanément : question, documents fournis et historique. Au-delà, les éléments les plus anciens sortent du champ.Voir dans le glossaire précédent dans le prompt suivant. Un agent qui boucle dix fois sur un outil qui échoue peut multiplier son coût par un facteur bien supérieur à dix, car chaque relance porte un historique grandissant, pas un historique constant.

En pratique, il faut calculer et stocker, pour chaque span d'appel modèle, le coût exact (tokens × tarif du modèle utilisé à cet instant), puis l'agréger au niveau de la trace (coût par requête) et au niveau de la session ou de l'utilisateur (coût cumulé). Un plafond configurable par session — par exemple interrompre l'agent au-delà d'un certain montant — évite qu'une boucle pathologique ne consomme un budget disproportionné avant d'être détectée.

Cataloguer les échecs d'outils

Tous les échecs d'outils ne se ressemblent pas et n'appellent pas la même réponse. Une taxonomie claire, appliquée systématiquement dans le code d'appel d'outil, permet de distinguer ce qui relève d'un problème transitoire de ce qui relève d'un bug structurel.

Un outil qui renvoie un code de succès avec un résultat incorrect, incomplet ou périmé ne déclenche aucune alerte technique classique. L'agent poursuit son raisonnement sur une base fausse, et l'utilisateur reçoit une réponse d'apparence normale. La seule défense fiable consiste à valider la plausibilité du résultat (bornes de valeur, cohérence de format, fraîcheur d'une donnée) au moment de l'appel, pas seulement le code de retour HTTP.

Chaque appel d'outil doit produire, en plus de son résultat métier, un statut normalisé consigné dans le span correspondant : succès, échec technique catégorisé selon le tableau ci-dessus, ou résultat suspect nécessitant une revue. Sans cette normalisation, il devient impossible d'agréger un taux d'erreur par outil de façon fiable — chaque intégration finit par logger les erreurs à sa manière.

Construire un tableau de bord minimal

Un tableau de bord d'observabilité pour un agent n'a pas besoin d'être exhaustif pour être utile ; il doit couvrir quatre familles de métriques :

• Latence, par type de span (appel modèle, appel outil), exprimée en p50, p95 et p99 — pas seulement en moyenne ;
• Coût, par requête et agrégé par jour, avec une ventilation par modèle utilisé ;
• Taux d'erreur par outil, avec la répartition par type d'échec du tableau précédent ;
• Taux de complétion des tâches, une métrique plus difficile à automatiser puisqu'elle suppose de juger si la réponse finale répond réellement à la demande — souvent approchée par un échantillon évalué manuellement ou par un modèle juge.

Un graphique consulté une fois par mois ne constitue pas de l'observabilité, seulement un historique. Chaque métrique affichée doit avoir un seuil associé et un propriétaire qui reçoit l'alerte quand ce seuil est franchi. Si personne n'est censé agir sur une métrique donnée, elle encombre le dashboard plus qu'elle ne l'éclaire.

Pourquoi préférer les percentiles à la moyenne pour la latence : une moyenne basse peut coexister avec une expérience très dégradée pour une minorité d'utilisateurs, si quelques requêtes très lentes sont compensées statistiquement par une majorité de requêtes rapides. Le p95 (95 % des requêtes sont plus rapides que cette valeur) révèle cette traîne que la moyenne masque.

Seuils d'alerte et garde-fous automatiques

Au-delà du tableau de bord consulté manuellement, certains garde-fous doivent agir sans intervention humaine :

• Détection de boucle : si un agent appelle le même outil avec des arguments identiques ou quasi identiques plus de deux ou trois fois consécutives au sein d'une même trace, interrompre l'exécution et remonter l'incident plutôt que de laisser la boucle continuer jusqu'à épuisement d'un budget de tokens.
• Circuit breaker par outil : si le taux d'échec d'un outil dépasse un seuil sur une fenêtre glissante (par exemple 30 % d'échecs sur les cinq dernières minutes), suspendre temporairement les appels vers cet outil et renvoyer un message d'indisponibilité à l'agent plutôt que de multiplier les tentatives coûteuses.
• Plafond de coût par session : interrompre une conversation qui dépasse un montant défini, avec un message clair à l'utilisateur plutôt qu'un arrêt silencieux.
• Alerte sur latence p95 : si la latence p95 d'un type de span dépasse un seuil sur une fenêtre donnée, notifier avant que les utilisateurs ne commencent à se plaindre en nombre.

Ces seuils se définissent par outil et par métrique, pas de façon globale : un taux d'erreur de 20 % sur un outil secondaire, peu utilisé, pèse beaucoup moins qu'un taux d'erreur de 5 % sur l'outil central de l'agent, appelé à chaque conversation.

Écosystème d'outils

Plusieurs catégories d'outils couvrent tout ou partie de ce périmètre :

• des plateformes spécialisées en observabilité LLM, en mode SaaS, qui offrent une visualisation des traces prête à l'emploi et un calcul automatique des coûts à partir des attributs gen_ai.* ;
• des solutions open source auto-hébergeables équivalentes, pertinentes quand la contrainte d'hébergement des données interdit l'envoi vers un tiers ;
• une instrumentation OpenTelemetry brute, exportée vers une pile d'observabilité générique déjà en place dans l'organisation (dashboards et systèmes de traces distribuées classiques), pertinente quand cette infrastructure existe déjà et qu'on préfère ne pas ajouter un outil spécialisé de plus.

Le choix dépend surtout de deux critères : la contrainte de confidentialité des données envoyées (prompts et réponses complets), et l'écosystème d'observabilité déjà en place dans l'équipe.

Beaucoup de plateformes d'observabilité tierces stockent les prompts et réponses complets, qui peuvent contenir des données personnelles transmises par les utilisateurs — nom, email, numéro de commande, contenu d'un document. Un pipeline de redaction, par filtrage sur motif ou par un modèle dédié, doit impérativement s'exécuter avant l'export vers un service tiers, jamais après coup sur des données déjà stockées ailleurs.

Checklist avant mise en production

• Un trace_id est généré à l'entrée de chaque requête et propagé à tous les spans internes, y compris les appels d'outils exécutés par des services séparés.
• Le coût est calculé à chaque appel modèle (tokens réels × tarif du modèle effectivement utilisé) et agrégé par requête et par session.
• Chaque appel d'outil produit un statut normalisé selon une taxonomie d'échecs partagée par toute l'équipe.
• Une détection de boucle interrompt automatiquement un agent qui répète le même appel d'outil au-delà d'un seuil défini.
• Un tableau de bord affiche au minimum la latence en p50/p95/p99 et le taux d'erreur par outil.
• Une étape de redaction retire les données personnelles avant tout export vers un outil d'observabilité tiers.
• Un plafond de coût par session est configurable et déclenche une interruption propre, pas un arrêt silencieux.

En résumé

L'observabilité d'un agent LLM ne se limite pas à journaliser des erreurs techniques : elle doit relier trace, coût et statut d'outil sur un même identifiant de requête pour permettre un diagnostic complet. Les échecs les plus coûteux ne sont pas les timeouts, faciles à détecter, mais les boucles qui gonflent silencieusement la facture et les résultats d'outils faux qui ne déclenchent aucune alerte technique. Une instrumentation posée dès le premier déploiement, appuyée sur un format standard comme OpenTelemetry, coûte largement moins cher qu'un diagnostic reconstruit a posteriori à partir de logs épars.