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.

Ajoutez de l'observabilité à vos ressources Amazon Bedrock AgentCore

Amazon Bedrock AgentCore fournit un certain nombre de mesures intégrées pour surveiller les performances des ressources pour les types de ressources AgentCore d'exécution, de mémoire, de passerelle, d'outils intégrés et d'identité. Ces données par défaut sont disponibles sur Amazon CloudWatch. Pour afficher la gamme complète des données d'observabilité dans la CloudWatch console ou pour générer des mesures d'exécution personnalisées pour les agents, vous devez instrumenter votre code à l'aide du SDK AWS Distro for Open Telemetry (ADOT).

Pour afficher le tableau de bord d'observabilité dans CloudWatch, ouvrez la page Amazon CloudWatch GenAi Observability.

Consultez les sections suivantes pour en savoir plus sur la configuration de vos ressources afin d'afficher les mesures d'observabilité sur la page d'observabilité de l'IA générée par la CloudWatch console et dans CloudWatch les journaux.

Favoriser l' AgentCore observabilité

Pour consulter les statistiques, les intervalles et les traces générés par le AgentCore service, vous devez d'abord effectuer une configuration unique pour activer Amazon CloudWatch Transaction Search. Pour afficher les intervalles de ressources mémoire fournis par le service, vous devez également activer le suivi lorsque vous créez une mémoire. Consultez la section Activation de l'observabilité pour l' AgentCore exécution, la mémoire, la passerelle, les outils intégrés et les ressources d'identité pour en savoir plus.

Les sections suivantes décrivent comment effectuer ces actions de configuration et activer l'observabilité dans le code de votre agent.

Activation de CloudWatch la recherche de transactions

Vous pouvez activer la recherche de CloudWatch transactions soit à l'aide de la CloudWatch console, soit à l'aide d'une API via l'interface de ligne de AWS commande (AWS CLI) ou l'un des AWS kits de développement logiciel.

Utilisez l'une des procédures suivantes pour activer la recherche de transactions.

Destination Span pour les agents hébergés dans l'environnement d'exécution Amazon Bedrock AgentCore

Grâce à AgentCore Runtime, une fonctionnalité d'Amazon Bedrock AgentCore, vous pouvez configurer un agent pour qu'il transmette ses spans au même groupe de CloudWatch journaux Amazon que les journaux de l'agent. Avec cette configuration, les spans vont au flux de spans journaux dans/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>, au lieu du groupe de aws/spans journaux partagé. Vous pouvez regrouper les spans, les journaux structurés et les sorties standard dans un groupe de journaux par agent, étendre le contrôle d'accès et le chiffrement à un agent individuel et exporter des données télémétriques depuis un emplacement unique.

Dans AWS les régions prises en charge, les agents nouvellement créés utilisent le groupe de journaux de l'agent comme destination de span par défaut. Les agents créés avant qu'une région ne prenne en charge la destination de span unifiée conservent le groupe de aws/spans journaux partagé par défaut.

Vous pouvez remplacer la valeur par défaut pour un agent individuel avec la variable d'environnement sur l'UNIFIED_TRACES_DESTINATION_ENABLEDenvironnement d'exécution de votre agent :

AgentCore Pour fournir des spans au groupe de journaux de l'agent, les conditions suivantes doivent être vraies :

La modification de la destination de la travée ne déplace pas les données de travée existantes. Les spans AgentCore déjà livrées restent dans leur groupe de log d'origine.

Activation de l'observabilité dans le code de l'agent pour les AgentCore-hosted agents

Outre les métriques générées par les services, AgentCore vous pouvez également collecter des données de span et de trace ainsi que des métriques personnalisées émises par le code de votre agent.

Lorsque vous utilisez des frameworks d'agents tels que https://strandsagents.com/latest/ Strands LangChain ou CrewAI avec des bibliothèques d'instrumentation tierces prises en charge, le framework lui-même est doté d'un support intégré pour les conventions sémantiques OTEL et GenAI, et il peut également être instrumenté à l'aide d'un package d'auto-instrumentation tel que. opentelemetry-instrument-langchain Il est également possible d'envoyer des conventions sémantiques Generative AI, de la télémétrie et des spans en définissant un traceur personnalisé. AgentCore prend en charge l'utilisation des bibliothèques d'instrumentation suivantes dans votre infrastructure d'agents :

Pour afficher ces données sur la page d'observabilité de l'IA générative de la CloudWatch console et sur Amazon CloudWatch, vous devez ajouter le SDK AWS Distro for Open Telemetry (ADOT) à votre code d'agent.

Pour ajouter le support ADOT et activer l' AgentCore observabilité, suivez les étapes de la procédure suivante.

Ajoutez de l'observabilité à votre agent AgentCore

Permettre l'observabilité pour les agents hébergés en dehors de AgentCore

Pour activer l'observabilité pour les agents hébergés en dehors de l' AgentCore environnement d'exécution, suivez d'abord les étapes décrites dans les sections précédentes pour activer la recherche de CloudWatch transactions et ajouter le SDK ADOT à votre code.

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.

Pour les agents qui s'exécutent en dehors de l' AgentCore environnement d'exécution, vous devez également créer un groupe de journaux d'agents que vous incluez dans vos variables d'environnement.

Configurez vos variables d' AWS environnement, puis définissez vos variables d'environnement Open Telemetry comme indiqué ci-dessous.

AWS variables d'environnement

AWS_ACCOUNT_ID=<account id>
AWS_DEFAULT_REGION=<default region>
AWS_REGION=<region>
AWS_ACCESS_KEY_ID=<access key id>
AWS_SECRET_ACCESS_KEY=<secret key>

Variables d'environnement OTEL

AGENT_OBSERVABILITY_ENABLED=true
AWS_GENAI_CONTENT_EXTRACTION_OPT_OUT=true # Keeps model payloads and tool request/response data on spans. Requires ADOT >=0.18.0.
OTEL_PYTHON_DISTRO=aws_distro
OTEL_PYTHON_CONFIGURATOR=aws_configurator # required for ADOT Python only
OTEL_RESOURCE_ATTRIBUTES=service.name=<agent-name>,aws.log.group.names=/aws/bedrock-agentcore/runtimes/<agent-id>,cloud.resource_id=<AgentEndpointArn:AgentEndpointName> # endpoint is optional
OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=/aws/bedrock-agentcore/runtimes/<agent-id>,x-aws-log-stream=runtime-logs,x-aws-metric-namespace=bedrock-agentcore
OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-aws-log-group=/aws/bedrock-agentcore/runtimes/<agent-id>,x-aws-log-stream=spans # (Optional) Directs spans to your log group instead of the aws/spans log group. Requires ADOT version 0.18.0 or later.
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_TRACES_EXPORTER=otlp
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false # AWS Lambda Layer for OpenTelemetry only: disables Application Signals
OTEL_LOGS_EXPORTER=otlp # AWS Lambda Layer for OpenTelemetry only: exports logs over OTLP
OTEL_METRICS_EXPORTER=awsemf # AWS Lambda Layer for OpenTelemetry only: exports metrics as CloudWatch EMF

<agent-name>Remplacez-le par le nom de votre agent et <agent-id> par un identifiant unique pour votre agent.

Prise en charge des identifiants de session

Pour propager l'identifiant de session, vous devez l'invoquer en utilisant l'identifiant de session figurant dans les bagages OTEL :

from opentelemetry import baggage

ctx = baggage.set_baggage("session.id", session_id) # Set the session.id in baggage
attach(ctx) # Attach the context to make it active token

Permettre l'observabilité de l' AgentCore exécution, de la mémoire, de la passerelle, des outils intégrés et des ressources d'identité

Lorsque vous créez une ressource AgentCore d'exécution (agent), le AgentCore moteur d'exécution crée par défaut un groupe de CloudWatch journaux pour les journaux fournis par le service. Toutefois, en ce qui concerne la mémoire, la passerelle et les ressources d'outils intégrées, AgentCore ne configure pas automatiquement les destinations des journaux pour vous.

Pour les ressources de mémoire et de passerelle, vous pouvez configurer les destinations des journaux dans la console ou à l'aide d'un AWS SDK. Si vous utilisez la console pour configurer une destination de CloudWatch journaux, le nom de groupe de journaux par défaut pour les ressources de mémoire et de passerelle est de la forme/aws/vendedlogs/bedrock-agentcore/{resource-type}/APPLICATION_LOGS/{resource-id}, où {resource-type} est memory ougateway.

Pour les journaux de mémoire et de passerelle, vous pouvez également configurer les destinations des journaux dans les journaux Amazon S3 ou les journaux de flux Firehose à l'aide de la AgentCore console. Pour en savoir plus sur le stockage des journaux dans Amazon S3 ou Firehose, consultez Chargement, téléchargement et utilisation d'objets dans Amazon S3 et Création d'un flux de diffusion Amazon Data Firehose.

Pour en savoir plus sur les données de journal produites par AgentCore les ressources de mémoire et de passerelle, voir Données de journal fournies (mémoire) ou Données de journal fournies (passerelle).

Pour les ressources d'outils intégrées, le AgentCore service ne fournit pas de journaux par défaut, mais vous pouvez générer vos propres journaux à partir de votre code. Si vous fournissez vos propres sorties de journal, vous devez configurer manuellement les destinations des journaux pour stocker ces données.

Pour voir ce que les données d'observabilité AgentCore fournissent par défaut pour chaque type de ressource, consultez les données d'observabilité AgentCore générées par Amazon Bedrock.

Configurer les destinations des journaux à l'aide de la console

Pour configurer les destinations des journaux de la mémoire ou des journaux de passerelle dans la AgentCore console, utilisez les procédures suivantes.

Configurer la diffusion du suivi à CloudWatch l'aide de la console

Cette section explique comment activer la livraison de traces CloudWatch pour suivre le flux d'interactions via votre application, ce qui vous permet de visualiser les demandes, d'identifier les goulots d'étranglement en matière de performances, de résoudre les erreurs et d'optimiser les performances.

Configurer les CloudWatch ressources à l'aide d'un AWS Kit SDK

Pour configurer une source de diffusion pour les journaux et les traces (SDK)

import boto3

def enable_observability_for_resource(resource_arn, resource_id, account_id, region='us-east-1'):
    """
    Enable observability for a Bedrock AgentCore resource (e.g., Memory Store)
    """
    logs_client = boto3.client('logs', region_name=region)

    # Step 0: Create new log group for vended log delivery
    log_group_name = f'/aws/vendedlogs/bedrock-agentcore/{resource_id}'
    logs_client.create_log_group(logGroupName=log_group_name)
    log_group_arn = f'arn:aws:logs:{region}:{account_id}:log-group:{log_group_name}'

    # Step 1: Create delivery source for logs
    logs_source_response = logs_client.put_delivery_source(
        name=f"{resource_id}-logs-source",
        logType="APPLICATION_LOGS",
        resourceArn=resource_arn
    )

    # Step 2: Create delivery source for traces
    traces_source_response = logs_client.put_delivery_source(
        name=f"{resource_id}-traces-source",
        logType="TRACES",
        resourceArn=resource_arn
    )

    # Step 3: Create delivery destinations
    logs_destination_response = logs_client.put_delivery_destination(
        name=f"{resource_id}-logs-destination",
        deliveryDestinationType='CWL',
        deliveryDestinationConfiguration={
            'destinationResourceArn': log_group_arn,
        }
    )

    # Traces required
    traces_destination_response = logs_client.put_delivery_destination(
        name=f"{resource_id}-traces-destination",
        deliveryDestinationType='XRAY'
    )

    # Step 4: Create deliveries (connect sources to destinations)
    logs_delivery = logs_client.create_delivery(
        deliverySourceName=logs_source_response['deliverySource']['name'],
        deliveryDestinationArn=logs_destination_response['deliveryDestination']['arn']
    )

    # Traces required
    traces_delivery = logs_client.create_delivery(
        deliverySourceName=traces_source_response['deliverySource']['name'],
        deliveryDestinationArn=traces_destination_response['deliveryDestination']['arn']
    )

    print(f"Observability enabled for {resource_id}")
    return {
        'logs_delivery_id': logs_delivery['id'],
        'traces_delivery_id': traces_delivery['id']
    }

# Usage example
resource_arn = "arn:aws:bedrock-agentcore:us-east-1:123456789012:memory/my-memory-id"
resource_id = "my-memory-id"
account_id = "123456789012"

delivery_ids = enable_observability_for_resource(resource_arn, resource_id, account_id)

Observabilité AgentCore d'exécution améliorée grâce à des en-têtes personnalisés

Vous pouvez appeler votre agent avec des en-têtes HTTP supplémentaires pour fournir des options d'observabilité améliorées. L'exemple suivant montre les invocations, y compris les demandes d'en-tête supplémentaires facultatives pour les agents hébergés dans l' AgentCore environnement d'exécution.

Exemple d'invocation de Boto3

def invoke_agent(agent_id, payload, session_id=None):
    client = boto3.client("bedrock-agentcore", region="us-west-2")
    response = client.invoke_agent_runtime(
        agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/test_agent_boto2-nIg2xk3VSR",
        runtimeSessionId="12345678-1234-5678-9abc-123456789012",
        payload='{"query": "Plan a weekend in Seattle"}',
    )

Vous pouvez inclure les en-têtes facultatifs suivants lorsque vous invoquez votre agent afin d'améliorer les fonctionnalités d'observabilité et de suivi :

Observabilité améliorée des outils AgentCore intégrés avec des en-têtes personnalisés

Vous pouvez invoquer vos Built-in outils avec des en-têtes HTTP supplémentaires pour fournir des options d'observabilité améliorées. Vous pouvez inclure les en-têtes facultatifs suivants lors de l'intégration des API Build-in Tools suivantes afin d'améliorer l'observabilité et les fonctionnalités de suivi :

Les API suivantes prennent en charge les en-têtes personnalisés :

Observabilité des AgentCore identités améliorée grâce à des en-têtes personnalisés

Vous pouvez invoquer vos ressources d'identité avec des en-têtes HTTP supplémentaires pour fournir des options d'observabilité améliorées. Vous pouvez inclure les en-têtes facultatifs suivants lors de l'intégration des API d'identité suivantes afin d'améliorer l'observabilité et les fonctionnalités de suivi :

Les API suivantes prennent en charge les en-têtes personnalisés :

Meilleures pratiques en matière d'observabilité

Prenez en compte les bonnes pratiques suivantes lors de la mise en œuvre de l'observabilité pour les agents dans AgentCore :

Utilisation d'autres plateformes d'observabilité

Pour intégrer les agents hébergés dans l' AgentCore environnement d'exécution à d'autres plateformes d'observabilité afin de capturer et d'afficher les sorties de télémétrie, définissez la variable d'environnement suivante :

DISABLE_ADOT_OBSERVABILITY=true

La définition de cette variable pour true annuler les variables d'environnement ADOT par défaut de l'environnement AgentCore d'exécution, garantissant ainsi qu'aucune des configurations ADOT par défaut n'est définie.