Comience con la AgentCore observabilidad

Amazon Bedrock Amazon Bedrock AgentCore Observability le ayuda a rastrear, depurar y supervisar el rendimiento de los agentes en entornos de producción. Esta guía le ayuda a implementar funciones de observabilidad en las aplicaciones de sus agentes.

Requisitos previos

Antes de empezar, asegúrese de tener:

Amazon Bedrock AgentCore Observability ofrece dos formas de configurar el monitoreo para que se adapte a las diferentes necesidades de infraestructura:

Como se configura una sola vez por AWS cuenta, los usuarios primerizos deben habilitar la búsqueda de transacciones en Amazon CloudWatch. Hay dos formas de hacerlo, a través de la API y a través de la CloudWatch consola.

Paso 1: Habilita la búsqueda de transacciones en CloudWatch

Tras activar Transaction Search, las unidades de seguimiento pueden tardar diez minutos en estar disponibles para su búsqueda y análisis. Elige una de las siguientes opciones:

Opción 1: habilitar la búsqueda de transacciones mediante una API

Para habilitar la búsqueda de transacciones mediante la API

Opción 2: Habilite la búsqueda de transacciones en la CloudWatch consola

Para habilitar la búsqueda de transacciones en la CloudWatch consola

Pasemos ahora a explorar las dos formas de configurar la observabilidad.

Paso 2: Habilitar la observabilidad para los agentes alojados en Amazon Bedrock AgentCore Runtime

AgentCore Runtime-hosted Los agentes de Amazon Bedrock se implementan y ejecutan directamente en el AgentCore entorno de Amazon Bedrock, lo que proporciona una instrumentación automática con una configuración mínima. Cuando implementa un agente mediante la AgentCore CLI, el tiempo de ejecución instrumenta automáticamente a su agente OpenTelemetry ; no se necesitan bibliotecas ni configuraciones de OTEL adicionales.

Para ver un ejemplo completo, consulte este cuaderno

Crea tu proyecto de agente

Cree un nuevo proyecto mediante la AgentCore CLI. Esto configura la carpeta del proyecto, el entorno virtual y las dependencias:

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

En el directorio de agentes del proyecto, sustituya el código de agente predeterminado por su propia lógica de agente. El siguiente es un ejemplo del uso del SDK de 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()

Despliegue e invoque a su agente

Despliegue el agente en AgentCore Runtime. La AgentCore CLI gestiona el empaquetado, el despliegue y la instrumentación automática de OTEL:

cd StrandsClaudeGettingStarted
agentcore deploy

Tras la implementación, su agente se ejecuta en AgentCore Runtime y se instrumenta automáticamente mediante. OpenTelemetry Llama a tu agente y consulta los seguimientos, las sesiones y las métricas en el panel de observabilidad de GenAI en Amazon: CloudWatch

agentcore invoke

Como alternativa, puedes invocar a tu agente mediante programación mediante el 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()))

Paso 3: Habilitar la observabilidad para agentes ajenos a Amazon Bedrock AgentCore-hosted

Para los agentes que se ejecutan fuera del entorno de AgentCore ejecución de Amazon Bedrock, puede ofrecer las mismas capacidades de supervisión a los agentes desplegados en su propia infraestructura. Esto permite una observabilidad uniforme, independientemente del lugar en el que trabajen sus agentes. Siga los siguientes pasos para configurar las variables de entorno necesarias para observar a sus agentes.

Para ver un ejemplo completo, consulta el ejemplo EKS de Agents on Amazon en el GitHub sitio web.

Configuración AWS variables de entorno

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>

Configure el CloudWatch registro

Cree un grupo de registros y un flujo de registros para su agente en Amazon CloudWatch que pueda usar para configurar las siguientes variables de entorno.

Configure las variables de OpenTelemetry entorno

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>Sustitúyalo por un nombre único para identificar este agente en el panel y los registros de GenAI Observability.

Crea un agente de forma local

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

Ejecute su agente con un comando de instrumentación automático

Con aws-opentelemetry-distro tu archivo requirements.txt, el opentelemetry-instrument comando hará lo siguiente:

Utilice el siguiente comando para ejecutar su agente con instrumentación automática:

opentelemetry-instrument python agent.py

Si aloja su agente en AWS Lambda, utilice la capa AWS Lambda para OpenTelemetry en el AWS sitio web Distro for. OpenTelemetry Añada la capa a su función y, a continuación, defina la variable de AWS_LAMBDA_EXEC_WRAPPER entorno en. /opt/otel-instrument Luego, la capa instrumenta automáticamente tu función. Con este enfoque, no es necesario añadir el aws-opentelemetry-distro paquete ni ejecutar el opentelemetry-instrument comando descrito anteriormente.

Ahora puedes ver tus seguimientos, sesiones y métricas en el panel de observabilidad de GenAI en Amazon CloudWatch con el valor YOUR-AGENT-NAMEque configuraste en tus variables de entorno.

Para correlacionar los seguimientos entre varios agentes, puedes asociar un identificador de sesión a tus datos de telemetría utilizando el equipaje: OpenTelemetry

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

Paso 4: Observe a su agente con la observabilidad GenAI en Amazon CloudWatch

Después de implementar la observabilidad, puede ver los datos recopilados en: CloudWatch

Observe a su agente

Ver los registros CloudWatch

Para ver los registros iniciados CloudWatch

Visualización de rastros e intervalos de tiempo

Para ver trazas y vanos

Ver las métricas de

Para ver las métricas

Prácticas recomendadas