# Commencez avec AgentCore Observability Amazon Bedrock 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. **Topics** + [Conditions préalables](#prerequisites) + [Étape 1 : Activez la recherche de transactions sur CloudWatch](#enabling-transaction-search) + [Étape 2 : activer l'observabilité pour les agents hébergés par Amazon Bedrock AgentCore Runtime](#enabling-observability-runtime-hosted) + [Étape 3 : activer l'observabilité pour les agents autres qu'Amazon Bedrock AgentCore-hosted](#enabling-observability-non-runtime-hosted) + [Étape 4 : observez votre agent grâce à l'observabilité de GenAI sur Amazon CloudWatch](#agentcore-observability-genai-cloudwatch) + [Bonnes pratiques](#best-practices) ## Conditions préalables Avant de commencer, assurez-vous d'avoir : + ** AWS Compte** avec informations d'identification configurées (`aws configure`) avec accès au modèle activé pour le modèle de base que vous souhaitez utiliser. + **Python 3.10\+ installé** + **Activez la recherche de transactions** sur Amazon CloudWatch. Une seule fois, les nouveaux utilisateurs doivent activer [CloudWatch Transaction Search](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Enable-TransactionSearch.html) pour voir les travées et les traces de Bedrock Amazon Bedrock AgentCore + **(Non-runtime agents uniquement) Ajoutez la OpenTelemetry bibliothèque** : incluez `aws-opentelemetry-distro` (ADOT) dans votre fichier requirements.txt. Si vous hébergez votre agent sur AWS Lambda, utilisez plutôt la [couche AWS Lambda pour OpenTelemetry le site](https://aws-otel.github.io/docs/getting-started/lambda) Web de AWS distribution. OpenTelemetry + **(Non-runtime agents uniquement)** Assurez-vous que votre infrastructure est configurée pour émettre des traces (par exemple, un `strands-agents[otel]` package). Il se peut que vous deviez parfois inclure l'instrument automatique de votre framework d'agents (par exemple,`opentelemetry-instrumentation-langchain`). Amazon Bedrock AgentCore Observability propose deux méthodes pour configurer la surveillance en fonction des différents besoins d'infrastructure : 1. Agents Amazon Bedrock AgentCore Runtime-hosted 1. Non-runtime agents hébergés Dans le cadre d'une configuration unique par AWS compte, les nouveaux utilisateurs doivent activer Transaction Search sur Amazon CloudWatch. Il existe deux manières de procéder, 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** 1. Créez une politique qui accorde l'accès aux intervalles d'ingestion dans les CloudWatch journaux à l'aide de la CLI AWS . Vous trouverez ci-dessous un exemple de mise en forme de votre commande AWS CLI avec`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. Configurez la destination des segments de trace. Vous trouverez ci-dessous un exemple de mise en forme de votre commande AWS CLI avec`UpdateTraceSegmentDestination`. ``` aws xray update-trace-segment-destination --destination CloudWatchLogs ``` 1. **Facultatif** : configurez le nombre de plages à indexer. Configurez le pourcentage d'échantillonnage souhaité avec`UpdateIndexingRule`. ``` aws xray update-indexing-rule --name "Default" --rule '{"Probabilistic": {"DesiredSamplingPercentage": number}}' ``` ### Option 2 : activer la recherche de transactions dans la CloudWatch console **Pour activer la recherche de transactions dans la CloudWatch console** 1. Ouvrez la CloudWatch console à l'adresse [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Dans le volet de navigation, sous **Configuration**, sélectionnez **Paramètres**. 1. Sélectionnez **Compte**, puis choisissez l'onglet **X-Ray Traces**. 1. Dans la section **Recherche de transactions**, choisissez **Afficher les paramètres**. 1. Sur la page qui s'ouvre, choisissez **Modifier**. 1. Sélectionnez **Activer la recherche de transactions**. 1. Sélectionnez **Pour X-Ray les utilisateurs** et entrez le pourcentage de traces à indexer. Vous pouvez indexer 1 % des traces gratuitement et ajuster ce pourcentage ultérieurement en fonction de vos besoins. 1. Choisissez **Enregistrer**. Attendez que le **délai d'ingestion OpenTelemetry indique** **Activé** avant d'envoyer des traces. Passons maintenant à l'exploration des deux manières de configurer l'observabilité. ## Étape 2 : activer l'observabilité pour les agents hébergés par 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 la AgentCore CLI, le moteur d'exécution l'utilise automatiquement. Aucune bibliothèque ou configuration OTEL supplémentaire n'est nécessaire. OpenTelemetry Pour un exemple complet, reportez-vous à ce [bloc-notes](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) ### Créez votre projet d'agent Créez un nouveau projet à l'aide de la AgentCore CLI. Cela permet de configurer le dossier de votre projet, votre environnement virtuel et vos dépendances : ``` npm install -g @aws/agentcore agentcore create --name StrandsClaudeGettingStarted ``` 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 d'utilisation du 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") response = agent(user_input) return response.message['content'][0]['text'] if __name__ == "__main__": app.run() ``` ### Déployez et appelez votre agent Déployez l'agent sur AgentCore Runtime. La AgentCore CLI gère le packaging, le déploiement et l'instrumentation automatique de l'OTEL : ``` cd StrandsClaudeGettingStarted 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 statistiques sur le tableau de bord GenAI Observability sur Amazon : CloudWatch ``` agentcore invoke ``` Vous pouvez également appeler votre agent par programmation à l'aide du AWS SDK : ``` 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 autres qu'Amazon Bedrock AgentCore-hosted Pour les agents exécutés en dehors de l' AgentCore environnement d'exécution Amazon Bedrock, vous pouvez proposer 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ù travaillent vos agents. Procédez comme suit pour configurer les variables d'environnement nécessaires à l'observation de vos agents. Pour un exemple complet, consultez l'exemple [Agents on Amazon EKS disponible](https://github.com/awslabs/agentcore-samples/tree/main/03-integrations/agents-hosted-outside-runtime/agents-on-eks) sur le GitHub site Web. ### Configurer AWS variables d’environnement ``` export AWS_ACCOUNT_ID= export AWS_DEFAULT_REGION= export AWS_REGION= export AWS_ACCESS_KEY_ID= export AWS_SECRET_ACCESS_KEY= ``` ### Configuration de la CloudWatch journalisation Créez un groupe de journaux et un flux de journaux pour votre agent sur Amazon CloudWatch , que vous pouvez 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=,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 ``` {{}}Remplacez-le par un nom unique pour identifier cet agent dans le tableau de bord et les journaux de GenAI Observability. **Note** Si vous configurez `OTEL_EXPORTER_OTLP_TRACES_HEADERS` l'attribution de spans à votre propre groupe de journaux, vous devez également ajouter une politique de ressources Amazon CloudWatch Logs. La politique doit autoriser X-Ray (`xray.amazonaws.com`) à appeler `logs:PutLogEvents` ce groupe de journaux. Utilisez la même politique que celle indiquée dans [Activer la recherche de transactions à l'aide d'une API](#enable-transaction-search-api), en insérant l'ARN de votre groupe de journaux`Resource`. Sans cette politique, X-Ray vous ne pouvez pas fournir de spans à votre groupe de logs. ### Création d'un agent en 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) ``` ### Exécutez votre agent avec une commande d'instrumentation automatique `aws-opentelemetry-distro`Dans votre fichier requirements.txt, la `opentelemetry-instrument` commande va : + Chargez votre configuration OTEL à partir de vos variables d'environnement + Instrumentez automatiquement les Strands, les appels Amazon Bedrock, les outils et bases de données des agents, ainsi que les autres demandes effectuées par l'agent + Envoyer des traces à CloudWatch + Vous permettre de visualiser le processus décisionnel de l'agent dans le tableau de bord GenAI Observability 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](https://aws-otel.github.io/docs/getting-started/lambda) le AWS site Web de OpenTelemetry distribution. OpenTelemetry Ajoutez la couche à votre fonction, puis définissez la variable d'`AWS_LAMBDA_EXEC_WRAPPER`environnement sur`/opt/otel-instrument`. La couche régule ensuite automatiquement votre fonction. Avec cette approche, il n'est pas nécessaire d'ajouter le `aws-opentelemetry-distro` package ou d'exécuter la `opentelemetry-instrument` commande décrite précédemment. **Le collecteur ADOT n'est pas pris en charge pour l'observabilité des agents** Le collecteur ADOT n'est pas pris en charge pour l'observabilité des agents. Pour envoyer de la télémétrie depuis un agent hébergé en dehors de l' AgentCore environnement d'exécution, vous devez utiliser le SDK ADOT ou la couche Lambda AWS pour. OpenTelemetry 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](#configure-opentelemetry-environment-variables). Pour corréler les traces entre plusieurs exécutions d'agents, vous pouvez associer un identifiant de session à vos données de télémétrie à l'aide de bagages : OpenTelemetry ``` from opentelemetry import baggage, context ctx = baggage.set_baggage("session.id", session_id) ``` ## Étape 4 : observez votre agent grâce à l'observabilité de GenAI sur Amazon CloudWatch Après avoir implémenté l'observabilité, vous pouvez consulter les données collectées dans CloudWatch : ### Observez votre agent 1. Ouvrez l'[observabilité GenAI](https://console.aws.amazon.com/cloudwatch/home#gen-ai-observability) sur console CloudWatch 1. Vous pouvez consulter les données relatives aux invocations de modèles et aux agents sur Bedrock Amazon AgentCore Bedrock sur le tableau de bord. 1. Dans l'onglet Bedrock Agentcore, vous pouvez afficher la vue des agents, la vue des sessions et la vue des traces. 1. Agents View répertorie tous vos agents actifs ou non en cours d'exécution. Vous pouvez également choisir un agent et consulter des informations supplémentaires, telles que les métriques d'exécution, les sessions et les traces spécifiques à un agent. 1. Dans l'onglet **Affichage des sessions**, vous pouvez parcourir toutes les sessions associées aux agents. 1. Dans l'onglet **Trace View**, vous pouvez consulter les informations relatives aux traces et à l'intervalle pour les agents. Explorez également la trajectoire et la chronologie du tracé en choisissant un tracé. ### Afficher les connexions CloudWatch **Pour afficher les connexions CloudWatch** 1. Ouvrez la [console CloudWatch ](https://console.aws.amazon.com/cloudwatch/). 1. Dans le volet de navigation de gauche, développez **Logs** et sélectionnez **Log groups** 1. Recherchez le groupe de log de votre agent : + Logs standard (stdout/stderr) Emplacement : `/aws/bedrock-agentcore/runtimes/-/[runtime-logs] ` + Logos structurés OTEL : `/aws/bedrock-agentcore/runtimes/-/runtime-logs` ### Afficher les traces et les travées **Pour afficher les traces et les travées** 1. Ouvrez la [console CloudWatch ](https://console.aws.amazon.com/cloudwatch/). 1. Sélectionnez **Recherche de transactions dans** la barre de navigation de gauche 1. Emplacement : le flux de `spans` journaux dans le groupe de journaux de l'agent (`/aws/bedrock-agentcore/runtimes/-`), ou le flux de `default` journaux dans le groupe de `aws/spans` journaux pour les agents qui utilisent la destination d'intervalle partagée 1. Filtrer par nom de service ou par d'autres critères 1. Sélectionnez une trace pour afficher le graphique d'exécution détaillé ### Affichage des métriques **Pour consulter les métriques** 1. Ouvrez la [console CloudWatch ](https://console.aws.amazon.com/cloudwatch/). 1. Sélectionnez **Metrics** dans le menu de navigation de gauche 1. Accédez à l'espace de `bedrock-agentcore` noms 1. Explorez les indicateurs disponibles ## Bonnes pratiques 1. **Commencez simplement, puis développez** : l'observabilité par défaut fournie par Amazon Bedrock AgentCore capture automatiquement les indicateurs les plus critiques, notamment les appels de modèles, l'utilisation des jetons et l'exécution des outils. 1. **Configuration pour la phase de développement** : adaptez votre configuration d'observabilité à votre phase de développement actuelle et ajustez-la progressivement. 1. **Utiliser une dénomination cohérente** : établissez des conventions de dénomination pour les services, les étendues et les attributs dès le départ 1. **Filtrer les données sensibles** - Empêchez l'exposition d'informations confidentielles en filtrant les données sensibles des attributs d'observabilité et des charges utiles. 1. **Configurer des alertes** - Configurez des CloudWatch alarmes pour vous informer des problèmes potentiels avant qu'ils n'affectent les utilisateurs