Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Comience con AgentCore Observability

Amazon Bedrock AgentCore Observability le ayuda a rastrear, depurar y supervisar el rendimiento de los agentes en los 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 la supervisión 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 maneras de hacerlo, a través de la API y a través de la CloudWatch consola.

Paso 1: Activa 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: habilita 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: Habilite la observabilidad para los agentes alojados en Amazon Bedrock Runtime AgentCore

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 motor de ejecución instrumenta automáticamente a su agente, sin necesidad OpenTelemetry de bibliotecas ni configuraciones adicionales de OTEL.

Para ver un ejemplo completo, consulte los ejemplos de AgentCore observabilidad en GitHub

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 \
  --project-name StrandsObservability \
  --name StrandsClaudeGettingStarted \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none
cd StrandsObservability/app/StrandsClaudeGettingStarted
uv add strands-agents-tools
cd ../..

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 en el que se utiliza el 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")
    if not isinstance(user_input, str) or not user_input:
        return "Error: 'prompt' must be a non-empty string"
    response = agent(user_input)
    return response.message['content'][0]['text']

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

Despliegue e invoque a su agente

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

agentcore deploy

Tras la implementación, su agente se ejecuta en AgentCore Runtime y se instrumenta automáticamente mediante. OpenTelemetry Invoca a tu agente y consulta los seguimientos, las sesiones y las métricas en el panel de control de GenAI Observability de 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: Habilite la observabilidad para los agentes que no sean de Amazon Bedrock AgentCore-hosted

En el caso de los agentes que trabajan 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 de dónde se ejecuten los agentes. Siga los pasos siguientes para configurar las variables de entorno necesarias para observar a sus agentes.

Para ver un ejemplo completo, consulte el ejemplo de Agents on Amazon EKS 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 una secuencia 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 a 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

aws-opentelemetry-distroEn su 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 en el sitio web OpenTelemetry AWS Distro for. OpenTelemetry Agregue la capa a su función y, a continuación, defina la variable de AWS_LAMBDA_EXEC_WRAPPER entorno en. /opt/otel-instrument A continuación, la capa instrumenta automáticamente la función. Con este enfoque, no es necesario añadir el aws-opentelemetry-distro paquete ni ejecutar el opentelemetry-instrument comando descrito anteriormente.

Ahora puede ver sus rastreos, sesiones y métricas en el panel de observación de GenAI en Amazon CloudWatch con el valor YOUR-AGENT-NAME que configuró en las variables de su entorno. Configure las variables de OpenTelemetry entorno

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

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

Paso 4: Observa a tu agente con la capacidad de observación de GenAI en Amazon CloudWatch

Tras implementar la observabilidad, puede ver los datos recopilados en: CloudWatch

Observe a su agente

Ver los registros ingresados CloudWatch

Para ver los inicios de sesión CloudWatch

Visualización de rastros e intervalos de tiempo

Para ver trazas y tramos

Ver las métricas de

Para ver las métricas

Prácticas recomendadas