Depurando agentes em produção com o Amazon Bedrock AgentCore Observability

Quando agentes de IA falham em silêncio

Agentes de Inteligência Artificial (IA) em produção têm um comportamento peculiar quando algo dá errado: eles frequentemente falham sem disparar nenhum alerta. Podem retornar respostas plausíveis, mas incorretas; entrar em loops de raciocínio que nunca terminam; ou escolher ferramentas erradas para resolver um problema — tudo isso sem gerar uma exceção sequer nos logs tradicionais.

É justamente para endereçar esse cenário que a AWS apresentou o Amazon Bedrock AgentCore Observability. O recurso oferece visibilidade sobre a execução de agentes em três camadas: métricas, traces e logs estruturados. Com isso, é possível acompanhar cada etapa do raciocínio do agente, inspecionar chamadas de ferramentas e identificar exatamente onde o fluxo desviou do esperado — mesmo quando nenhum erro explícito foi lançado.

Este artigo é a Parte 1 de uma série de dois posts. A Parte 2 aborda otimização de desempenho e gerenciamento de memória.

Pré-requisitos

Para seguir os exemplos práticos descritos neste post, é necessário ter uma conta AWS com o Amazon Bedrock AgentCore habilitado, familiaridade com dashboards do Amazon CloudWatch e consultas básicas de logs, além de conhecimento de papéis e políticas do AWS Gerenciamento de Identidade e Acesso (IAM). Também é necessário ter o CloudWatch Transaction Search ativado na conta e um agente Bedrock AgentCore já implantado ou permissão para implantar um.

Os três padrões de falha mais comuns

Agentes de IA falham de forma diferente das aplicações tradicionais. Os problemas costumam se encaixar em três categorias: qualidade, confiabilidade e eficiência.

Falhas de qualidade

Ocorrem quando o agente conclui a tarefa, mas retorna resultados incorretos. Os sistemas de monitoramento registram execuções bem-sucedidas enquanto os usuários recebem respostas imprecisas. Alucinações são comuns: o agente pode referenciar políticas inexistentes ou gerar dados para preencher lacunas. Em sistemas com múltiplos agentes, esses erros se propagam quando a saída de um agente vira entrada de outro. Revisar os traces de execução é o caminho para identificar onde a lógica quebrou.

Falhas de confiabilidade

Impedem que o agente conclua seu fluxo de trabalho. Erros de invocação de ferramentas são causa frequente: um erro 401 indica credenciais ausentes ou expiradas; um 403 aponta para permissões IAM insuficientes; e um 400 sugere entrada inválida. Outro problema comum é a perda de contexto, onde o agente não retém o estado da sessão e trata requisições de acompanhamento como conversas novas.

Problemas de eficiência

Afetam custo e desempenho, não a correção. Alta latência reduz o engajamento do usuário. Uso excessivo de tokens aumenta o custo sem melhorar os resultados — isso ocorre quando agentes geram respostas muito longas, recuperam documentos completos desnecessariamente ou repetem chamadas de ferramentas em vez de usar cache.

O kit de ferramentas de observabilidade

O Bedrock AgentCore Observability combina três camadas que trabalham juntas para levar o time de engenharia da detecção de um problema até sua causa raiz.

Dashboards do Amazon CloudWatch

O dashboard GenAI Observability exibe volume de sessões, latência de invocação, uso de tokens e taxas de erro em uma visão unificada. É possível filtrar por ID do agente, ID da sessão ou intervalo de tempo. Alarmes do CloudWatch notificam automaticamente quando a latência ultrapassa limites aceitáveis ou quando a taxa de erros sobe acima do normal.

Traces com OpenTelemetry

Enquanto os dashboards mostram o comportamento do sistema em alto nível, os traces mostram como cada requisição é executada passo a passo. O Bedrock AgentCore emite traces distribuídos, logs estruturados em nível de span e métricas sob o namespace bedrock-agentcore do CloudWatch. Essa telemetria segue o protocolo OpenTelemetry (OTEL) e é roteada para o CloudWatch por padrão. Se a organização usar Datadog, Grafana Cloud ou Elastic Observability, é possível exportar a mesma telemetria para esses backends sem instrumentação adicional.

Cada trace captura o fluxo completo de execução: etapas de raciocínio, invocações de ferramentas, recuperações de memória e saídas finais.

Métricas-chave para monitorar

A recomendação é acompanhar três categorias:

• Desempenho: latência nos percentis 50, 95 e 99; tempo de recuperação de memória; tempo de resposta de ferramentas.
• Recursos: duração da sessão, sessões simultâneas e uso de tokens de entrada e saída separadamente.
• Confiabilidade: taxa de erros por categoria — autenticação, autorização, validação e timeout.

Habilitando a observabilidade

Antes de começar a depurar, é preciso ativar o CloudWatch Transaction Search na conta. Isso permite que o Bedrock AgentCore envie dados de trace e métricas ao CloudWatch. Após a ativação, o serviço passa a coletar dados de observabilidade em todos os agentes, sistemas de memória e integrações de ferramentas.

Cenário 1: Depurando loops infinitos

Loops infinitos ocorrem quando agentes não têm condições de encerramento adequadas ou não reconhecem quando cometem erros repetidos. Três causas raiz são as mais frequentes:

• Design de prompt inadequado: o prompt do sistema não estabelece condições de encerramento claras — não especifica quantas tentativas são razoáveis, quando declarar uma tarefa impossível ou quando escalar para um humano.
• Ausência de detecção de loop: o framework do agente não reconhece ações repetidas. Sem lógica explícita para rastrear tentativas anteriores, o agente não consegue perceber que está preso.
• Seleção incorreta de ferramenta: o agente escolhe consistentemente a ferramenta errada, como tentar resolver um cálculo matemático com uma ferramenta de busca na web.

Sintomas a observar

Quando um agente entra em loop, o uso de tokens aumenta significativamente e a duração da sessão cresce além do normal. Em alguns casos, o agente gera múltiplas respostas sem entrada do usuário. O detalhe mais enganoso: a taxa de erros permanece baixa, porque o agente não está travando — ele simplesmente não consegue concluir a tarefa. Alto consumo de tokens combinado com zero erros é o sinal clássico de loop infinito.

Diagnóstico: problema de engenharia de prompt

O primeiro passo é identificar a sessão problemática. A consulta abaixo no CloudWatch Logs Insights localiza sessões com uso de tokens anormalmente alto:

fields @timestamp, SessionId, TokenUsage
| filter TokenUsage > 10000
| sort TokenUsage desc
| limit 20

Com o SessionId em mãos, é possível examinar o padrão de raciocínio do agente naquela sessão:

fields @timestamp, @message, RequestId
| filter SessionId = "<SessionId>"
| filter Operation like /InvokeAgent/
| sort @timestamp asc
| limit 1000

Um trace com 177 spans e latência média de 85.590 ms (~85 segundos) é um sinal claro de loop. Respostas normais de agentes completam em 1 a 5 segundos.

Ao inspecionar os logs de raciocínio, um padrão repetitivo como o abaixo confirma o problema:

"Try using calculator tool with input 25"
"Result: 24.95"
"This is incorrect, try again"
"Try using calculator tool with input 25"
"Result: 24.95"
"This is incorrect, try again"

O trace OpenTelemetry revela a causa raiz: um prompt de sistema instruindo o agente a “nunca desistir” e “continuar tentando até obter a resposta exata” — sem nenhuma condição de encerramento. Para corrigir, basta adicionar instruções explícitas de término ao prompt, como: “Se você tentar a mesma ação três vezes sem sucesso, pare e explique ao usuário por que não consegue concluir a tarefa.” Também é recomendado definir um limite máximo de tokens por sessão (tipicamente 5.000 a 10.000 para um agente conversacional) e um limite de etapas de raciocínio de 10 a 15 passos como parada forçada.

Diagnóstico: falha na detecção de loop

Para examinar sequências de invocação de ferramentas, use:

fields @timestamp, ToolName, ToolInput, ToolOutput
| filter SessionId = "<SessionId>"
| filter Operation like /InvokeTool/
| sort @timestamp asc

Um padrão como o abaixo confirma falha na detecção de loop — a mesma ferramenta sendo chamada dezenas de vezes com entradas quase idênticas, nunca atingindo o valor exato exigido pelo prompt:

2026-02-02 22:02:39 | calculate_percentage | {"value": 25, "total": 100} | 25.0
2026-02-02 22:02:45 | calculate_percentage | {"value": 25, "total": 100} | 25.0
2026-02-02 22:02:51 | calculate_percentage | {"value": 25, "total": 100} | 25.0
[repetido mais 40 vezes]

A correção é adicionar lógica de detecção de loop ao framework do agente: rastrear invocações de ferramentas e etapas de raciocínio, forçar encerramento após três ações idênticas repetidas e configurar um alarme no CloudWatch para alertar quando o uso médio de tokens por sessão crescer significativamente.

Diagnóstico: seleção incorreta de ferramenta

Quando o agente escolhe a ferramenta errada, os logs de trace mostram um padrão como:

"User wants to calculate 25% of 100"
"I should use the web_search tool to find the answer"
[web_search returns irrelevant results]
"Let me try web_search again with different terms"

A solução é fornecer descrições mais claras para cada ferramenta, com exemplos explícitos de uso na configuração do agente:

{
  "tools": [
    {
      "name": "calculator",
      "description": "Use this tool for mathematical calculations, including percentages, arithmetic, and numerical operations. Example: calculating 25% of 100."
    },
    {
      "name": "web_search",
      "description": "Use this tool to find information on the internet. Do NOT use for mathematical calculations."
    }
  ]
}

Cenário 2: Falhas de invocação de ferramentas

Diferentemente dos loops, falhas de invocação de ferramentas geram erros explícitos e taxas de erro elevadas no dashboard. O desafio é identificar rapidamente a causa raiz. Cinco tipos de erro cobrem a maioria dos casos:

• Erros de autenticação (401): credenciais expiradas, ausentes ou método de autenticação incorreto.
• Erros de autorização (403): o papel IAM do agente não tem as políticas necessárias.
• Erros de validação (400): a entrada fornecida pelo agente não corresponde ao schema esperado pela ferramenta.
• Recurso não encontrado (404): nome de ferramenta incorreto, ID de recurso inválido ou ferramenta deletada.
• Erros de execução da ferramenta (500): a própria ferramenta falhou por erros internos, timeouts ou limites de taxa.

Diagnóstico: autenticação e autorização

Para identificar qual ferramenta falha com mais frequência:

fields @timestamp, ToolName, StatusCode, ErrorMessage
| filter Operation like /InvokeTool/
| filter StatusCode like /4[0-9][0-9]|5[0-9][0-9]/
| stats count(*) by ToolName, StatusCode
| sort count desc

No Bedrock AgentCore, as ferramentas são acessadas através de Gateways, e o papel de serviço do Gateway deve ter permissões para invocar os recursos downstream. Para erros 403, por exemplo, se o agente invoca uma função AWS Lambda através do gateway, o papel de serviço do Gateway precisa incluir:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowGatewayToInvokeLambdaTool",
      "Effect": "Allow",
      "Action": [
        "lambda:InvokeFunction"
      ],
      "Resource": [
        "arn:aws:lambda:us-east-1:123456789012:function:my-tool-function"
      ]
    }
  ]
}

Para problemas de credenciais, a recomendação é usar o AWS Secrets Manager para armazenar e rotacionar credenciais automaticamente. Um alarme no CloudWatch para taxas de erro de ferramentas acima de 5% permite investigação imediata.

Diagnóstico: erros de validação

Para erros 400, examine a entrada que o agente forneceu:

fields @timestamp, ToolName, ToolInput, ErrorMessage
| filter StatusCode = 400
| limit 50

Compare a entrada do agente com o schema esperado pela ferramenta. Um exemplo clássico de incompatibilidade:

Tool expected: {"customer_id": "string", "amount": number}
Agent provided: {"customer_id": 12345, "amount": "100.00"}

A correção envolve atualizar os schemas das ferramentas para corresponder à API atual e criar testes de integração que invoquem cada ferramenta com diferentes entradas, incluindo casos extremos.

Diagnóstico: erros de recurso e execução

Para erros 404 e 500, verifique primeiro os próprios logs e métricas da ferramenta — o problema pode não estar no agente. Use a consulta:

fields @timestamp, ToolName, ToolInput, ErrorMessage
| filter StatusCode = 404 or StatusCode = 500
| limit 50

Quando uma ferramenta falha, o agente deve registrar o erro com contexto completo, tentar novamente com backoff exponencial para falhas transitórias, tentar abordagens alternativas quando a ferramenta estiver indisponível e informar claramente o usuário quando não conseguir acessar a ferramenta.

Do diagnóstico reativo ao monitoramento proativo

As consultas apresentadas nos cenários anteriores ajudam a diagnosticar problemas depois que ocorrem. Para detectá-los antes que os usuários reportem, a AWS recomenda converter essas consultas diagnósticas em dashboards e alarmes persistentes.

• Criando um alarme do CloudWatch a partir do Logs Insights: filtros de métricas monitoram continuamente o grupo de logs do agente em busca de padrões que indicam falhas. Ao associar um alarme do CloudWatch, o time é alertado automaticamente — um sistema de alerta antecipado para loops infinitos sem necessidade de executar consultas manualmente.
• Construindo um dashboard do CloudWatch: adicione as consultas diagnósticas principais como widgets no dashboard para manter visibilidade contínua da saúde dos agentes.
• Monitoramento automatizado de precisão com AgentCore Evaluators: os AgentCore Evaluators oferecem avaliação contínua e automatizada do comportamento dos agentes em escala. Em vez de revisar traces manualmente quando algo dá errado, os Evaluators inspecionam sessões em tempo real e pontuam o desempenho do agente contra critérios de qualidade.

Limpeza de recursos

Após concluir os walkthroughs, é importante remover ou desabilitar os recursos criados para evitar cobranças contínuas. Isso inclui deletar consultas salvas no Logs Insights, remover alarmes criados para uso de tokens ou taxas de erro, desativar o CloudWatch Transaction Search se foi habilitado apenas para este exercício, e deletar qualquer agente de teste implantado no console do Amazon Bedrock. Vale destacar que desativar o CloudWatch Transaction Search interrompe toda coleta futura de traces — certifique-se de não precisar mais dos dados antes de desativá-lo.

Conclusão

O Amazon Bedrock AgentCore Observability oferece um framework prático para depurar agentes em produção. As três categorias de falhas — qualidade, confiabilidade e eficiência — têm padrões identificáveis, e as consultas do CloudWatch Logs Insights apresentadas neste post permitem ir da detecção de um problema à sua causa raiz em minutos, não horas. O próximo passo é a Parte 2 da série, que aborda gargalos de desempenho e vazamentos de memória em agentes de produção.

Fonte

Debugging production agents with Amazon Bedrock AgentCore Observability (https://aws.amazon.com/blogs/machine-learning/debugging-production-agents-with-amazon-bedrock-agentcore-observability/)