Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Commencez avec AgentCore Observability

Amazon Bedrock AgentCore Observability vous permet de suivre, de déboguer et de surveiller les performances des agents dans les environnements de production. Ce guide vous aide à implémenter des fonctionnalités d'observabilité dans vos applications d'agent.

Conditions préalables

Avant de commencer, assurez-vous d'avoir :

Amazon Bedrock AgentCore Observability propose deux méthodes pour configurer la surveillance afin de répondre aux différents besoins d'infrastructure :

Dans le cadre d'une configuration unique par AWS compte, les nouveaux utilisateurs doivent activer la recherche de transactions sur Amazon CloudWatch. Vous pouvez le faire de deux manières, via l'API et via la CloudWatch console.

Étape 1 : Activez la recherche de transactions sur CloudWatch

Une fois la recherche de transactions activée, il faut compter dix minutes pour que les portées soient disponibles pour la recherche et l’analyse. Choisissez l'une des options ci-dessous :

Option 1 : activer la recherche de transactions à l'aide d'une API

Pour activer la recherche de transactions à l'aide de l'API

Option 2 : activer la recherche de transactions dans la CloudWatch console

Pour activer la recherche de transactions dans la CloudWatch console

Passons maintenant à l'exploration des deux manières de configurer l'observabilité.

Étape 2 : activer l'observabilité pour les agents hébergés sur Amazon Bedrock AgentCore Runtime

Les AgentCore Runtime-hosted agents Amazon Bedrock sont déployés et exécutés directement dans l' AgentCore environnement Amazon Bedrock, fournissant une instrumentation automatique avec une configuration minimale. Lorsque vous déployez un agent à l'aide de l' AgentCore interface de ligne de commande, le moteur d'exécution instrumente automatiquement votre agent. Aucune bibliothèque ou configuration OTEL supplémentaire n'est nécessaire. OpenTelemetry

Pour un exemple complet, reportez-vous aux exemples d'AgentCore observabilité sur GitHub

Créez votre projet d'agent

Créez un nouveau projet à l'aide de la AgentCore CLI. Cela configure le dossier de votre projet, votre environnement virtuel et vos dépendances :

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 ../..

Dans le répertoire des agents du projet, remplacez le code d'agent par défaut par votre propre logique d'agent. Voici un exemple utilisant le SDK 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()

Déployez et invoquez votre agent

Déployez l'agent sur AgentCore Runtime. La AgentCore CLI gère le packaging, le déploiement et l'instrumentation OTEL automatique :

agentcore deploy

Après le déploiement, votre agent s'exécute sur AgentCore Runtime et est automatiquement instrumenté à l'aide OpenTelemetry de. Appelez votre agent et consultez les traces, les sessions et les mesures sur le tableau de bord GenAI Observability d'Amazon : CloudWatch

agentcore invoke

Vous pouvez également appeler votre agent par programmation à l'aide du 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()))

Étape 3 : activer l'observabilité pour les agents n'appartenant pas à Amazon Bedrock AgentCore-hosted

Pour les agents qui s'exécutent en dehors de l' AgentCore environnement d'exécution Amazon Bedrock, vous pouvez fournir les mêmes fonctionnalités de surveillance aux agents déployés sur votre propre infrastructure. Cela permet une observabilité constante quel que soit l'endroit où vos agents travaillent. Suivez les étapes ci-dessous pour configurer les variables d'environnement nécessaires à l'observation de vos agents.

Pour un exemple complet, consultez l'exemple Agents on Amazon EKS sur le GitHub site Web.

Configurer AWS variables d’environnement

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>

Configurer la CloudWatch journalisation

Créez un groupe de journaux et un flux de journaux pour votre agent dans Amazon CloudWatch , que vous pourrez utiliser pour configurer les variables d'environnement ci-dessous.

Configuration des variables d' OpenTelemetry environnement

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

Remplacez-le <YOUR-AGENT-NAME> par un nom unique pour identifier cet agent dans le tableau de bord et les journaux GenAI Observability.

Créez un agent localement

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

Exécutez votre agent avec une commande d'instrumentation automatique

aws-opentelemetry-distroDans votre fichier requirements.txt, la opentelemetry-instrument commande va :

Utilisez la commande suivante pour exécuter votre agent avec une instrumentation automatique :

opentelemetry-instrument python agent.py

Si vous hébergez votre agent sur AWS Lambda, utilisez la couche AWS Lambda pour OpenTelemetry sur le site Web AWS Distro for. OpenTelemetry Ajoutez la couche à votre fonction, puis définissez la variable d'AWS_LAMBDA_EXEC_WRAPPERenvironnement sur/opt/otel-instrument. La couche instrumente ensuite automatiquement votre fonction. Avec cette approche, vous n'avez pas besoin d'ajouter le aws-opentelemetry-distro package ou d'exécuter la opentelemetry-instrument commande décrite précédemment.

Vous pouvez désormais consulter vos traces, sessions et métriques sur le tableau de bord d'observabilité GenAI sur Amazon CloudWatch avec la valeur YOUR-AGENT-NAME que vous avez configurée dans vos variables d'environnement.

Pour corréler les traces entre plusieurs agents, vous pouvez associer un identifiant de session à vos données de télémétrie à l'aide des bagages : OpenTelemetry

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

Étape 4 : Observez votre agent grâce à l'observabilité GenAI sur Amazon CloudWatch

Après avoir implémenté l'observabilité, vous pouvez consulter les données collectées dans CloudWatch :

Observez votre agent

Afficher les connexions CloudWatch

Pour afficher les connexions CloudWatch

Afficher les traces et les étendues

Pour afficher les traces et les étendues

Affichage des métriques

Pour afficher les statistiques

Bonnes pratiques