AWS Builder Center

Builder Center

Primeiros Passos com o Amazon CloudWatch para Observabilidade do Bedrock AgentCore

Primeiros Passos com o Amazon CloudWatch para Observabilidade do Bedrock AgentCore

Reúna todos os componentes do Amazon Bedrock AgentCore em um único agente LangGraph e leia o sistema inteiro de ponta a ponta pela observabilidade de IA generativa do CloudWatch.

Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (10 articles)

  1. 1
    Primeiros Passos com Amazon Bedrock AgentCore Harness e Runtime
  2. …
  3. 10
    Primeiros Passos com o Amazon CloudWatch para Observabilidade do Bedrock AgentCore This article

Carlos Biagolini

AWS Solutions Architect

Introdução

Este artigo faz parte de uma série que estou escrevendo sobre diferentes aspectos do Amazon Bedrock AgentCore. Nos artigos anteriores, cada componente foi apresentado isoladamente e conectado ao mesmo assistente de concessionária de carros usados. Aqui, reunimos todos eles em um único agente e observamos o sistema completo em execução de ponta a ponta. Para um entendimento mais amplo do AgentCore e seus componentes, confira os outros artigos desta série:
Este artigo é diferente dos anteriores. Cada componente já foi descrito isoladamente, então aqui não configuramos nenhum deles manualmente de novo. Em vez disso, subimos um único agente que conecta todos eles e observamos o sistema inteiro rodando de ponta a ponta. O foco é a visão consolidada: um agente, todos os módulos conectados, observados de fora.
Como cada peça foi coberta separadamente antes, este artigo pressupõe que você já sabe como cada uma é configurada. Não vamos repetir nenhum passo a passo de console. O que faltava na série é exatamente isto: ver a orquestração do agente completo e ler seu comportamento pela observabilidade.
Para tornar tudo reprodutível, o repositório complementar provisiona tudo com Terraform. Um único terraform apply sobe o Runtime, o Gateway e seus targets, o Code Interpreter, o Browser, a Memory, a Knowledge Base, a camada de identidade do Cognito, as tabelas do DynamoDB e as roles do IAM, todos conectados entre si. O mesmo apply também constrói e envia a imagem do agente, popula os dados de demonstração e escreve a configuração do testbench, de modo que não há nada para conectar manualmente.

O Que Estamos Construindo

Reutilizamos o assistente da concessionária de carros usados da série, agora como um único deployment integrado:
  • O agente é escrito com LangGraph  em vez do Strands Agents SDK usado em outras partes da série. Isso é deliberado: o AgentCore Runtime  é agnóstico de framework, então um agente no modelo bring-your-own-container funciona da mesma forma.
  • Ele é implantado no AgentCore Runtime como um contêiner ARM64 no Amazon ECR, o mesmo padrão do primeiro artigo .
  • Ele conecta todos os elementos da série: ferramentas pelo Gateway  (uma ferramenta de estoque em Lambda, um conector de Knowledge Base e Web Search), o Code Interpreter  para cálculos, o Browser , a Memory  para recall entre sessões e o Identity  para controle de acesso, tudo sob a observabilidade do AgentCore.
 
 
Diagrama de arquitetura do agente da concessionária de carros usados executando no AgentCore Runtime

Como as Peças se Conectam

O fluxo de requisição amarra toda a série em um único caminho:
  1. Um usuário faz login no Amazon Cognito e recebe um ID token que carrega a claim cognito:groups (Identity).
  2. O testbench chama o endpoint do Runtime com Authorization: Bearer <id-token>. O autorizador JWT do Runtime valida o token na borda e rejeita qualquer um cujo grupo não seja customer ou employee.
  3. Dentro do contêiner, o agente LangGraph lê o token validado, resolve o papel do chamador e registra as ferramentas de acordo (controle de acesso baseado em papel).
  4. Para estoque, conhecimento e busca na web, o agente se conecta a um único AgentCore Gateway via MCP usando SigV4, e o Gateway roteia cada chamada para o target correto.
  5. Para contas exatas, o agente chama o Code Interpreter. Para uma URL específica, ele chama o Browser.
  6. Antes e depois de cada turno, o agente recupera e grava fatos duráveis na Memory.
  7. Cada uma dessas chamadas é emitida para o Amazon CloudWatch: métricas de serviço e logs estruturados da plataforma, além de traces e spans do OpenTelemetry vindos do contêiner instrumentado, dando uma única visão consolidada da execução.

O Repositório Complementar

A implementação completa está disponível no GitHub . O repositório é organizado como um projeto Terraform fullstack:
  • backend/infrastructure contém um arquivo Terraform por serviço da AWS (aws_cognito.tf, aws_dynamodb.tf, aws_agentcore_gateway.tf, aws_agentcore_runtime.tf, e assim por diante).
  • agent/ contém o contêiner LangGraph (agent.py, Dockerfile, requirements.txt).
  • testbench/ contém as formas de exercitar o agente: uma interface de chat no navegador com um proxy local e um script gerador de tráfego.
  • seed/ contém os dados de exemplo e os documentos da Knowledge Base.
A lógica de orquestração do agente vive em agent/agent.py . Ele lê o JWT, filtra as ferramentas por papel, carrega as ferramentas do Gateway via MCP e adiciona o Code Interpreter e o Browser como ferramentas locais. O grafo inteiro é um create_react_agent padrão do LangGraph, o que mostra o quão pouco código de integração a plataforma exige.
Uma decisão de projeto que vale destacar: toda a stack é provisionada como infraestrutura como código, incluindo os próprios recursos do AgentCore. O provedor Terraform da AWS agora expõe recursos nativos do AgentCore (aws_bedrockagentcore_agent_runtime, aws_bedrockagentcore_gateway, aws_bedrockagentcore_gateway_target, aws_bedrockagentcore_memory, aws_bedrockagentcore_code_interpreter e aws_bedrockagentcore_browser), de modo que não há cliques no console para reproduzir o ambiente. O Terraform ainda constrói e envia a imagem e popula os dados durante o apply, controlado por um toggle descrito a seguir.

Passo 1: Provisionar Tudo

Provisione a stack completa com Terraform. Por padrão (auto_bootstrap = true), um único terraform apply faz tudo: provisiona a infraestrutura, constrói e envia a imagem do agente, popula os dados de demonstração e escreve testbench/.env. Como ele constrói a imagem localmente, você precisa do Docker com buildx e da AWS CLI na máquina que executa o Terraform.
 
1
2
3
4
5
6
7
git clone https://github.com/biagolini/TerraformAwsBedrockAgentCoreIntegratedAgent.git
cd TerraformAwsBedrockAgentCoreIntegratedAgent/backend/environments/dev
cp backend.hcl.example backend.hcl # your state bucket and profile
cp terraform.tfvars.example terraform.tfvars # your region and profile
export AWS_PROFILE=<your-profile>
terraform init -backend-config=backend.hcl
terraform apply
A ingestão da Knowledge Base roda de forma assíncrona, então aguarde de dois a três minutos após o apply antes de fazer perguntas à knowledge base. Se você preferir controlar o build e a carga de dados por conta própria (por exemplo, em CI, ou sem Docker), defina auto_bootstrap = false e execute agent/build_and_push.sh e seed/seed.sh manualmente.

Passo 2: Gerar Tráfego

Antes de as visões de observabilidade terem algo a mostrar, o agente precisa ser exercitado. O repositório inclui um gerador de tráfego para isso:
 
1
2
cd testbench
python3 generate_traffic.py
Ele lê o .env gerado e dispara um fluxo constante de requisições (de 2 a 5 por minuto ao longo de 20 minutos por padrão), escolhendo um usuário e um prompt aleatoriamente. A composição de usuários é ponderada em cerca de 45/45/10 entre employee, customer e sem grupo, uma sessão por usuário para que a Memory acumule contexto, e os prompts cobrem todos os componentes: estoque (Gateway mais Lambda), contas de financiamento (Code Interpreter), perguntas à knowledge base, busca na web e a ferramenta de custo exclusiva de employee.
Se você preferir enviar prompts manualmente e ler as respostas, execute python3 proxy.py e abra a interface de chat em http://localhost:8080. Fazer login como jane (employee), john (customer) e alex (sem grupo) e fazer a mesma pergunta exclusiva de employee, por exemplo "What was the acquisition cost of the Ford Explorer?", é a forma mais rápida de ver o controle de acesso do artigo sobre Identity : jane recebe o número, john é recusado, e alex é rejeitado antes mesmo de o contêiner rodar.

Passo 3: Observar o Sistema Inteiro no CloudWatch

É aqui que a visão integrada compensa. Como o agente roda no AgentCore Runtime  e o contêiner é instrumentado com o AWS Distro for OpenTelemetry , suas métricas, logs e traces fluem para a observabilidade de IA generativa do Amazon CloudWatch . Cada componente reporta sob a mesma conta, então você consegue ler toda a orquestração em um único lugar. Para a configuração inicial subjacente (Transaction Search e entrega de logs por recurso), veja o artigo sobre Observability ; esta stack já habilita tudo isso no Terraform.
Abra o console em CloudWatch > GenAI Observability > Bedrock AgentCore. A página inicial tem quatro abas que vão do agregado ao evento individual:
  • All capabilities agrupa os dados por capacidade do AgentCore, com uma subaba para cada uma: Agents, Built-in tools, Gateways, Harnesses, Identity, Memory, Payments e Runtime.
  • All sessions lista as conversas. Uma sessão é uma interação completa do usuário, correlacionada pelo id de sessão.
  • All traces lista os ciclos de requisição-resposta. Cada trace é uma invocação do agente, do prompt de entrada até a resposta final.
  • All spans lista as operações individuais dentro desses traces: um passo de raciocínio, uma chamada de modelo, uma invocação de ferramenta, uma consulta à memory.
As subabas sob All capabilities são cobertas a seguir, na ordem do console. Nem toda capacidade é usada por este projeto, mas vale a pena ver como cada dashboard se parece.

3.1 Agents

O scorecard do agente, populado a partir dos spans do contêiner instrumentado: sessões OTEL, traces, tokens, custo e taxa de erro. Esta é a coisa mais próxima de um resumo único do comportamento do agente.
 
Console do Amazon CloudWatch GenAI Observability com a subaba Agents selecionada em All capabilities

3.2 Built-in tools

Uso das ferramentas Code Interpreter  e Browser . O gerador de tráfego envia perguntas de financiamento que o agente executa pelo Code Interpreter, então as execuções em seu sandbox aparecem aqui. Um detalhe a observar: a entrega por recurso difere por ferramenta. O Code Interpreter aceita logs e traces (ambos configurados no Terraform); o Browser aceita apenas traces, então a stack envia seus traces para o X-Ray sem um stream de log dedicado.
 
As perguntas de financiamento enviadas pelo gerador de tráfego são calculadas no sandbox do Code Int

3.3 Gateways

Cada chamada de ferramenta roteada pelo AgentCore Gateway , com taxas de erro e de throttle. Esta visão única cobre os três targets: a ferramenta de estoque em Lambda, o conector de Knowledge Base e o Web Search. A Knowledge Base  é acessada pelo Gateway, então suas chamadas de retrieval aparecem aqui. A stack também configura a entrega por recurso para ela no Terraform (logs para o CloudWatch Logs, traces para o X-Ray), de modo que seus spans de retrieval também surgem sob a observabilidade do AgentCore, ao lado de suas próprias métricas no console do Amazon Bedrock.
 
Console do CloudWatch GenAI Observability com a subaba Gateways selecionada, mostrando a contagem de

3.4 Harnesses

O AgentCore Harness  é o loop de agente gerenciado, uma alternativa a trazer seu próprio contêiner no Runtime. Este projeto usa o Runtime, não um Harness, então o dashboard marca zero. Ele é mostrado aqui porque o Harness é uma forma comum de rodar agentes e você verá esta aba no console.
 
Console do CloudWatch GenAI Observability com a subaba Harnesses selecionada, mostrando painéis de m

3.5 Identity

Esta visão reporta o AgentCore Identity  de saída (um agente se autenticando em serviços externos), que este projeto não usa, então marca zero. A autorização de entrada da qual este agente depende (incluindo o usuário sem grupo rejeitado) é aplicada na borda do Runtime e surge como métricas do Runtime.
 
Console do CloudWatch GenAI Observability com a subaba Identity selecionada, mostrando uma visão ger

3.6 Memory

Operações de retrieval e de evento contra a AgentCore Memory , com suas latências. É aqui que o recall entre sessões se torna visível como tráfego.
 
Console do CloudWatch GenAI Observability com a subaba Memory selecionada, exibindo a contagem de op

3.7 Payments

O AgentCore Payments  rastreia transações do agente. Este projeto não transaciona, então o dashboard é uma visão geral vazia, mostrada por completude.
 
Console do CloudWatch GenAI Observability com a subaba Payments selecionada, mostrando uma visão ger

3.8 Runtime

O ambiente de hospedagem do agente: sessões do runtime, invocações, erros, throttles e a CPU e memória consumidas. Esta é a saúde operacional do próprio processo do agente.
 
Console do CloudWatch GenAI Observability com a subaba Runtime selecionada, mostrando sessões do run

3.9 All sessions

Uma sessão é uma interação completa do usuário, correlacionada pelo id de sessão que o cliente envia. Esta aba lista as sessões e permite entrar em qualquer uma delas. Como o gerador de tráfego mantém uma sessão por usuário, você pode acompanhar toda a visita de um usuário aqui, incluindo como o componente Memory acumula contexto ao longo dos turnos.
 
Console do CloudWatch GenAI Observability com a aba All sessions selecionada, mostrando uma lista de

3.10 All traces

Um trace é um ciclo de requisição-resposta: uma única invocação do agente, do prompt de entrada até a resposta final. Esta aba lista os traces com sua latência e status, que é a forma mais rápida de identificar um turno lento ou com falha.
 
Console do CloudWatch GenAI Observability com a aba All traces selecionada, listando as invocações d

3.11 All spans

Um span é uma operação dentro de um trace: um passo de raciocínio, uma chamada de modelo, uma invocação de ferramenta, uma consulta à memory. Abrir um trace o decompõe em seus spans, cada um com sua própria duração e contagem de tokens. Essa atribuição passo a passo entre componentes é o que nenhuma visão de serviço isolada oferece, e é onde você olha quando precisa saber exatamente onde uma requisição gastou seu tempo.
 
Console do CloudWatch GenAI Observability com a aba All spans selecionada, listando operações como c

Passo 4: Limpeza

Tudo neste artigo é infraestrutura como código, então destruir é um único comando. A partir do diretório do ambiente:
 
1
2
export AWS_PROFILE=<your-profile>
terraform destroy
Para detalhes de preço dos serviços envolvidos, confira a página de preços do AgentCore  e a página de preços do Amazon Bedrock .

Conclusão

Os artigos anteriores respondiam à pergunta "como eu configuro este componente específico?" Este responde à pergunta que a série havia deixado em aberto: "como é quando todos eles rodam juntos?"
A construção consolidada deixa algumas coisas claras:
  • Um único agente AgentCore pode combinar ferramentas do Gateway, Code Interpreter, Web Search, Browser, Memory, Knowledge Bases e Identity, com muito pouco código de orquestração. O agente LangGraph é um agente reativo padrão; a plataforma faz o trabalho pesado.
  • A infraestrutura como código agora cobre os próprios recursos do AgentCore, então todo o ambiente, incluindo o Runtime, o Gateway e as ferramentas, é reprodutível com Terraform.
  • A observabilidade é onde o sistema integrado se torna legível. A partir de um único namespace do CloudWatch, você consegue ver qual ferramenta o agente escolheu, quanto tempo cada chamada levou, como os tokens foram gastos e se o controle de acesso cumpriu seu papel, tudo atribuído ao componente correto.
O aprendizado mais útil é que o valor desses componentes se potencializa quando eles são combinados. O Identity decide quem entra, o Gateway roteia para a ferramenta certa, a Knowledge Base e o Web Search embasam a resposta, o Code Interpreter torna as contas exatas, a Memory personaliza entre visitas, e a Observability permite ver toda a cadeia. Construir cada um isoladamente ensina a mecânica. Vê-los rodar juntos é o que mostra o sistema.

Referências

Vamos Nos Conectar

Se você achou este artigo útil e quer aprender mais sobre AWS, arquitetura de nuvem, IA, infraestrutura como código e segurança na nuvem, siga o autor para conteúdos e tutoriais futuros:
  • 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 por dentro de mais tutoriais práticos e soluções para desafios de infraestrutura de nuvem e DevOps.
Boas construções na AWS!
# ai# agentic-ai# amazon-bedrock-agentcore# observability# monitoring-observability

Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (10 articles)

  1. 1
    Primeiros Passos com Amazon Bedrock AgentCore Harness e Runtime
  2. …
  3. 10
    Primeiros Passos com o Amazon CloudWatch para Observabilidade do 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