Observabilité des agents d'IA : guide pratique des traces, métriques et revues

L'observabilité des agents d'IA permet de reconstruire ce qu'un agent a tenté, les outils et données qu'il a utilisés, le résultat de chaque étape, le coût de l'exécution et l'acceptabilité du résultat final. Un tableau de bord limité à la latence et aux erreurs ne suffit pas. Le comportement des agents varie : les équipes ont aussi besoin de traces, d'évaluations, de résultats métier et d'un processus de revue des contenus sensibles.

Recherche et transparence: Ce guide s'appuie sur les travaux d'OpenTelemetry consacrés à l'observabilité des agents, les conventions sémantiques OpenTelemetry et le cadre de gestion des risques liés à l'IA du NIST, consultés le 4 septembre 2026. Le modèle opérationnel ci-dessous est un cadre éditorial original, pas un test de performance d'Ottermind.

Les questions auxquelles l'observabilité doit répondre

Un système utile doit répondre à six questions sans obliger un ingénieur à reconstruire l'exécution à partir de journaux dispersés :

1. Quel objectif, quelles instructions, quel modèle et quelles entrées ont lancé l'exécution ?
2. Quels appels de modèle, recherches, outils et approbations ont eu lieu ?
3. Qu'a reçu et renvoyé chaque étape ?
4. Où l'exécution a-t-elle réessayé, bloqué, bifurqué ou échoué ?
5. Le résultat a-t-il atteint un seuil de qualité spécifique à la tâche?
6. Un relecteur peut-il reproduire les preuves sans exposer de données restreintes ?

Le suivi traditionnel des applications est toujours important. La disponibilité, la latence et les taux d'erreur vous indiquent si le service fonctionne. L'observabilité de l'agent ajoute le contexte du niveau de tâche nécessaire pour savoir si le service a fait le bon travail.

Le modèle d'observabilité à quatre couches

Ne réduisez pas ces couches à un seul score. Une exécution rapide peut produire un mauvais rapport. Un rapport bien étayé peut arriver trop tard. Un livrable accepté peut encore exposer des données qui n'auraient jamais dû entrer dans une trace.

Un schéma d'événement minimal

Commencez par un petit contrat d' événement que chaque agent et outil peut émettre:

{
  "run_id": "run_123",
  "step_id": "step_07",
  "parent_step_id": "step_03",
  "operation": "tool.call",
  "tool": "document_search",
  "started_at": "2026-09-04T09:00:00Z",
  "duration_ms": 842,
  "status": "ok",
  "input_classification": "confidential",
  "content_recorded": false,
  "tokens": 0,
  "cost_usd": 0,
  "evaluation_refs": ["eval_19"]
}

L'exécution stable et les identifiants parents rendent la séquence reconstructible. Enregistrer des versions pour les instructions, les modèles, les outils et les politiques afin qu'une régression puisse être liée à un changement. Gardez les instructions et les sorties crues facultatives: les métadonnées suffisent souvent pour l'analyse opérationnelle, tandis que la capture de contenu crée des obligations de confidentialité et de conservation.

Garder les quatre identifiants distincts

• workflow_idnommer le produit durable ou le processus d'affaires.
• workflow_versionidentifie la configuration testée des instructions, des outils, des modèles et des règles.
• run_idconnecte chaque étape en une seule exécution.
• thread_idLes liens liés se déroulent à travers une conversation ou une tâche plus longue.

Ne réutilisez pas un identifiant d'utilisateur en tant que fil ou en tant qu'identifiant d'exécution. Gardez l'identité dans un champ contrôlé séparément et utilisez des références pseudonymes lorsque l'analyse ne nécessite pas d'identification directe. Ne joindre l'artefact ou l'identifiant d'enregistrement d'affaires que lorsque la politique le permet.

Ajoutez des versions de déploiement, d'environnement, d'expérience et de jeu de sources. Ces dimensions répondent à la question de savoir si un échec a commencé après une mise en production, affecte une cohorte ou dépend d'une collection de connaissances obsolète.

Mesures qui révèlent le comportement de l'agent

Suivez un ensemble compact avant d' ajouter des dizaines de graphiques:

• taux d'achèvement et d'abandon par type de tâche;
• la latence médiane et la latence de la queue pour l'exécution et chaque outil;
• taux d'échec de l'outil, de nouvelle tentative et de repli;
• les étapes, les tokens et le coût par résultat accepté;
• l'authenticité ou la couverture des citations lorsque les éléments de preuve sont importants;
• le temps de correction humaine et les raisons de rejet;
• blocage des politiques, demandes d'approbation et refus d'autorisation.

Segmenter les métriques par version du flux de travail et par tâche représentative. Les moyennes agrégées peuvent cacher qu'un type de document ou une intégration d'outil échouent à plusieurs reprises.

Suivre une exécution de but à but

Prenons l'exemple d'un agent de recherche qui a été invité à préparer un rapport de compétition à partir de dix sources approuvées. Le document final contient le mauvais prix pour un concurrent. Une trace utile devrait permettre à l'relecteur de revenir en arrière tout au long de l’exécution:

1. L'enregistrement des résultats montre que le rapport a été rejeté et étiquette l'erreur de tarification.
2. L'espace de synthèse final identifie la ligne de prix extraite qui a fourni la phrase.
3. La durée de récupération indique qu'un article d'aide archivé se classe au-dessus de la page de prix actuelle.
4. Les métadonnées de source ne montrent pas de champ de date effective et aucune règle ne préférant les pages officielles actuelles.
5. La version du flux de travail montre qu'une récente modification de récupération a supprimé un filtre de date.

La correction ne consiste pas simplement à « utiliser un meilleur modèle ». Rétablissez la règle de priorité des sources, ajoutez l'exécution rejetée à un jeu d'évaluation, testez d'autres affirmations sensibles au temps et surveillez la récupération des pages archivées. L'observabilité crée de la valeur lorsqu'elle relie un défaut visible à une modification vérifiable.

Sans trace liée, l'équipe peut modifier le prix unique, nouvelle tentative la tâche ou modifier le prompt sans savoir si l'échec de récupération sous-jacent reste.

Le design s'étend autour des décisions

Une trace devient illisible si chaque fonction auxiliaire possède son propre span, et incomplète si toute l'exécution tient dans un seul span. Instrumentez des unités de travail significatives :

• l'importation des objectifs et la classification des politiques;
• la création d'un plan ou la sélection d'un itinéraire;
• chaque invocation modèle;
• chaque requête de récupération et chaque ensemble de sources retournées;
• chaque appel et chaque résultat d'un outil externe;
• l'état ou la mémoire lisent et écrivent;
• nouvelle tentative, revenir en arrière et arrêter les décisions;
• les demandes d'approbation humaine et les réponses;
• la création et la validation des artefacts;
• la livraison finale et le résultat de l'utilisateur.

Utilisez les relations parent-enfant pour le travail niché et les liens pour les tâches asynchrones qui partagent une cause mais pas une pile d'appels directs. Donnez à chaque span un nom d'opération stable. Mettez des valeurs variables telles que le nom de l'outil, la version du flux de travail et la classe de document dans les attributs afin qu'ils puissent être filtrés sans créer des milliers de noms métriques.

Enregistrer suffisamment de contexte, pas de raisonnement caché

L'objectif est de capturer les entrées, les sorties, les décisions et les transitions d'état observables. Ne vous fiez pas à la chaîne de pensée privée ou à un raisonnement intérieur verbeux. Un champ de route tel que selected_tool=document_search, plus les alternatives autorisées et le résultat de l'outil, est plus utile et réglable qu'une transcription de raisonnement illimité.

Pour une décision ratée, consignez la politique ou l'évaluateur qui aurait dû la régir, les éléments de preuve disponibles à ce moment-là et l'action qui en résulte. Cela prend en charge le débogage sans transformer chaque trace en un récit sensible.

Construire des évaluations à partir de modes d'échec réels

Les mesures génériques telles que la fluidité et l'utilité sont rarement suffisantes. Définir les dimensions d'évaluation du contrat de flux de travail.

Pour le résumé de la recherche, les dimensions utiles peuvent inclure:

Utilisez trois étapes d'évaluation:

1. **Régression préalable à la mise en production:**les cas fixes sont exécutés avant que la version du flux de travail ne soit expédiée.
2. **Prélèvement d'échantillons de production:**un pourcentage défini de exécutions réelles reçoit un examen automatisé ou humain.
3. **Promotion des défaillances:**Les courbes rejetées, corrigées ou inhabituelles deviennent des cas de régression étiquetés.

Gardez les instructions d'évaluation, les modèles de classement, les rubriques et les ensembles de données en version. Lorsque le juge change, ne comparez pas ses scores à une ancienne ligne de base comme si la mesure était restée constante.

Définir les objectifs de service du flux de travail

Le temps de fonctionnement de l'application ne décrit pas si un agent termine un travail utile. Ajouter des indicateurs de service au niveau des tâches:

• pourcentage de exécutions admissibles qui produisent un artefact;
• pourcentage accepté sans correction substantielle;
• le temps allant de la demande au résultat prêt à l'examen;
• pourcentage augmenté à la propriétaire correcte;
• le coût maximum d'un résultat accepté;
• la citation ou la couverture des preuves pour les travaux soutenus par la source;
• taux d'achèvement conforme aux politiques.

Définissez les objectifs par catégorie de flux de travail. Un mémo de recherche en cinq minutes et une réponse du support en dix secondes ne doivent pas partager la même cible de latence. N'excluez les entrées invalides qu'en vertu d'une règle documentée, sans quoi une équipe pourrait embellir la fiabilité en reclassant les échecs difficiles.

Alerte sur les symptômes auxquels les gens peuvent agir

Évitez d'appeler quelqu'un pour chaque faible score d'évaluation. Les alertes doivent identifier une réponse opérationnelle limitée.

Utilisez des tableaux de bord pour connaître les tendances, des billets pour les défauts et des pages pour les incidents urgents. Si chaque fluctuation d'évaluation réveille un opérateur, la fatigue d'alerte cachera l'événement qui nécessite réellement une intervention.

Choisir une stratégie d'échantillonnage

La capture complète de métadonnées peut être suffisamment peu coûteuse pour chaque opération, tandis que la conservation complète du contenu et l'évaluation basée sur des modèles ne le sont pas. Combiner les règles d'échantillonnage:

• prélèvement aléatoireévalue la qualité normale sans sélectionner uniquement les défaillances dramatiques;
• prélèvement d'échantillons de risqueexamine davantage les flux de travail qui en découlent;
• prélèvement d'échantillons d'événementsconserve des erreurs, des blocages de politique, des boucles coûteuses et des rejetes par les utilisateurs;
• échantillonnage de changementaugmente la couverture après la mise en œuvre d'un modèle, d'un prompt, d'une récupération ou d'un outil;
• prélèvement d'échantillons de segments'assure que les langues rares, les types de documents, les rôles des utilisateurs et les cas de bord apparaissent;
• prélèvement d'échantillons cohérentconserve l’exécution complète en plusieurs étapes plutôt que des départs déconnectés.

Documentez le dénominateur. Si un tableau de bord affiche un taux de réussite de 95% sur les seules exécutions accomplies avec succès, les travaux abandonnés et bloqués ont disparu de la mesure.

Examinez l'échantillon pour les taches aveugles. Une règle qui ne maintient que des exécutions lentes ou ratées ne peut pas estimer la qualité quotidienne, tandis que le prélèvement aléatoire pur peut manquer d'incidents rares à fort impact. Préserver les incidents confirmés indépendamment de l'échantillonnage de routine dans le cadre de la politique de dossiers pertinente.

Concilier la télémétrie avec les commentaires des utilisateurs

Connectez explicitement le rejet, la correction, la nouvelle tentative, l'escalade, le ticket de support et les signaux d'artefact acceptés à l’exécution. Ne tirez pas de la satisfaction d'un utilisateur qui termine la conversation; il est possible qu'il l'ait abandonnée.

Créez des raisons structurées de rétroaction telles que une source erronée, une exigence manquante, des informations obsolètes, une action dangereuse, un format médiocre, trop lent ou trop coûteux. Gardez le texte libre en option pour le contexte, mais évitez de faire en sorte que chaque analyse dépend de la lecture manuelle.

Lorsque les commentaires sont en contradiction avec un évaluateur automatisé, inspectez le cas. L'utilisateur peut se tromper, l'évaluateur peut être mal précisé ou le flux de travail peut optimiser une rubrique technique qui ne correspond pas au résultat réel. Ces désaccords constituent des cas d'évaluation précieux.

Faites une revue de l' incident de l' agent

L'examen des incidents doit être irréprochable et traçable:

L'impact sur l'utilisateur et les exécutions affectés:
Temps de détection et signal:
Flux de travail, prompt, modèle, outil et versions des politiques:
Le comportement attendu:
Séquence observée:
Source, état ou autorisation:
Pourquoi les évaluations existantes ne l'ont pas reconnu:
Réservation immédiate:
Modification corrective et propriétaire:
Les cas de régression ont été ajoutés:
Surveillance des changements:
Date de suivi:

Séparer l'erreur déclenchante des contributeurs systémiques. Un modèle peut émettre un argument invalide, mais le contrat d'outil peut également l'accepter, la boucle de nouvelle tentative peut le répéter et l'évaluation peut ignorer les résultats de l'outil. La réparation de la première défaillance visible laisse le système fragile.

Déployer l'observabilité en quatre étapes

Étape 1 : Reconstruire une seule exécution

Instrumentez de bout en bout un flux de travail limité. Vérifiez qu'un ingénieur et un relecteur métier peuvent expliquer indépendamment une exécution échouée à partir de la trace.

Étape 2: Connectez la qualité

Ajouter des validations déterministiques, des étiquettes d'examen et des résultats acceptés ou rejetés. Construisez un petit ensemble de régressions à partir des défaillances observées.

Étape 3: Opérer au volume de production

Définir le prélèvement d'échantillons, la conservation, la rédaction, les tableaux de bord et les alertes actionnables. Mesurer le coût de la télémétrie et vérifier que le suivi n'expose pas de données restreintes.

Étape 4: Améliorer systématiquement

Utilisez des clusters d'échecs pour prioriser les changements, comparer les versions sur des ensembles de données fixes et confirmer l'effet dans la production. Réviser les mesures obsolètes et supprimer la télémétrie qui ne conduit plus à une décision.

Template d'examen hebdomadaire

Flux de travail et version:
Résultat attendu par l'utilisateur:
Résultats représentatifs:
Résultats négatifs ou corrigés:
Les modes de défaillance les plus élevés:
Modifications depuis l'examen précédent:
La latence et le décalage des coûts:
Changement d'évaluation:
Incidents de confidentialité ou d'autorisation:
Une expérience pour la semaine prochaine:
Propriétaire et date d'examen:

Des défaillances d'échantillons, pas seulement des moyennes. Examinez au moins une exécution propre, une exécution coûteuse, un résultat rejeté et une exécution nécessitant une intervention humaine. Cet ensemble expose un comportement que le panneau de statut vert manque.

Les limites de la vie privée et de la sécurité

Les données d'observabilité peuvent contenir des instructions, des noms de fichiers, des passages récupérés, des arguments d'outil, des informations d'identification, des données personnelles et des décisions commerciales. Classifiez-le comme des données de production. Expurgez les secrets avant l'exportation, séparer le contenu des métadonnées, restreindre l'accès, définir la conservation et enregistrer qui a inspecté des traces sensibles.

Créez au moins trois modes de capture. Un mode limité aux métadonnées enregistre la chronologie, l'état, les versions, les classifications et les hachages. Un mode expurgé conserve un contenu limité après filtrage automatique. Un mode de diagnostic restreint capture brièvement un contenu approuvé avec un accès nominatif. Le flux de travail, et non un développeur isolé, doit sélectionner le mode selon la classification des données.

Testez l’expurgation avant que la télémétrie ne quitte le processus. Un arrière-plan ne peut pas protéger un secret qui a déjà été transmis. Vérifiez également les données dérivées: les titres des documents, les arguments des outils, les embeddings, les messages d'erreur et les explications des évaluateurs peuvent révéler des contenus sensibles même lorsque le prompt principal est supprimé.

Une liste de contrôle de l'échéance

[ ] Chaque série de production dispose d'un flux de travail et d'un identifiant de version stables.
[ ] Les étapes de modèle, de récupération, d'outil, d'état, d'approbation et d'artefact sont reliées.
[ ] La capture de contenu sensible suit une règle de classification documentée.
[ ] Les résultats acceptés, corrigés, rejetés et abandonnés se joignent à des traces.
[ ] Les évaluations reflètent le contrat de tâche et sont révisées.
[ ] Les essais de production ratés peuvent être promus dans des ensembles de données de régression.
[ ] Les alertes ont un propriétaire et une première réponse définie.
[ ] La conservation, l'accès, l'exportation et la suppression ont été testés.
[ ] Le coût comprend le stockage et l'évaluation de la télémétrie, pas seulement les tokens de modèle.
[ ] Un relecteur de domaine peut reconstruire un résultat sans l'aide de l'ingénierie.

Pour un modèle de menace plus large, consultez la liste de contrôle de sécurité des agents d'IA. Pour les limites des composants et les contrats d'orchestration, voir le guide d'architecture des agents d'IA.

FAQ

Quelle est la différence entre la surveillance et l'observabilité d'agents d'IA ?

La surveillance rapporte des signaux connus tels que les défaillances, la latence et les coûts. L'observabilité fournit suffisamment de preuves connexes pour enquêter sur le comportement que vous n'avez pas prédit, y compris les choix d'outils, les nouvelles tentatives, le contexte, les évaluations et les corrections humaines.

Faut-il stocker chaque prompt et chaque réponse ?

Non. Conservez le minimum de données nécessaire aux besoins opérationnels et d'audit. Privilégiez les métadonnées et les hachages, expurgez les secrets, limitez la capture de contenu selon la classification des tâches et fixez une durée de conservation.

Avec quelle métrique une nouvelle équipe devrait-elle commencer ?

Commencez par le taux d'achèvement et le temps de correction acceptés pour un flux de travail limité. Ajoutez des mesures de coût, de latence et de mode d'échec autour de ce résultat.

L'observabilité remplace-t-elle l'évaluation hors ligne ?

Non. L'évaluation hors ligne teste des cas connus avant la mise en production. L'observabilité montre ensuite le comportement des entrées, outils et utilisateurs réels. Les équipes fiables utilisent les deux.

Combien de trafic de production devrait-on échantillonner ?

Il n'y a pas de pourcentage universel. Capturez les métadonnées à faible risque de manière générale, puis choisissez le contenu et l'échantillonnage d'évaluation en fonction du volume, du risque, du coût et de la fréquence des défaillances. Conserver toujours les incidents confirmés dans le cadre de la politique approuvée.

Combien de temps les traces doivent-elles être conservées ?

Ne les conserver que tant que le débogage, l'évaluation, l'audit ou le but contractuel le nécessitent. Utiliser des périodes plus courtes pour le contenu brut, des périodes plus longues pour les mesures agrégées et des réserves documentées pour les incidents confirmés.

Qui devrait examiner les traces de l'agent ?

Les ingénieurs examinent les pannes d'exécution et d'intégration; les propriétaires de domaines examinent la qualité des tâches; les équipes de sécurité et de confidentialité examinent les incidents pertinents. L'accès fondé sur le rôle devrait empêcher la navigation large de contenus sensibles.

L'observabilité peut-elle améliorer les prompts par elle-même ?

Elle fournit des preuves, pas une correction automatique. Utilisez les groupes d'échecs pour proposer une modification, la tester sur des cas versionnés et vérifier que les améliorations ne créent pas de régressions ailleurs.

Quel est le premier tableau de bord à construire ?

Pour un flux de travail, affichez les exécutions admissibles, le taux d'achèvement accepté, les motifs de rejet, le temps de correction, la latence, le coût, les escalades et la version actuelle. Reliez chaque agrégat à des exécutions consultables.

Les commentaires des utilisateurs sont-ils suffisants pour mesurer la qualité?

Non. Les retours sont précieux, mais incomplets et autosélectionnés. Combinez-les avec les validations de tâche, un échantillonnage représentatif, une revue métier et les résultats observés.

Les exécutions ratées doivent-elles toujours être conservées ?

Conservez les preuves nécessaires à l'enquête et au respect des règles, tout en appliquant la minimisation, les contrôles d'accès et les durées de conservation. Une défaillance ne justifie pas automatiquement le stockage indéfini de contenus sensibles.

Utilisez Ottermind pour exécuter un flux de travail limité et fondé sur des sources, examiner le livrable obtenu et consigner les corrections qui formeront votre premier jeu d'évaluation.