# 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.
**Topics**
+ [Pré-requisitos](#prerequisites)
+ [Etapa 1: habilitar a pesquisa de transações em CloudWatch](#enabling-transaction-search)
+ [Etapa 2: Habilitar a observabilidade para agentes hospedados no Amazon Bedrock AgentCore Runtime](#enabling-observability-runtime-hosted)
+ [Etapa 3: habilitar a observabilidade para agentes não pertencentes ao Amazon Bedrock AgentCore-hosted](#enabling-observability-non-runtime-hosted)
+ [Etapa 4: observe seu agente com a observabilidade do GenAI na Amazon CloudWatch](#agentcore-observability-genai-cloudwatch)
+ [Práticas recomendadas](#best-practices)
## Pré-requisitos
Antes de começar, verifique se você tem:
+ ** AWS Conta** com credenciais configuradas (`aws configure`) com acesso ao modelo habilitado para o Foundation Model que você gostaria de usar.
+ **Python 3.10\+ instalado**
+ **Ative a pesquisa de transações** na Amazon CloudWatch. Somente uma vez, usuários iniciantes devem ativar a [Pesquisa de CloudWatch Transações](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Enable-TransactionSearch.html) para visualizar extensões e rastreamentos do Bedrock Amazon Bedrock AgentCore
+ **(somente Non-runtime agentes) Adicione a OpenTelemetry biblioteca** — Inclua `aws-opentelemetry-distro` (ADOT) em seu arquivo requirements.txt. Se você hospedar seu agente no AWS Lambda, use a [camada AWS Lambda OpenTelemetry no site AWS Distro for](https://aws-otel.github.io/docs/getting-started/lambda). OpenTelemetry
+ **(somente Non-runtime agentes)** Certifique-se de que sua estrutura esteja configurada para emitir rastreamentos (por exemplo, `strands-agents[otel]` pacote). Às vezes, você pode precisar incluir o instrumentador automático da estrutura do seu agente (por exemplo,). `opentelemetry-instrumentation-langchain`
O Amazon Bedrock AgentCore Observability oferece duas maneiras de configurar o monitoramento para atender às diferentes necessidades de infraestrutura:
1. Agentes Amazon Bedrock AgentCore Runtime-hosted
1. Non-runtime agentes hospedados
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**
1. Crie uma política que conceda acesso a períodos de ingestão em CloudWatch registros usando a CLI AWS .
Um exemplo é mostrado abaixo sobre como formatar seu comando AWS CLI com. `PutResourcePolicy`
```
aws logs put-resource-policy --policy-name MyResourcePolicy --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Sid": "TransactionSearchXRayAccess", "Effect": "Allow", "Principal": { "Service": "xray.amazonaws.com" }, "Action": "logs:PutLogEvents", "Resource": [ "arn:partition:logs:region:account-id:log-group:aws/spans:*", "arn:partition:logs:region:account-id:log-group:/aws/application-signals/data:*" ], "Condition": { "ArnLike": { "aws:SourceArn": "arn:partition:xray:region:account-id:*" }, "StringEquals": { "aws:SourceAccount": "account-id" } } } ]}'
```
1. Configure o destino dos segmentos de rastreamento.
Um exemplo é mostrado abaixo sobre como formatar seu comando AWS CLI com. `UpdateTraceSegmentDestination`
```
aws xray update-trace-segment-destination --destination CloudWatchLogs
```
1. **Opcional** Configure a quantidade de extensões a serem indexadas.
Configure a porcentagem de amostragem desejada com`UpdateIndexingRule`.
```
aws xray update-indexing-rule --name "Default" --rule '{"Probabilistic": {"DesiredSamplingPercentage": number}}'
```
### Opção 2: ativar a pesquisa de transações no CloudWatch console
**Para habilitar a pesquisa de transações no CloudWatch console**
1. Abra o CloudWatch console em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. No painel de navegação, em **Configuração**, escolha **Configurações**.
1. Selecione **Conta** e escolha a guia **X-Ray Rastreamentos**.
1. Na seção **Pesquisa de transações**, escolha **Exibir configurações**.
1. Na página que se abre, escolha **Editar**.
1. Escolha **Habilitar Transaction Search**.
1. Selecione **Para X-Ray usuários** e insira a porcentagem de rastreamentos a serem indexados. Você pode indexar 1% dos rastreamentos sem nenhum custo e ajustar essa porcentagem posteriormente com base em suas necessidades.
1. Escolha **Salvar**. Espere até que ** OpenTelemetry os intervalos de ingestão apareçam** **Ativados** antes de enviar rastreamentos.
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](https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/06-AgentCore-observability/01-Agentcore-runtime-hosted/Strands%20Agents/runtime_with_strands_and_bedrock_models.ipynb)
### 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](https://github.com/awslabs/agentcore-samples/tree/main/03-integrations/agents-hosted-outside-runtime/agents-on-eks) no GitHub site.
### Configurar AWS variáveis de ambiente
```
export AWS_ACCOUNT_ID=
export AWS_DEFAULT_REGION=
export AWS_REGION=
export AWS_ACCESS_KEY_ID=
export AWS_SECRET_ACCESS_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=,x-aws-log-stream=,x-aws-metric-namespace=
# Directs logs to CloudWatch groups
export OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-aws-log-group=,x-aws-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= # 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
```
{{}}Substitua por um nome exclusivo para identificar esse agente no painel e nos registros do GenAI Observability.
**nota**
Se você definir `OTEL_EXPORTER_OTLP_TRACES_HEADERS` a entrega de extensões para seu próprio grupo de registros, você também deve adicionar uma política de recursos do Amazon CloudWatch Logs. A política deve permitir que X-Ray (`xray.amazonaws.com`) chame `logs:PutLogEvents` esse grupo de registros. Use a mesma política mostrada em [Habilitar a pesquisa de transações usando uma API](#enable-transaction-search-api), com o ARN do seu grupo de registros. `Resource` Sem essa política, não é X-Ray possível entregar extensões ao seu grupo de registros.
### 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á:
+ Carregue sua configuração de OTEL a partir de suas variáveis de ambiente
+ Instrumente automaticamente Strands, chamadas do Amazon Bedrock, ferramentas e bancos de dados do agente e outras solicitações feitas pelo agente
+ Envie rastros para CloudWatch
+ Permite que você visualize o processo de tomada de decisão do agente no painel de observabilidade do GenAI
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](https://aws-otel.github.io/docs/getting-started/lambda). 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.
**O ADOT Collector não é compatível com a observabilidade do agente**
O ADOT Collector não é compatível com a observabilidade do agente. Para enviar telemetria de um agente hospedado fora do AgentCore tempo de execução, você deve usar o ADOT SDK ou o Lambda AWS Layer for. OpenTelemetry
Agora você pode visualizar seus rastreamentos, sessões e métricas no GenAI Observability Dashboard na Amazon CloudWatch com o valor do **YOUR-AGENT-NAME**que você configurou em suas variáveis de [ambiente](#configure-opentelemetry-environment-variables).
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
1. Abra o [GenAI Observability](https://console.aws.amazon.com/cloudwatch/home#gen-ai-observability) no console CloudWatch
1. Você pode visualizar os dados relacionados às invocações do modelo e aos agentes no Bedrock Amazon AgentCore Bedrock no painel.
1. Na guia Bedrock Agentcore, você pode visualizar a Visualização dos Agentes, a Visualização das Sessões e a Visualização dos Traços.
1. O Agents View lista todos os seus agentes que estão ativos e não em tempo de execução. Você também pode escolher um agente e ver mais detalhes, como métricas de tempo de execução, sessões e rastreamentos específicos de um agente.
1. Na guia **Visualização de sessões**, você pode navegar por todas as sessões associadas aos agentes.
1. Na guia **Trace View**, você pode examinar os rastreamentos e as informações de extensão dos agentes. Explore também a trajetória e o cronograma do traçado escolhendo um traçado.
### Exibir logins CloudWatch
**Para ver os logins CloudWatch**
1. Abra o [console do CloudWatch ](https://console.aws.amazon.com/cloudwatch/).
1. **No painel de navegação esquerdo, expanda **Registros e selecione Grupos de registros****
1. Pesquise o grupo de registros do seu agente:
+ Registros padrão (stdout/stderr) Localização: `/aws/bedrock-agentcore/runtimes/-/[runtime-logs] `
+ Registros estruturados do OTEL: `/aws/bedrock-agentcore/runtimes/-/runtime-logs`
### Visualizar rastros e intervalos
**Para visualizar traços e extensões**
1. Abra o [console do CloudWatch ](https://console.aws.amazon.com/cloudwatch/).
1. Selecione **Pesquisa de transações** no painel de navegação à esquerda
1. Local: o fluxo de `spans` registros no grupo de registros do agente (`/aws/bedrock-agentcore/runtimes/-`) ou o fluxo de `default` registros no grupo de `aws/spans` registros para agentes que usam o destino de intervalo compartilhado
1. Filtrar por nome do serviço ou outros critérios
1. Selecione um rastreamento para visualizar o gráfico de execução detalhado
### Visualizar métricas do
**Para visualizar métricas**
1. Abra o [console do CloudWatch ](https://console.aws.amazon.com/cloudwatch/).
1. Selecione **Métricas** na navegação à esquerda
1. Navegue até o `bedrock-agentcore` namespace
1. Explore as métricas disponíveis
## Práticas recomendadas
1. **Comece de forma simples e depois expanda**: a observabilidade padrão fornecida pelo Amazon Bedrock AgentCore captura automaticamente as métricas mais críticas, incluindo chamadas de modelos, uso de tokens e execução de ferramentas.
1. **Configurar para o estágio de desenvolvimento** - Adapte sua configuração de observabilidade para corresponder à sua fase atual de desenvolvimento e ajuste-a progressivamente.
1. **Use nomenclatura consistente** - Estabeleça convenções de nomenclatura para serviços, extensões e atributos desde o início
1. **Filtre dados confidenciais** - evite a exposição de informações confidenciais filtrando dados confidenciais de atributos de observabilidade e cargas úteis.
1. **Configurar alertas** - Configure CloudWatch alarmes para notificá-lo sobre possíveis problemas antes que eles afetem os usuários