Comece a usar o AgentCore Observability

Amazon Bedrock O Amazon Bedrock AgentCore Observability ajuda você a rastrear, depurar e monitorar o desempenho do agente em ambientes de produção. Este guia ajuda você a implementar recursos de observabilidade em seus aplicativos de agente.

Pré-requisitos

Antes de começar, verifique se você tem:

O Amazon Bedrock AgentCore Observability oferece duas maneiras de configurar o monitoramento para atender às diferentes necessidades de infraestrutura:

Como uma configuração única por AWS conta, os usuários iniciantes precisam ativar a Pesquisa de transações na Amazon CloudWatch. Há duas maneiras de fazer isso, por meio da API e por meio do CloudWatch console.

Etapa 1: habilitar a pesquisa de transações em CloudWatch

Depois de habilitar o Transaction Search, pode levar dez minutos para que as extensões fiquem disponíveis para pesquisa e análise. Escolha uma das opções abaixo:

Opção 1: ativar a pesquisa de transações usando uma API

Para habilitar a pesquisa de transações usando a API

Opção 2: ativar a pesquisa de transações no CloudWatch console

Para habilitar a pesquisa de transações no CloudWatch console

Vamos agora explorar as duas maneiras de configurar a observabilidade.

Etapa 2: Habilitar a observabilidade para agentes hospedados no Amazon Bedrock AgentCore Runtime

Os AgentCore Runtime-hosted agentes do Amazon Bedrock são implantados e executados diretamente no AgentCore ambiente Amazon Bedrock, fornecendo instrumentação automática com configuração mínima. Quando você implanta um agente usando a AgentCore CLI, o tempo de execução instrumenta automaticamente seu agente OpenTelemetry — nenhuma biblioteca ou configuração adicional do OTEL é necessária.

Para obter um exemplo completo, consulte este caderno

Crie seu projeto de agente

Crie um novo projeto usando a AgentCore CLI. Isso configura a pasta do projeto, o ambiente virtual e as dependências:

npm install -g @aws/agentcore
agentcore create --name StrandsClaudeGettingStarted

No diretório de agentes do projeto, substitua o código padrão do agente pela sua própria lógica de agente. Veja a seguir um exemplo usando o SDK do Strands Agents:

## app/StrandsClaudeGettingStarted/main.py
from strands import Agent, tool
from strands_tools import calculator
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands.models import BedrockModel

app = BedrockAgentCoreApp()

@tool
def weather():
    """Get weather"""
    return "sunny"

model = BedrockModel(
    model_id="us.anthropic.claude-3-7-sonnet-20250219-v1:0",
)
agent = Agent(
    model=model,
    tools=[calculator, weather],
    system_prompt="You're a helpful assistant. You can do simple math calculation, and tell the weather."
)

@app.entrypoint
def strands_agent_bedrock(payload):
    """Invoke the agent with a payload"""
    user_input = payload.get("prompt")
    response = agent(user_input)
    return response.message['content'][0]['text']

if __name__ == "__main__":
    app.run()

Implante e invoque seu agente

Implante o agente no AgentCore Runtime. A AgentCore CLI lida com empacotamento, implantação e instrumentação automática do OTEL:

cd StrandsClaudeGettingStarted
agentcore deploy

Após a implantação, seu agente é executado em AgentCore Runtime e é automaticamente instrumentado usando OpenTelemetry. Chame seu agente e visualize os rastreamentos, as sessões e as métricas no painel do GenAI Observability na Amazon: CloudWatch

agentcore invoke

Como alternativa, você pode invocar seu agente programaticamente usando o SDK: AWS

import boto3, json

client = boto3.client('bedrock-agentcore')

response = client.invoke_agent_runtime(
    agentRuntimeArn="YOUR_AGENT_RUNTIME_ARN",
    runtimeSessionId="my-observability-session-001",
    payload=json.dumps({"prompt": "What is 2 + 2?"}),
    qualifier="DEFAULT"
)

print(json.loads(response['response'].read()))

Etapa 3: habilitar a observabilidade para agentes não pertencentes ao Amazon Bedrock AgentCore-hosted

Para agentes que funcionam fora do tempo de AgentCore execução do Amazon Bedrock, você pode fornecer os mesmos recursos de monitoramento para agentes implantados em sua própria infraestrutura. Isso permite uma observabilidade consistente, independentemente de onde seus agentes operam. Use as etapas a seguir para configurar as variáveis de ambiente necessárias para observar seus agentes.

Para ver um exemplo completo, consulte a amostra Agents on Amazon EKS no GitHub site.

Configurar AWS variáveis de ambiente

export AWS_ACCOUNT_ID=<account id>
export AWS_DEFAULT_REGION=<default region>
export AWS_REGION=<region>
export AWS_ACCESS_KEY_ID=<access key id>
export AWS_SECRET_ACCESS_KEY=<secret key>

Configurar o CloudWatch registro

Crie um grupo de registros e um stream de registros para seu agente na Amazon CloudWatch , que você pode usar para configurar as variáveis de ambiente abaixo.

Configurar variáveis de OpenTelemetry ambiente

export AGENT_OBSERVABILITY_ENABLED=true # Activates the ADOT pipeline
export OTEL_PYTHON_DISTRO=aws_distro # Uses AWS Distro for OpenTelemetry
export OTEL_PYTHON_CONFIGURATOR=aws_configurator # Sets AWS configurator for ADOT SDK
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf # Configures export protocol
export  OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=<YOUR-LOG-GROUP>,x-aws-log-stream=<YOUR-LOG-STREAM>,x-aws-metric-namespace=<YOUR-NAMESPACE>
# Directs logs to CloudWatch groups
export OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-aws-log-group=<YOUR-LOG-GROUP>,x-aws-log-stream=<YOUR-TRACES-LOG-STREAM>
# (Optional) Directs spans to your log group instead of the aws/spans log group. Requires ADOT version 0.18.0 or later.
export OTEL_RESOURCE_ATTRIBUTES=service.name=<YOUR-AGENT-NAME> # Identifies your agent in observability data
export OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false # AWS Lambda Layer for OpenTelemetry only: disables Application Signals
export OTEL_LOGS_EXPORTER=otlp # AWS Lambda Layer for OpenTelemetry only: exports logs over OTLP
export OTEL_METRICS_EXPORTER=awsemf # AWS Lambda Layer for OpenTelemetry only: exports metrics as CloudWatch EMF

<YOUR-AGENT-NAME>Substitua por um nome exclusivo para identificar esse agente no painel e nos registros do GenAI Observability.

Crie um agente localmente

# Create agent.py -  Strands agent that is a weather assistant
from strands import Agent
from strands_tools import http_request

# Define a weather-focused system prompt
WEATHER_SYSTEM_PROMPT = """You are a weather assistant with HTTP capabilities. You can:

1. Make HTTP requests to the National Weather Service API
2. Process and display weather forecast data
3. Provide weather information for locations in the United States

When retrieving weather information:
1. First get the coordinates or grid information using https://api.weather.gov/points/{latitude},{longitude} or https://api.weather.gov/points/{zipcode}
2. Then use the returned forecast URL to get the actual forecast

When displaying responses:
- Format weather data in a human-readable way
- Highlight important information like temperature, precipitation, and alerts
- Handle errors appropriately
- Convert technical terms to user-friendly language

Always explain the weather conditions clearly and provide context for the forecast.
"""

# Create an agent with HTTP capabilities
weather_agent = Agent(
    system_prompt=WEATHER_SYSTEM_PROMPT,
    tools=[http_request],  # Explicitly enable http_request tool
)

response = weather_agent("What's the weather like in Seattle?")
print(response)

Execute seu agente com o comando automático de instrumentação

Com aws-opentelemetry-distro seu requirements.txt, o opentelemetry-instrument comando irá:

Use o comando a seguir para executar seu agente com instrumentação automática:

opentelemetry-instrument python agent.py

Se você hospedar seu agente no AWS Lambda, use a camada AWS Lambda OpenTelemetry no site Distro for. AWS OpenTelemetry Adicione a camada à sua função e, em seguida, defina a variável de AWS_LAMBDA_EXEC_WRAPPER ambiente como/opt/otel-instrument. A camada então instrumenta automaticamente sua função. Com essa abordagem, você não precisa adicionar o aws-opentelemetry-distro pacote ou executar o opentelemetry-instrument comando descrito anteriormente.

Agora você pode visualizar seus rastreamentos, sessões e métricas no GenAI Observability Dashboard na Amazon CloudWatch com o valor do YOUR-AGENT-NAMEque você configurou em suas variáveis de ambiente.

Para correlacionar rastreamentos em várias execuções de agentes, você pode associar uma ID de sessão aos seus dados de telemetria usando bagagem: OpenTelemetry

from opentelemetry import baggage, context
ctx = baggage.set_baggage("session.id", session_id)

Etapa 4: observe seu agente com a observabilidade do GenAI na Amazon CloudWatch

Depois de implementar a observabilidade, você pode visualizar os dados coletados em: CloudWatch

Observe seu agente

Exibir logins CloudWatch

Para ver os logins CloudWatch

Visualizar rastros e intervalos

Para visualizar traços e extensões

Visualizar métricas do

Para visualizar métricas

Práticas recomendadas