
Primeiros Passos com a Observabilidade para o Amazon Bedrock AgentCore
Um guia prático para ativar o CloudWatch Transaction Search, configurar entrega de logs e rastreamento para recursos do AgentCore, e usar o painel GenAI Observability para monitorar seus agentes de IA em produção
Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (11 articles)
- …
- 4Primeiros Passos com a Observabilidade para o Amazon Bedrock AgentCore This article
Introdução
Construir um agente de IA é apenas metade do desafio. Uma vez que seu agente está rodando em produção, você precisa de visibilidade sobre o que ele está fazendo: quais ferramentas ele chama, quanto tempo cada etapa leva, quantos tokens ele consome e onde os erros ocorrem. Sem observability, depurar o comportamento do agente se torna pura adivinhação.
Amazon Bedrock AgentCore Observability é um serviço gerenciado que fornece tracing, métricas e logging para todos os recursos do AgentCore. Ele se integra com o Amazon CloudWatch e suporta o padrão OpenTelemetry (OTEL), oferecendo visualizações detalhadas de cada etapa no fluxo de trabalho do agente. Você pode inspecionar caminhos de execução, auditar saídas intermediárias, rastrear consumo de tokens e depurar gargalos de performance.
Este artigo faz parte de uma série explorando os componentes do Amazon Bedrock AgentCore. Aqui, focamos em habilitar observability para seus recursos AgentCore (Harness, Gateway, Browser, Code Interpreter) para que você possa monitorar e depurar seus agentes de forma eficaz. Para a série completa, veja:
O que é AgentCore Observability?
AgentCore Observability fornece métricas integradas para todos os tipos de recursos do AgentCore: Runtime, Harness, Memory, Gateway, ferramentas integradas (Browser, Code Interpreter) e Identity. Esses dados ficam disponíveis no Amazon CloudWatch através do dashboard GenAI Observability .
O que você obtém
- Traces e spans — Visibilidade ponta a ponta da execução do agente, incluindo chamadas de ferramentas com entradas, saídas e temporização
- Métricas — Contagem de sessões, latência, duração, uso de tokens e taxas de erro
- Logs — Logs estruturados das sessões do agente
- Atributos personalizados — Adicione metadados de negócio aos traces para filtragem e análise
Como funciona
O AgentCore emite telemetria no formato OpenTelemetry (OTEL). A única configuração necessária é habilitar o CloudWatch Transaction Search , que ativa a ingestão de spans nos CloudWatch Logs. Depois disso, todos os recursos do AgentCore enviam automaticamente seus dados de observability para o CloudWatch.
Para agentes hospedados no AgentCore Runtime (incluindo Harness), a observability é automaticamente habilitada sem alterações adicionais no código. Para agentes hospedados fora do AgentCore, você precisa adicionar o AWS Distro for OpenTelemetry (ADOT) SDK ao código do seu agente.
Pré-requisitos
- Conta AWS com credenciais configuradas
- Pelo menos um recurso AgentCore já criado (Harness, Gateway ou Runtime dos artigos anteriores desta série)
- Região AWS onde o AgentCore está disponível (us-east-1, us-west-2, ap-southeast-2 ou eu-central-1)
Step 1: Habilitar Observability
Habilitar observability para os recursos do AgentCore requer duas configurações. Ambas são obrigatórias para visibilidade completa do comportamento do seu agente.
1.1 Habilitar CloudWatch Transaction Search
CloudWatch Transaction Search é uma configuração única por conta AWS e região. Ele ativa a ingestão de spans nos CloudWatch Logs, o que é necessário para visualizar traces e spans dos recursos do AgentCore.
1.1.2. No painel de navegação à esquerda, expanda Application Signals (APM) e escolha Transaction Search
1.1.3. Clique no botão Enable Transaction Search

1.1.4. Na página de configuração, habilite o toggle Enable Transaction Search. Isso inicia a ingestão de todos os spans como logs estruturados no formato OpenTelemetry.
1.1.5. Clique em Save

Alternativamente, você pode habilitar o Transaction Search via AWS CLI usando
aws logs put-resource-policy e aws xray update-trace-segment-destination . Para mais detalhes, veja Enabling CloudWatch Transaction Search .1.2 Habilitar Entrega de Logs e Tracing para seus Recursos
O Transaction Search sozinho não ativa a entrega de logs para recursos individuais. O AgentCore não configura destinos de log automaticamente para Gateway, Memory ou ferramentas integradas. Você precisa habilitar duas coisas em cada recurso que deseja monitorar:
- Entrega de logs — Logs estruturados de operações: invocações de ferramentas, conteúdo de request/response, erros. Use esses logs para depuração detalhada quando precisar inspecionar o payload exato de uma chamada de ferramenta.
- Tracing — Rastreamento distribuído no formato OpenTelemetry. Mostra o fluxo ponta a ponta de uma requisição: duração de cada etapa, linha do tempo das chamadas de ferramentas, detalhamento de latência e identificação de erros. Os spans são armazenados no log group
aws/spans.
Existem duas abordagens para habilitar isso:
- Por recurso (recomendado para controle de custos) — Você configura entrega de logs e tracing apenas para os recursos específicos que deseja monitorar. É o que usamos neste tutorial.
- Nível de conta (via CloudWatch > Ingestion > Data Sources) — Habilita a ingestão para todos os recursos atuais e futuros de um determinado tipo. É mais conveniente, mas pode gerar custos indesejados se você tiver muitos recursos. Essa abordagem também requer habilitar "resource discovery" no CloudWatch primeiro.
Neste artigo, usamos a abordagem por recurso para manter os custos mínimos.
Habilitar entrega de logs:
1.2.1. Navegue até Amazon Bedrock AgentCore > Gateways no Console AWS
1.2.2. Selecione seu Gateway (por exemplo,
LuckyNumberGateway )1.2.3. Na seção Log delivery, clique em Add log delivery e selecione To Amazon CloudWatch Logs

1.2.4. O console preenche automaticamente um nome de log group padrão com o padrão
/aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/<gateway-id> . Aceite o valor padrão.1.2.5. Clique em Add e verifique se o status mostra Delivery active

Habilitar tracing:
1.2.6. Na mesma página de detalhes do Gateway, role até a seção Tracing
1.2.7. Clique em Edit

1.2.8. Mude o toggle de tracing para Enable e clique em Save

Após completar ambas as configurações, a seção Observability na página do Gateway não mostrará mais a mensagem "Resource doesn't have Log deliveries added and Traces enabled."
Repita esse processo para qualquer outro recurso que deseja monitorar (Browser, Code Interpreter, Memory). Os passos são os mesmos: adicionar um destino de entrega de logs e habilitar tracing na página de detalhes do recurso. Para a referência completa, veja Configure log destinations and tracing delivery .
Step 2: Invocar o Gateway para Gerar Dados de Observability
Com a observability habilitada, você precisa de pelo menos uma invocação para gerar dados. Vamos repetir o mesmo teste do artigo anterior para produzir traces e logs.
2.1. Navegue até Amazon Bedrock AgentCore > Harness
2.2. Clique no nome do seu Harness (
car_agent )2.3. Clique no botão Test Harness
2.4. Insira o seguinte prompt:
Hi! My name is Alice. Can you give me a lucky number for today?
2.5. Aguarde a resposta do agente. O agente invocará a ferramenta
get_lucky_number do Gateway e retornará um resultado.
Após a invocação ser concluída, os dados de observability (logs e traces) começarão a aparecer no CloudWatch. Note que pode levar alguns minutos para os dados ficarem disponíveis.
Você pode verificar que tudo está funcionando retornando à página de detalhes do Gateway. A seção Observability agora mostrará métricas (total de invocações, latência, taxa de erro, taxa de throttle) e a seção Log deliveries and tracing confirmará que tanto a entrega de logs quanto o tracing estão ativos.
Step 3: Visualizar Traces e Métricas
Após a observability estar habilitada e você ter invocado seu agente pelo menos uma vez, é possível visualizar os dados no CloudWatch.
3.1 Acessar o Dashboard GenAI Observability
3.1.2. Você verá uma visão geral dos seus recursos AgentCore com métricas principais: contagem de invocações, latência, uso de tokens e taxas de erro

3.2 Visualizar Traces
3.2.1. No console do CloudWatch, navegue até Application Signals (APM) > Transaction search
3.2.2. Selecione a aba Logs Insights QL e execute a seguinte query para listar traces recentes:
filterIndex @data_format = 'AWS-OTEL-TRACE-V1'| FIELDS traceId,name,@timestamp,attributes.aws.local.service as service,attributes.aws.local.environment as environment,attributes.http.response.status_code as statusCode,durationNano,spanId,@message,@log as accountId| SORT @timestamp ASC| LIMIT 10000
3.2.3. Clique em Run query. Os resultados mostrarão spans dos seus recursos AgentCore, incluindo as invocações do Gateway do Step 2.

3.2.4. Clique em um trace para ver a linha do tempo completa de execução, incluindo:
- Cada chamada de ferramenta com parâmetros de entrada e saída
- Tempo gasto em cada etapa
- Uso de tokens por invocação de modelo
- Detalhes de erros caso alguma etapa tenha falhado
3.3 O que procurar
Ao revisar traces, cada span inclui:
- Service name — Qual recurso AgentCore gerou o span (por exemplo,
harness_car_agent.DEFAULT)
- Operation name — Qual ação foi realizada (por exemplo, GET, InternalOperation)
- Duration — Quanto tempo a operação levou (em nanossegundos)
- Status code — Código de status HTTP da resposta (200, 500, etc.)
- Remote service — Qual serviço externo foi chamado (por exemplo, endpoint do Gateway, endpoint do modelo)
Esses dados ajudam você a identificar gargalos de latência, operações com falha e o fluxo geral da execução do seu agente. Para mais orientações sobre como aproveitar esses dados de forma eficaz, veja AWS observability best practices .
Conclusão
Neste artigo, você habilitou observability para seus recursos do Amazon Bedrock AgentCore:
- CloudWatch Transaction Search é uma configuração única que ativa a ingestão de spans. Sem ele, você não consegue visualizar traces ou spans do AgentCore.
- Observability em nível de recurso habilita entrega de logs e tracing para recursos individuais (Gateway, Browser, Code Interpreter).
- O dashboard GenAI Observability fornece uma visão unificada de métricas, traces e spans de todos os seus recursos AgentCore.
Observability é essencial para agentes em produção. Ela oferece confiança de que seu agente está chamando as ferramentas corretas, respondendo dentro de uma latência aceitável e tratando casos extremos de forma adequada. Conforme você adiciona mais ferramentas e complexidade ao seu agente de concessionária em artigos futuros, esses traces serão a principal forma de depurar e otimizar o comportamento.
Referências
Fique Conectado
Se você achou este artigo útil e quer aprender mais sobre AWS, arquitetura cloud, IA, infraestrutura como código e segurança na nuvem, siga o autor para conteúdos futuros e tutoriais:
- LinkedIn: https://www.linkedin.com/in/biagolini
- Medium: https://medium.com/@biagolini
- GitHub: https://github.com/biagolini
- YouTube (PT-BR): https://www.youtube.com/@BiagoliniTech
- AWS Builder Center (PT-BR): https://builder.aws.com/community/@cbiagolini
Fique ligado para mais walkthroughs práticos e soluções para desafios de infraestrutura cloud e DevOps.
Happy building on AWS! 🚀☁️
Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (11 articles)
- …
- 4Primeiros Passos com a Observabilidade para o Amazon Bedrock AgentCore This article
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article