Detecção de Falhas e Análise de Causa Raiz em Agentes de IA com Strands Evals

Quando saber que falhou não é suficiente

Detectar que um agente de IA falhou em produção é apenas o começo do problema. A pergunta mais difícil — e mais custosa — é entender por que ele falhou e o que precisa ser corrigido. Ferramentas tradicionais de avaliação entregam métricas como “esse agente atingiu 60% de taxa de conclusão de objetivos”, mas deixam a equipe revisando manualmente centenas de passos de execução para descobrir o que deu errado.

Para times que operam agentes em escala, essa inspeção manual vira um gargalo real: o tempo entre detectar um problema e publicar uma correção se estende desnecessariamente. É para resolver isso que a AWS introduziu os Detectors no Strands Evals SDK — uma camada de automação que identifica falhas nas execution traces dos agentes e realiza análise de causa raiz, reduzindo o tempo de diagnóstico de horas para minutos.

Os Detectors complementam o framework de avaliação apresentado em um post anterior, respondendo não apenas “o agente foi bem?” mas também “por que ele falhou e o que devo corrigir?”

Por que métricas sozinhas não resolvem

O Strands Evals já oferece sinais de qualidade confiáveis por meio de Cases, Experiments e Evaluators: taxas de sucesso de objetivos, precisão na seleção de ferramentas e pontuações de utilidade. Esses indicadores são essenciais para detectar regressões e entender o desempenho em nível estatístico.

Mas considere o que acontece depois de identificar uma regressão. A taxa de sucesso do agente cai de 85% para 70% após um deploy ou após mudanças no prompt ou nas ferramentas. Os Evaluators confirmam a queda. E agora? É preciso identificar quais comportamentos específicos causaram as falhas, separar causas raiz de sintomas secundários, determinar se a correção pertence ao system prompt ou às definições de ferramentas, e priorizar pelo impacto.

Esse fluxo de diagnóstico tradicionalmente exige que engenheiros seniores inspecionem traces span por span e correlacionem falhas ao longo de centenas de passos — um processo que simplesmente não escala. Os Detectors automatizam esse fluxo. Enquanto os Evaluators respondem “o agente foi bem?” produzindo pontuações por caso, os Detectors respondem “por que falhou?” produzindo diagnósticos por span, com falhas categorizadas, cadeias causais e recomendações de correção.

Como os Detectors funcionam

O pipeline de detecção opera em duas fases, ambas alimentadas por análise baseada em LLM (Modelo de Linguagem de Grande Escala) sobre a execution trace. Para entender melhor os conceitos de sessões, traces e spans de agentes, a AWS disponibiliza a documentação Understand observability for agentic resources in Amazon Bedrock AgentCore.

Fase 1 — Detecção de falhas: varre cada span de uma sessão contra uma taxonomia abrangente de falhas organizada em nove categorias principais: alucinação, ações incorretas, erros de orquestração, não conformidade com instruções de tarefa, erros de execução, erros de manipulação de contexto, comportamento repetitivo, problemas de saída do LLM e incompatibilidade de configuração. Para cada falha identificada, o sistema retorna a localização do span, uma ou mais categorias, um score de confiança e evidências extraídas da trace.

Fase 2 — Análise de causa raiz: recebe as falhas detectadas e traça cadeias causais entre elas. Um único erro upstream frequentemente se propaga em múltiplas falhas downstream. A análise de causa raiz separa causas de sintomas, classifica a causalidade de cada falha (PRIMARY, SECONDARY ou TERTIARY), determina o impacto de propagação e gera recomendações de correção categorizadas pelo local onde a correção deve ser feita: system prompt, descrição de ferramenta ou outro.

Ambas as fases lidam com sessões de tamanhos variados por meio de uma estratégia em camadas: análise direta para sessões que cabem na janela de contexto do modelo Detector selecionado; pruning de caminhos de falha que retém apenas spans ancestrais e descendentes para sessões moderadamente grandes; e análise em chunks com merge para sessões muito grandes, que divide a trace em janelas sobrepostas e reconcilia os resultados.

Pré-requisitos

Para acompanhar os exemplos práticos, são necessários: Python 3.10 ou superior; Strands Evals SDK instalado com pip install strands-agents-evals; acesso habilitado a modelos no Amazon Bedrock (os Detectors usam análise baseada em LLM); e, para os exemplos com Amazon CloudWatch, credenciais AWS configuradas com as permissões logs:StartQuery e logs:GetQueryResults.

Detecção de falhas na prática

Os exemplos a seguir usam uma trace de sessão de um assistente de pesquisa em drug discovery apresentado no post Evaluating AI agents for production: A practical guide to Strands Evals. O agente foi construído com Strands Agents e Amazon Bedrock. Para acompanhar, é necessário rodar o agente com rastreamento OpenTelemetry habilitado e exportar a sessão como JSON. Consulte a documentação de User Simulation no Strands Agents SDK para configurar o rastreamento e exportar sessões.

A função detect_failures recebe um objeto Session (o formato padrão de trace no Strands Evals) e retorna falhas estruturadas. Cada falha inclui o span onde ocorreu, uma ou mais categorias da taxonomia, um score de confiança e evidências extraídas da trace:

import json
from strands_evals.detectors import detect_failures
from strands_evals.types.trace import Session
from strands_evals.detectors import ConfidenceLevel

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

result = detect_failures(session, confidence_threshold=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}")

O exemplo abaixo mostra a saída de um agente de pesquisa que recebeu a tarefa “Research the impact of energy requirements for powering AI in the real world” e encontrou problemas progressivos de configuração de ferramentas:

[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.'

Em uma única passagem, o Detector identifica falhas em múltiplos níveis: erros de execução (validação de parâmetro de ferramenta), problemas semânticos (alucinação a partir de “conhecimento geral”) e problemas de orquestração (desvio completo do objetivo). Um único span pode apresentar múltiplas categorias de falha, cada uma com confiança e evidência independentes.

Análise de causa raiz

Identificar falhas é útil, mas entender por que elas aconteceram é o que direciona as correções. A função analyze_root_cause recebe as falhas detectadas, traça cadeias causais entre elas, separa causas raiz de sintomas downstream e recomenda onde cada correção deve ser aplicada. Se as falhas não forem fornecidas, a função executa a detecção automaticamente.

from strands_evals.detectors import detect_failures, analyze_root_cause

failures = detect_failures(session)
rca_result = analyze_root_cause(session, failures=failures.failures)

for rc in rca_result.root_causes:
    print(f"Causality: {rc.causality}")
    print(f"  Span: {rc.failure_span_id} | Fix type: {rc.fix_type}")
    print(f"  Root cause: {rc.root_cause_explanation}")
    print(f"  Recommendation: {rc.fix_recommendation}")

Continuando com a mesma sessão do agente de pesquisa, a análise de causa raiz revela a estrutura causal:

Causality: PRIMARY_FAILURE
  Span: f503a7d546fa4157 | Fix type: TOOL_DESCRIPTION_FIX
  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: SYSTEM_PROMPT_FIX
  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.

A distinção entre tipos de correção é o que torna a análise de causa raiz acionável. O erro de schema da ferramenta é um TOOL_DESCRIPTION_FIX porque o parâmetro knowledgeBaseId da ferramenta de recuperação não está documentado claramente. A alucinação downstream é um SYSTEM_PROMPT_FIX por falta de instruções sobre como lidar com falhas persistentes de ferramentas. Corrigir apenas uma categoria deixa a outra sem solução.

Diagnóstico integrado com diagnose_session

Para conveniência, a função diagnose_session executa as duas fases como um único pipeline — detecção de falhas seguida de análise de causa raiz — e retorna um DiagnosisResult unificado com recomendações deduplicadas:

from strands_evals.detectors import diagnose_session, ConfidenceLevel

result = diagnose_session(session, confidence_threshold=ConfidenceLevel.MEDIUM)

print(f"Found {len(result.failures)} failures, {len(result.root_causes)} root causes")
for rec in result.recommendations:
    print(f"  - {rec}")

Com uma única chamada de função, obtém-se uma lista priorizada de mudanças concretas categorizadas pelo local onde devem ser aplicadas.

Integração com pipelines de avaliação

Os Detectors ganham ainda mais valor quando integrados ao fluxo de avaliação existente. O DiagnosisConfig anexa diagnóstico automatizado a qualquer experimento, de forma que cada caso de teste com falha produza automaticamente um diagnóstico:

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

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

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

Dois modos de trigger estão disponíveis. ON_FAILURE (padrão) executa o diagnóstico apenas quando pelo menos um avaliador retorna test_pass=False, mantendo os custos de LLM proporcionais às taxas de falha — ideal para detecção de regressões em pipelines de Integração Contínua e Entrega Contínua (CI/CD). ALWAYS executa o diagnóstico em todos os casos independentemente do resultado, útil para identificar caminhos subótimos em casos que nominalmente passam.

Atenção aos custos: a execução dos Detectors usa inferência do Amazon Bedrock para análise baseada em LLM, o que gera cobranças. Consulte a tabela de preços do Amazon Bedrock para detalhes. O armazenamento de logs no Amazon CloudWatch também gera cobranças — consulte os preços do Amazon CloudWatch. Monitore o uso no AWS Cost Explorer, especialmente ao integrar Detectors em pipelines de CI/CD com execuções frequentes.

Diagnóstico de sessões em produção via CloudWatch

Os exemplos anteriores usam arquivos de sessão locais, mas em produção as traces do agente ficam no Amazon CloudWatch Logs, exportadas com OpenTelemetry. O CloudWatchProvider busca traces diretamente do Amazon CloudWatch e os converte em objetos Session prontos para análise com os Detectors:

from strands_evals.providers import CloudWatchProvider
from strands_evals.detectors import diagnose_session, ConfidenceLevel

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

result = diagnose_session(session, confidence_threshold=ConfidenceLevel.MEDIUM)

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

Por baixo dos panos, o provider consulta o Amazon CloudWatch Logs Insights por registros OTEL correspondentes ao ID de sessão, detecta automaticamente o framework do agente (Strands, LangChain ou outros) a partir dos metadados dos spans e mapeia os spans para uma Session padronizada. Os Detectors funcionam com qualquer framework que exporte traces OpenTelemetry para o Amazon CloudWatch — não apenas com Strands Agents. Também é possível recuperar traces do Langfuse ou OpenSearch usando LangfuseProvider ou OpenSearchProvider.

Boas práticas

• Comece com confiança MEDIUM. O threshold LOW captura mais problemas potenciais, mas com mais ruído — útil para investigação profunda de um caso específico. MEDIUM oferece boa relação sinal/ruído para uso rotineiro. Reserve HIGH para monitoramento em produção onde apenas achados de alta certeza são desejados.
• Use ON_FAILURE em CI/CD e ALWAYS para auditorias periódicas. ON_FAILURE mantém os custos de LLM proporcionais às taxas de falha, tornando-o prático para cada execução de teste. Agende execuções no modo ALWAYS semanalmente ou por release para capturar comportamentos subótimos em casos que passam.
• Corrija falhas PRIMARY primeiro. Falhas secundárias e terciárias frequentemente se resolvem quando a causa raiz é endereçada. Antes de implementar múltiplas recomendações, verifique se corrigir a falha primária elimina as downstream.
• Agrupe recomendações por tipo de correção. Agrupe mudanças de TOOL_DESCRIPTION_FIX juntas e de SYSTEM_PROMPT_FIX juntas. Isso torna o impacto de cada categoria de mudança independentemente mensurável ao re-executar a avaliação.
• Passe falhas pré-detectadas para analyze_root_cause. Se você já executou detect_failures e quer inspecionar os resultados antes de rodar a análise de causa raiz, passe-os diretamente para evitar detecção redundante:

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

• Use a sessão de teste para experimentação. O arquivo flawed_session.json usado nos exemplos está disponível na suite de testes do Strands Evals para você testar os Detectors localmente.

Limpeza de recursos

As funções dos Detectors em si não provisionam recursos AWS persistentes. No entanto, se você configurou exportação de traces do agente para o Amazon CloudWatch Logs, vale revisar dois pontos: os log groups do CloudWatch (excluir um log group remove permanentemente todos os dados de log — confirme que exportou o que precisa antes de prosseguir); e o acesso a modelos no Amazon Bedrock (se habilitou o acesso apenas para este walkthrough, revogue-o pelo console do Amazon Bedrock em Model access).

Conclusão

Os Detectors do Strands Evals fecham o ciclo entre medir a qualidade de um agente e melhorá-la. Ao automatizar a detecção de falhas e a análise de causa raiz que antes exigiam inspeção manual de traces, as equipes passam de “o teste falhou” para “aqui está o que corrigir” em minutos, não horas.

Para começar, consulte a documentação de Detectors do Strands Evals SDK e o repositório GitHub do Strands Evals. Experimente o arquivo de trace de exemplo incluído e adicione o DiagnosisConfig a um caso de teste existente no seu pipeline de avaliação para ver o diagnóstico automatizado em ação.

Fonte

AI Agent Failure Detection and Root Cause Analysis with Strands Evals (https://aws.amazon.com/blogs/machine-learning/ai-agent-failure-detection-and-root-cause-analysis-with-strands-evals/)