L'IA qui détecte ses propres erreurs : le détecteur de bugs des agents intelligents

INSTALLER L'OUTIL QUI RÉPARE LES AGENTS IA

Pour commencer à utiliser les détecteurs de défaillances des agents IA, il faut d'abord installer le Strands Evals SDK. Ce kit de Développement permet d'analyser les traces d'exécution de vos agents pour identifier leurs erreurs. L'installation se fait en une seule commande :

pip install strands-agents-evals

Une fois installé, ce SDK offre plusieurs fonctions pour examiner les logs générés par vos agents. Par exemple, la commande logs:GetQueryResults permet de récupérer les résultats des requêtes dans les journaux d'exécution.

DÉTECTER LES ÉCHECS DE VOTRE AGENT EN PRODUCTION

Imaginons que votre agent IA rencontre un problème lors d'une tâche de recherche sur les besoins énergétiques de l'IA. Voici comment identifier précisément ce qui a mal tourné. D'abord, chargez les traces d'exécution de votre agent depuis un fichier JSON :

import json
from strandsevals.detectors import detectfailures
from strands_evals.types.trace import Session
from strands_evals.detectors import ConfidenceLevel

with open("agent_trace.json") as f:
    session = Session.modelvalidatejson(f.read())

result = detectfailures(session, confidencethreshold=ConfidenceLevel.MEDIUM)

for failure in result.failures:
    for cat, conf, ev in zip(failure.category, failure.confidence, failure.evidence):
        print(f"[{conf}] {cat} at span {failure.span_id}")
        print(f"  Evidence: {ev}")

Cette fonction detect_failures parcourt chaque étape (span) de la session de votre agent et identifie les défaillances selon une taxonomie prédéfinie. Pour chaque erreur détectée, elle retourne :

• L'emplacement exact de l'erreur (l'ID du span)
• La catégorie de l'erreur (par exemple, problème d'exécution, hallucination, erreur d'orchestration)
• Un score de confiance (entre 0 et 1) indiquant la probabilité que l'erreur soit réelle
• Les preuves extraites directement des traces d'exécution

Voici un exemple de sortie pour l'agent de recherche sur l'énergie de l'IA :

[0.9] execution-error-category-tool-schema at span f503a7d546fa4157
  Evidence: Tool execution failed due to missing required parameter
  'knowledgeBaseId'. Error: 'Parameter validation failed: Invalid type
  for parameter knowledgeBaseId, value: None'

[0.75] hallucination-category-hall-usage at span 0466979670d14099
  Evidence: Agent claims 'I don't have access to the specific knowledge
  base needed' and then proceeds to provide detailed information about AI
  energy requirements 'based on general knowledge' without using any tools.

[0.9] orchestration-related-errors-category-goal-deviation at span d98d578e61233d33
  Evidence: Agent completely abandons the original task about AI energy
  requirements and instead provides a lengthy response about marine
  biology, stating 'I'm going to pivot to discuss marine biology instead.'

Dans cet exemple, trois types d'erreurs sont détectés :

1. Un problème d'exécution (le paramètre knowledgeBaseId est manquant)
2. Une hallucination (l'agent invente des informations sans utiliser les outils)
3. Une déviation totale de l'objectif (l'agent parle de biologie marine au lieu d'énergie)

ANALYSER LES CAUSES RACINES DES ÉCHECS

Identifier les erreurs est utile, mais comprendre pourquoi elles se produisent est essentiel pour les corriger. La fonction analyzerootcause prend les défaillances détectées et établit des chaînes causales entre elles. Elle sépare les causes racines des symptômes secondaires et propose des recommandations de correction précises.

Voici comment l'utiliser :

from strandsevals.detectors import detectfailures, analyzerootcause

failures = detect_failures(session)
rcaresult = analyzeroot_cause(session, failures=failures.failures)

for rc in rcaresult.rootcauses:
    print(f"Causality: {rc.causality}")
    print(f"  Span: {rc.failurespanid} | Fix type: {rc.fix_type}")
    print(f"  Root cause: {rc.rootcauseexplanation}")
    print(f"  Recommendation: {rc.fix_recommendation}")

Pour notre agent de recherche, l'analyse des causes racines révèle la structure suivante :

Causality: PRIMARY_FAILURE
  Span: f503a7d546fa4157 | Fix type: TOOLDESCRIPTIONFIX
  Root cause: Agent called retrieve tool without required knowledgeBaseId
    parameter because tool description does not clearly document that
    knowledgeBaseId is mandatory. This caused parameter validation failure
    and forced agent into multiple retry attempts with different parameter
    combinations.
  Recommendation: Update retrieve tool description to explicitly mark
    knowledgeBaseId as a required parameter with clear documentation
    including format constraints and example values.

Causality: SECONDARY_FAILURE
  Span: 0466979670d14099 | Fix type: SYSTEMPROMPTFIX
  Root cause: Agent fabricated detailed AI energy consumption information
    claiming it is 'based on general knowledge' after all retrieval attempts
    failed, because system prompt lacks instruction prohibiting generation
    of factual content without tool-retrieved evidence.
  Recommendation: Add instruction to system prompt requiring agent to
    explicitly acknowledge inability to complete research tasks when
    retrieval tools fail, and prohibit generating detailed factual content
    without tool-verified sources.

L'analyse identifie deux types de problèmes distincts :

• Un TOOLDESCRIPTIONFIX : l'outil retrieve ne documente pas clairement que le paramètre knowledgeBaseId est obligatoire.
• Un SYSTEMPROMPTFIX : le prompt système manque d'instructions pour gérer les échecs des outils de récupération.

DIAGNOSTIQUER UNE SESSION EN UN CLIC

Pour gagner du temps, la fonction diagnose_session combine les deux étapes (détection des échecs et analyse des causes racines) en un seul appel. Elle retourne un résultat unifié avec les défaillances détectées, les causes racines identifiées et les recommandations de correction, le tout dédupliqué.

Exemple d'utilisation :

from strandsevals.detectors import diagnosesession, ConfidenceLevel

result = diagnosesession(session, confidencethreshold=ConfidenceLevel.MEDIUM)
print(f"Found {len(result.failures)} failures, {len(result.root_causes)} root causes")

for rec in result.recommendations:
    print(f"  - {rec}")

Cette approche produit les mêmes résultats que les exemples précédents, mais en une seule opération. Vous obtenez une liste priorisée de changements concrets, classés par type de correction nécessaire.

INTÉGRER LA DÉTECTION DANS VOTRE PIPELINE D'ÉVALUATION

Les détecteurs ne servent pas seulement à analyser des sessions locales. Ils peuvent être intégrés directement dans votre pipeline d'évaluation automatisée. Par exemple, vous pouvez configurer une expérience qui exécute des tests, évalue les performances de votre agent, et déclenche automatiquement une analyse des défaillances dès qu'un échec est détecté.

Voici comment configurer cette intégration :

from strands_evals import Experiment
from strands_evals.evaluators import GoalSuccessRateEvaluator
from strands_evals.detectors import ConfidenceLevel, DiagnosisConfig, DiagnosisTrigger
from strandsevals.types.evaluationreport import EvaluationReport

experiment = Experiment(
    cases=test_cases,
    taskfunction=myagent_task,
    evaluators=[GoalSuccessRateEvaluator()],
    diagnosis_config=DiagnosisConfig(
        trigger=DiagnosisTrigger.ON_FAILURE,
        confidence_threshold=ConfidenceLevel.MEDIUM
    ),
)

report = experiment.run()
report.display(include_recommendations=True)

Cette configuration utilise deux modes de déclenchement :

• ON_FAILURE (par défaut) : l'analyse est lancée uniquement quand au moins un test échoue, ce qui est idéal pour les pipelines CI/CD.
• ALWAYS : l'analyse est effectuée sur chaque cas, même quand les tests passent, pour identifier des comportements sous-optimaux.

Avec cette intégration, votre pipeline CI/CD ne se contente plus de dire « 3 tests ont échoué ». Il vous indique pourquoi ils ont échoué et comment les corriger. Le cycle de feedback est ainsi bouclé : définissez vos cas de test, exécutez l'expérience, obtenez les scores et les diagnostics ensemble, appliquez les correctifs recommandés, puis relancez les tests pour confirmer.

ANALYSER LES TRACES DE PRODUCTION DANS CLOUDWATCH

En production, les traces d'exécution de vos agents ne sont pas stockées localement, mais dans des services comme Amazon CloudWatch Logs. Le CloudWatchProvider permet de récupérer ces traces directement depuis le cloud et de les convertir en objets Session analysables par les détecteurs.

Exemple de récupération et d'analyse :

from strands_evals.providers import CloudWatchProvider
from strandsevals.detectors import diagnosesession, ConfidenceLevel

provider = CloudWatchProvider(agent_name="my-research-agent", region="us-east-1")
data = provider.getevaluationdata(session_id="abc-123-def-456")
session = data["trajectory"]

result = diagnosesession(session, confidencethreshold=ConfidenceLevel.MEDIUM)

for rc in result.root_causes:
    print(f"[{rc.fixtype}] {rc.fixrecommendation}")

Sous le capot, le CloudWatchProvider interroge Amazon CloudWatch Logs Insights pour récupérer les enregistrements OpenTelemetry correspondant à l'ID de session. Il détecte automatiquement le framework de l'agent (Strands, LangChain, ou autre) à partir des métadonnées des spans et les mappe dans un format standardisé de Session.

Les détecteurs fonctionnent avec n'importe quel framework qui exporte des traces OpenTelemetry vers Amazon CloudWatch, pas seulement avec les agents Strands. Vous pouvez également récupérer des traces depuis d'autres services comme Langfuse ou OpenSearch en utilisant les fournisseurs dédiés.

CHOISIR LE BON SEUIL DE CONFIANCE

Les détecteurs utilisent des modèles de langage pour analyser les traces et identifier les défaillances. Trois niveaux de confiance sont disponibles :

• LOW : détecte plus d'erreurs potentielles, mais inclut plus de bruit. Idéal pour une investigation approfondie d'un cas spécifique.
• MEDIUM (par défaut) : offre un bon équilibre entre détection et précision. Recommandé pour un usage régulier.
• HIGH : ne retourne que les défaillances les plus certaines. Réservé à la surveillance en production où seul un haut niveau de certitude est acceptable.

Pour les pipelines CI/CD, privilégiez le mode ON_FAILURE avec un seuil MEDIUM. Cela limite les coûts d'inférence tout en assurant une détection efficace des régressions.

PRIORISER LES CORRECTIFS POUR UNE RÉSOLUTION RAPIDE

Lorsque l'analyse identifie plusieurs causes racines, il est important de les traiter dans le bon ordre. Voici quelques conseils pour optimiser votre processus de correction :

• Corrigez d'abord les échecs primaires : les échecs secondaires et tertiaires disparaissent souvent quand la cause racine est résolue. Cela réduit le nombre d'itérations nécessaires.
• Groupez les recommandations par type de correction : regroupez les TOOLDESCRIPTIONFIX ensemble et les SYSTEMPROMPTFIX ensemble. Cela permet de mesurer l'impact de chaque catégorie de correction indépendamment lors des tests suivants.
• Passez les échecs déjà détectés à analyzerootcause : si vous avez déjà exécuté detect_failures et filtré les résultats, vous pouvez les passer directement à analyzerootcause pour éviter une détection redondante.

Exemple de passage de défaillances pré-détectées :

failures = detect_failures(session)
# . inspect or filter failures .
rca = analyzerootcause(session, failures=failures.failures)

Cette approche permet d'inspecter ou de filtrer les défaillances avant de lancer l'analyse des causes racines, ce qui peut faire gagner du temps sur de grandes sessions.

SUPPRIMER LES TRACES INUTILES POUR ÉVITER LES COÛTS INUTILES

Les traces d'exécution stockées dans Amazon CloudWatch Logs peuvent rapidement faire augmenter vos coûts de stockage. Pour les supprimer, utilisez la commande suivante :

aws logs delete-log-group --log-group-name 

Cette commande efface un groupe de logs spécifique. Assurez-vous de ne pas supprimer des logs importants avant de les avoir analysés.

COMMENCER AVEC UNE SESSION DE TEST

Pour vous familiariser avec les détecteurs, utilisez une session de test contenant des erreurs connues. Le fichier flawed_session.json utilisé dans cet article est disponible dans le SDK Strands. Ce fichier contient des traces d'un agent de recherche qui a rencontré plusieurs types de défaillances, ce qui en fait un excellent cas d'étude pour comprendre le fonctionnement des détecteurs.

COMPRENDRE LE FONCTIONNEMENT DU PIPELINE DE DÉTECTION

Le pipeline de détection des échecs des agents IA fonctionne en deux phases principales, chacune utilisant l'analyse par modèle de langage des traces d'exécution :

Phase 1 : Détection des échecs

Cette phase parcourt chaque étape (span) d'une session et la compare à une taxonomie complète des défaillances organisée en neuf catégories principales :

• Hallucinations
• Actions incorrectes
• Erreurs d'orchestration
• Non-respect des instructions de la tâche
• Erreurs d'exécution
• Erreurs de gestion du contexte
• Comportements répétitifs
• Problèmes de sortie du modèle de langage
• Inadéquation de configuration

Pour chaque défaillance identifiée, le détecteur retourne :

• L'emplacement de l'erreur (l'ID du span)
• Une ou plusieurs catégories de défaillance
• Un score de confiance
• Les preuves extraites des traces

Phase 2 : Analyse des causes racines

Cette phase prend les défaillances détectées et établit des chaînes causales entre elles. Une seule erreur en amont peut déclencher plusieurs échecs en aval. L'analyse des causes racines sépare les causes des symptômes et :

• Classe chaque défaillance selon sa causalité (PRIMAIRE, SECONDAIRE ou TERTIAIRE)
• Détermine l'impact de la propagation
• Génère des recommandations de correction classées par type de correction nécessaire

Les deux phases gèrent des sessions de tailles variables grâce à une stratégie échelonnée :

• Analyse directe pour les sessions qui tiennent dans la fenêtre de contexte du modèle de détection
• Élagage des chemins d'échec pour les sessions modérément grandes (seuls les spans ancêtres et descendants sont conservés)
• Analyse par blocs avec fusion pour les très grandes sessions (le trace est divisée en fenêtres chevauchantes et les résultats sont réconciliés)

GÉRER LES COÛTS D'INFÉRENCE DES MODÈLES DE LANGAGE

L'exécution des détecteurs utilise l'inférence Amazon Bedrock pour l'analyse par modèle de langage, ce qui engendre des coûts. Consultez les tarifs d'Amazon Bedrock pour plus de détails. De plus, le stockage des logs dans Amazon CloudWatch Logs peut également entraîner des frais. Consultez les tarifs d'Amazon CloudWatch pour plus d'informations. Surveillez votre utilisation dans AWS Cost Explorer, surtout si vous intégrez les détecteurs dans des pipelines CI/CD qui s'exécutent fréquemment.

Pour optimiser les coûts :

• Utilisez le seuil de confiance MEDIUM par défaut
• Activez le mode ON_FAILURE dans vos pipelines CI/CD
• Planifiez les analyses en mode ALWAYS de manière périodique (par exemple, hebdomadaire ou par release)

VÉRIFIER LES TRACES AVEC LES OUTILS OPEN TELEMETRY

Pour que les détecteurs fonctionnent correctement, vos agents doivent exporter leurs traces d'exécution au format OpenTelemetry. Ce format standardisé permet de capturer chaque étape (span) de l'exécution de l'agent, y compris les appels aux outils, les décisions du modèle de langage et les interactions avec l'utilisateur.

Pour activer le tracing OpenTelemetry dans vos agents, suivez la documentation du Strands Agents SDK sur la simulation utilisateur. Une fois les traces exportées au format JSON, vous pouvez les analyser avec les détecteurs.

UTILISER LES FOURNISSEURS DE TRACES ALTERNATIFS

Les détecteurs ne se limitent pas à Amazon CloudWatch. Vous pouvez récupérer des traces depuis d'autres services d'observabilité :

• LangfuseProvider : pour récupérer les traces depuis Langfuse
• OpenSearchProvider : pour récupérer les traces depuis OpenSearch

Ces fournisseurs permettent d'évaluer et de diagnostiquer des sessions de production historiques sans relancer les agents. Ils offrent une flexibilité supplémentaire pour intégrer les détecteurs dans des environnements variés.

RECOMMANDATIONS FINALES POUR UNE UTILISATION OPTIMALE

Voici quelques bonnes pratiques pour tirer le meilleur parti des détecteurs de défaillances des agents IA :

• Commencez par un seuil de confiance MEDIUM : il offre un bon équilibre entre détection et précision pour un usage régulier.
• Utilisez ON_FAILURE dans vos pipelines CI/CD : cela limite les coûts d'inférence tout en assurant une détection efficace des régressions.
• Planifiez des audits périodiques en mode ALWAYS : pour identifier des comportements sous-optimaux qui pourraient passer inaperçus dans des tests nominaux.
• Corrigez les échecs primaires en premier : cela résout souvent les échecs secondaires et tertiaires, réduisant le nombre d'itérations nécessaires.
• Groupez les recommandations par type de correction : pour mesurer l'impact de chaque catégorie de correction indépendamment.
• Surveillez vos coûts AWS : surtout si vous intégrez les détecteurs dans des pipelines CI/CD fréquents.

EN RÉSUMÉ : TRANSFORMER LES ÉCHECS EN OPPORTUNITÉS DE PROGRÈS

Les agents IA sont de plus en plus utilisés en production, mais leur complexité rend difficile l'identification des causes de leurs échecs. Traditionnellement, cette tâche reposait sur des ingénieurs seniors qui devaient examiner manuellement des centaines d'étapes pour comprendre ce qui n'allait pas. Ce processus ne passe pas à l'échelle et devient un goulot d'étranglement majeur.

Les détecteurs de Strands Evals changent la donne en automatisant cette analyse. Ils ne se contentent pas de dire « l'agent a échoué ». Ils expliquent pourquoi il a échoué et proposent des correctifs précis, qu'il s'agisse de mettre à jour la description d'un outil ou d'ajouter des instructions dans le prompt système.

En intégrant ces détecteurs dans vos pipelines d'évaluation, vous fermez le cycle de feedback : chaque échec détecté est immédiatement analysé, chaque correctif est testé et validé. Résultat ? Moins de temps perdu en diagnostic manuel, des agents IA plus fiables, et une productivité accrue pour les équipes techniques.