AWS Builder Center
Primeiros Passos com a Observabilidade para o Amazon Bedrock AgentCore

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)

  1. …
  2. 4
    Primeiros Passos com a Observabilidade para o Amazon Bedrock AgentCore This article
AWS Solutions Architect

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
Tela do console AWS CloudWatch exibindo a página Transaction Search dentro de Application Signals APM, com o botão Enable Transaction Search visível e pronto para ser clicado

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
Tela do console AWS CloudWatch exibindo a página de configuração do Transaction Search com o toggle Enable Transaction Search ativado, pronto para ser salvo

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
Tela do console AWS exibindo a seção Log deliveries and tracing de um recurso Gateway do AgentCore, com o menu suspenso Add log delivery expandido e a opção To Amazon CloudWatch Logs visível

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
Tela do console AWS exibindo o formulário de configuração de entrega de logs para um Gateway do AgentCore, com o campo de nome do grupo de logs preenchido automaticamente com o padrão para vendedlogs e o status de entrega indicando ativo

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
Tela do console AWS exibindo a seção Tracing na página de detalhes do Gateway do AgentCore, com o botão Edit visível e o rastreamento ainda não habilitado

1.2.8. Mude o toggle de tracing para Enable e clique em Save
Tela do console AWS exibindo o formulário de configuração de rastreamento para um Gateway do AgentCore com o toggle Enable ativado, pronto para ser salvo

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.
Tela do console AWS exibindo a seção Observability de um Gateway do AgentCore após uma invocação bem-sucedida, mostrando métricas de total de invocações, latência, taxa de erros e taxa de throttle, além de confirmar que a entrega de logs e o rastreamento estão ativos

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.1. Abra a página do  Amazon CloudWatch 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
Painel CloudWatch GenAI Observability exibindo métricas resumidas dos recursos do AgentCore, incluindo contagem de Agents e Endpoints, sessões OTEL, Traces, total de tokens, taxa de erros e taxa de throttle


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.
Interface do CloudWatch Transaction Search exibindo o editor de consultas Logs Insights QL com uma consulta de filtro de traces OTEL e o painel de resultados preenchido com spans dos recursos do AgentCore, incluindo IDs de trace, nomes de serviço, timestamps e durações

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:
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)

  1. …
  2. 4
    Primeiros Passos com a Observabilidade para o Amazon Bedrock AgentCore This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article