User's blog

Monitore agentes de IA on-premises e multi-cloud com o AgentCore Observability

Written by

Make.com Service User

in

O desafio de observar agentes de IA fora da AWS

Quando você constrói agentes de inteligência artificial com frameworks como Strands Agents, LangGraph ou CrewAI, a observabilidade sobre o comportamento desses agentes é indispensável. Isso vale independentemente de onde eles estejam rodando: no Amazon EKS, no Amazon ECS, no AWS Lambda, em servidores on-premises ou em outros provedores de nuvem como Google Cloud Platform (GCP) ou Microsoft Azure.

O Amazon Bedrock AgentCore é a plataforma da AWS para construir, conectar e otimizar agentes em escala, com suporte a qualquer framework ou modelo. Dentro dela, o Amazon Bedrock AgentCore Observability oferece rastreamento nativo, monitoramento e análises que ferramentas locais de monitoramento de nuvem não entregam por padrão. O ponto de atenção: nativamente, o recurso suporta apenas agentes implantados no runtime do AgentCore dentro da AWS. Para agentes rodando em outros ambientes, é necessária configuração adicional para enviar a telemetria ao dashboard.

A AWS publicou um guia completo mostrando exatamente como fazer essa configuração. A seguir, apresentamos os principais conceitos e passos para colocar isso em prática.

Como a solução funciona

A abordagem utiliza o AWS Distro for OpenTelemetry (ADOT) — a Distribuição AWS para OpenTelemetry — rodando em processo junto com a aplicação do agente. O ADOT instrumenta automaticamente o framework do agente, captura spans seguindo as convenções semânticas de IA generativa e exporta a telemetria diretamente para o endpoint OTLP (Protocolo de Telemetria OpenTelemetry) do Amazon CloudWatch, usando autenticação SigV4 com credenciais do IAM (Gerenciamento de Identidade e Acesso).

São três componentes centrais para enviar telemetria de um agente externo ao painel do AgentCore Observability:

  • Auto-instrumentação ADOT: cuida de toda a complexidade de exportar telemetria de ambientes fora da AWS.
  • Credenciais IAM: utilizadas pelo ADOT para autenticar com o CloudWatch e encaminhar traces, métricas e logs ao dashboard.
  • Variáveis de ambiente: contêm configurações específicas do OpenTelemetry para roteamento e autenticação.

Do ponto de vista de serviços AWS envolvidos, o Amazon CloudWatch serve como base para ingestão e armazenamento da telemetria. O AgentCore Observability adiciona dashboards especializados para agentes de IA. O ADOT fornece a capacidade de instrumentação multiplataforma. E o IAM garante a autenticação segura entre os ambientes externos e a AWS.

Imagem original — fonte: Aws

A observabilidade é um pilar fundamental de IA responsável. Ao rotear a telemetria para o AgentCore Observability, é possível enxergar as cadeias de raciocínio do agente, invocações de ferramentas e saídas do modelo. Isso permite detectar alucinações, monitorar respostas inadequadas, acompanhar o uso de tokens para governança de custos e auditar o comportamento dos agentes em diferentes ambientes — algo especialmente crítico para agentes rodando fora da AWS, onde problemas poderiam passar despercebidos sem uma observabilidade centralizada.

Imagem original — fonte: Aws

Pré-requisitos

Antes de começar, é necessário garantir que você tem:

  • Uma conta AWS com acesso ao Amazon Bedrock configurado (o walkthrough usa o Claude Haiku). Verifique os modelos suportados por região da AWS.
  • O CloudWatch Transaction Search habilitado na conta (configuração única).
  • Python 3.10 ou superior instalado no ambiente não-AWS.
  • Credenciais de usuário IAM (access key ID e secret access key) com permissões para: bedrock:InvokeModel, operações de logs no CloudWatch, operações do X-Ray e cloudwatch:PutMetricData.
  • Acesso HTTPS de saída para endpoints da AWS a partir do seu ambiente.

Para habilitar o CloudWatch Transaction Search (uma vez por conta), execute:

aws xray update-trace-segment-destination --destination CloudWatchLogs --region us-east-1

Para verificar se está ativo:

aws xray get-trace-segment-destination --region us-east-1
# Expected: {"Destination": "CloudWatchLogs", "Status": "ACTIVE"}

Passo a passo de configuração

Passo 1: Instalar as dependências

No ambiente não-AWS (servidor on-premises, VM no GCP, VM no Azure ou qualquer máquina com acesso à internet):

pip install "aws-opentelemetry-distro>=0.10.0" boto3 "strands-agents[otel]"

O pacote aws-opentelemetry-distro inclui a auto-instrumentação ADOT com exportadores OTLP específicos para AWS e o aws_configurator, que cuida da autenticação SigV4. O pacote strands-agents[otel] fornece a emissão de traces OpenTelemetry a partir do framework Strands.

Passo 2: Configurar credenciais AWS

export AWS_ACCESS_KEY_ID=<your-access-key-id>
export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
export AWS_REGION=us-east-1

Nota de segurança: Para ambientes de produção, a AWS recomenda usar o IAM Roles Anywhere em vez de chaves de acesso de longa duração. Com esse recurso, workloads on-premises podem obter credenciais temporárias usando certificados X.509.

Passo 3: Definir variáveis de ambiente do OpenTelemetry

Essas variáveis configuram o ADOT para rotear a telemetria ao dashboard do AgentCore Observability:

export AGENT_OBSERVABILITY_ENABLED=true
export OTEL_PYTHON_DISTRO=aws_distro
export OTEL_PYTHON_CONFIGURATOR=aws_configurator
export OTEL_RESOURCE_ATTRIBUTES="service.name=my-external-agent,aws.log.group.names=/aws/bedrock-agentcore/runtimes/my-external-agent"
export OTEL_EXPORTER_OTLP_LOGS_HEADERS="x-aws-log-group=/aws/bedrock-agentcore/runtimes/my-external-agent,x-aws-log-stream=runtime-logs,x-aws-metric-namespace=bedrock-agentcore"
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_TRACES_EXPORTER=otlp

Pontos importantes sobre essa configuração:

  • AGENT_OBSERVABILITY_ENABLED=true ativa o processamento de telemetria específico para IA generativa no ADOT.
  • OTEL_PYTHON_DISTRO=aws_distro e OTEL_PYTHON_CONFIGURATOR=aws_configurator ativam a configuração OpenTelemetry específica para AWS, incluindo a assinatura SigV4 para o endpoint OTLP do CloudWatch.
  • OTEL_RESOURCE_ATTRIBUTES com aws.log.group.names instrui o CloudWatch a indexar a telemetria no dashboard do AgentCore Observability. Sem isso, os traces vão para os logs genéricos do Amazon CloudWatch.
  • OTEL_EXPORTER_OTLP_LOGS_HEADERS com x-aws-metric-namespace=bedrock-agentcore roteia métricas no formato de métrica embarcada para o namespace correto do CloudWatch.

Passo 4: Criar a aplicação do agente

Crie um arquivo chamado agent_test.py com um agente Strands:

from strands import Agent
from strands.models.bedrock import BedrockModel
from opentelemetry import baggage
from opentelemetry.context import attach
import time

# Configure the Bedrock model
model = BedrockModel(
    model_id="us.anthropic.claude-haiku-4-5-20251001-v1:0",
    region_name="us-east-1"
)

# Create the agent
agent = Agent(
    model=model,
    system_prompt="You are a helpful travel assistant."
)

# Set session ID for AgentCore session tracking
# All agent calls after attach() share same session ID for multiple requests/responses
session_id = f"external-session-{int(time.time())}"
ctx = baggage.set_baggage("session.id", session_id)
attach(ctx)

# Run the agent
response = agent("What are the top 3 things to do in Tokyo?")
print(response)

Passo 5: Executar com auto-instrumentação ADOT

O comando opentelemetry-instrument envolve o processo Python com o ADOT, instrumentando automaticamente as chamadas ao Amazon Bedrock e as operações do framework Strands:

opentelemetry-instrument python3.12 agent_test.py

A resposta do agente aparece no terminal. Em segundo plano, o ADOT captura traces, spans e logs, exportando tudo para o CloudWatch. A telemetria fica disponível no dashboard em dois a três minutos após a execução.

Validação a partir do Google Cloud Platform

Para confirmar que a solução funciona a partir de um provedor de nuvem de terceiros, a AWS testou a mesma configuração a partir do Google Cloud Shell — um terminal baseado em navegador rodando na infraestrutura do GCP.

A configuração no Google Cloud Shell segue exatamente o mesmo padrão: instalação das dependências, definição das credenciais AWS como variáveis de ambiente e configuração das variáveis ADOT, desta vez com nomes de serviço identificando o ambiente GCP (por exemplo, gcp-hosted-agent):

# Create a virtual environment
python3.12 -m venv venv
source venv/bin/activate

# Install dependencies
pip install "aws-opentelemetry-distro" boto3 "strands-agents[otel]"

# Set AWS credentials
export AWS_ACCESS_KEY_ID=<your-access-key-id>
export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
export AWS_REGION=us-east-1

# Set ADOT environment variables
export AGENT_OBSERVABILITY_ENABLED=true
export OTEL_PYTHON_DISTRO=aws_distro
export OTEL_PYTHON_CONFIGURATOR=aws_configurator
export OTEL_RESOURCE_ATTRIBUTES="service.name=gcp-hosted-agent,aws.log.group.names=/aws/bedrock-agentcore/runtimes/gcp-hosted-agent"
export OTEL_EXPORTER_OTLP_LOGS_HEADERS="x-aws-log-group=/aws/bedrock-agentcore/runtimes/gcp-hosted-agent,x-aws-log-stream=runtime-logs,x-aws-metric-namespace=bedrock-agentcore"
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_TRACES_EXPORTER=otlp
cat > agent_test.py << 'EOF'
from strands import Agent
from strands.models.bedrock import BedrockModel
from opentelemetry import baggage
from opentelemetry.context import attach
import time

model = BedrockModel(
    model_id="us.anthropic.claude-haiku-4-5-20251001-v1:0",
    region_name="us-east-1"
)
agent = Agent(model=model, system_prompt="You are a helpful assistant.")

# Set session ID for AgentCore session tracking
# All agent calls after attach() share same session ID for multiple requests/responses
session_id = f"gcp-session-{int(time.time())}"
ctx = baggage.set_baggage("session.id", session_id)
attach(ctx)

response = agent("What are the top 3 things to do in Paris?")
print(response)
EOF

opentelemetry-instrument python3.12 agent_test.py

Em dois a três minutos, o agente gcp-hosted-agent aparece no dashboard do AgentCore Observability ao lado de agentes rodando no runtime do AgentCore ou em outros ambientes. A telemetria é idêntica à produzida por agentes hospedados no runtime do AgentCore: sessões, traces, métricas de span, uso de tokens e latência — tudo em uma visão unificada, independentemente de onde o agente roda.

Comparação: ambientes não-AWS vs. runtime do AgentCore

Embora este guia use o Strands Agents, o mesmo padrão baseado em ADOT se aplica a outros frameworks compatíveis com OpenTelemetry. A tabela abaixo resume as principais diferenças entre as duas abordagens:

  • Telemetria suportada: Em ambientes não-AWS, as variáveis OTEL precisam ser configuradas manualmente. No runtime do AgentCore, a configuração é automática e embutida.
  • Gerenciamento de credenciais: Em ambientes externos, usa-se access key/secret do IAM ou o IAM Roles Anywhere. No runtime do AgentCore, a role IAM é atribuída automaticamente.
  • Melhor para: A abordagem manual é ideal para agentes on-premises, no GCP, no Azure ou em qualquer ambiente não-AWS. O runtime do AgentCore é ideal para agentes implantados na AWS com AgentCore.

Ambientes validados

A AWS testou a abordagem de auto-instrumentação ADOT em dois ambientes não-AWS:

  • On-premises (simulado): servidor standalone rodando fora da AWS — agente Strands reportando telemetria (sessões, traces, spans) no AgentCore Observability com sucesso.
  • Google Cloud Shell (GCP): terminal baseado em navegador rodando no Google Cloud Platform — agente Strands reportando telemetria com sucesso.

Boas práticas

Com base nos testes realizados, a AWS recomenda:

  • Use nomes descritivos: o service.name em OTEL_RESOURCE_ATTRIBUTES se torna o nome do agente no dashboard. Use nomes que identifiquem o ambiente, como prod-onprem-support-agent ou staging-gcp-research-agent.
  • Valide as credenciais antes de rodar o agente: execute python -c "import boto3; print(boto3.client('sts').get_caller_identity())". Se falhar, o ADOT também falhará silenciosamente.
  • Use Python 3.10 ou superior: o ADOT exige Python 3.10+. Python 3.12 é recomendado para melhor compatibilidade.
  • Defina session IDs para conversas multi-turno: use a API de baggage do OpenTelemetry para propagar IDs de sessão: 
    from opentelemetry import baggage
from opentelemetry.context import attach
ctx = baggage.set_baggage("session.id", "my-session-123")
attach(ctx)
  • Rotacione as credenciais regularmente: para produção, evite chaves de acesso de longa duração. Considere o IAM Roles Anywhere para workloads on-premises, ou use a federação de identidade do seu provedor de nuvem para assumir roles IAM da AWS.

Limpeza dos recursos

Para remover os recursos criados durante o walkthrough:

# Delete the IAM access key (if created for testing)
aws iam delete-access-key --user-name <your-user> --access-key-id <your-key-id>

# Optionally delete the auto-created CloudWatch log groups
aws logs delete-log-group --log-group-name /aws/bedrock-agentcore/runtimes/my-external-agent --region us-east-1
aws logs delete-log-group --log-group-name /aws/bedrock-agentcore/runtimes/gcp-hosted-agent --region us-east-1

O walkthrough utiliza Amazon Bedrock, Amazon CloudWatch e AWS X-Ray, que geram custos. Consulte as páginas de preços de cada serviço para detalhes.

Conclusão

O Amazon Bedrock AgentCore Observability não se limita a agentes rodando no runtime do AgentCore ou dentro da AWS. Com a auto-instrumentação ADOT, credenciais IAM e as variáveis de ambiente OpenTelemetry corretas, é possível enviar telemetria de qualquer ambiente com acesso à internet — on-premises, GCP, Azure ou qualquer outro lugar — para o mesmo dashboard centralizado.

A configuração exige apenas um pip install e um conjunto de variáveis de ambiente. A telemetria resultante é idêntica à produzida por agentes hospedados no runtime do AgentCore: sessões, traces, métricas de span e uso de tokens em uma visão unificada.

Para começar, clone o código de exemplo no GitHub e siga as instruções do README. Para agentes já rodando na AWS mas fora do runtime do AgentCore (EKS, ECS, Lambda), consulte o tutorial de AgentCore Observability para agentes hospedados no EKS. Para agentes no runtime do AgentCore, a observabilidade é configurada automaticamente — veja como adicionar observabilidade aos seus recursos do AgentCore.

Fonte

Monitor on-premises and multi-cloud AI agents with AgentCore Observability (https://aws.amazon.com/blogs/machine-learning/monitor-on-premises-and-multi-cloud-ai-agents-with-agentcore-observability/)

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *

More posts