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 AgentCore d'exécution, de mémoire, de passerelle, d'outils intégrés et de ressources d'identité. Ces données par défaut sont disponibles sur Amazon CloudWatch. Pour afficher l'ensemble des données d'observabilité dans la CloudWatch console ou pour générer des métriques d'exécution personnalisées pour les agents, vous devez instrumenter votre code à l'aide du SDK ADOT ( AWS Distro for Open Telemetry).

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 métriques d'observabilité sur la page d'observabilité de l'IA générative de la CloudWatch console et dans CloudWatch les journaux.

Permettre l' AgentCore observabilité

Pour consulter les métriques, 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 plages de ressources de mémoire fournies par le service, vous devez également activer le suivi lorsque vous créez une mémoire. Consultez Activer 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 comment 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 SDK.

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

Destination Span pour les agents hébergés dans Amazon Bedrock Runtime AgentCore

Avec le AgentCore runtime, une fonctionnalité d'Amazon Bedrock AgentCore, vous pouvez configurer un agent pour qu'il envoie ses spans au même groupe de CloudWatch journaux Amazon que les journaux de l'agent. Avec cette configuration, les spans sont dirigés vers le flux de spans journaux entrant/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>, plutôt que vers le groupe de aws/spans journaux partagé. Vous pouvez conserver les spans, les journaux structurés et les sorties standard dans un seul groupe de journaux par agent, étendre le contrôle d'accès et le chiffrement à un agent individuel et exporter la télémétrie à partir d'un seul emplacement.

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

Vous pouvez remplacer la valeur par défaut d'un agent individuel par la variable d'UNIFIED_TRACES_DESTINATION_ENABLEDenvironnement sur le runtime de votre agent :

AgentCore Pour que des intervalles soient fournis au groupe de journaux de l'agent, les conditions suivantes doivent être remplies :

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

Permettre l'observabilité dans le code des agents pour les AgentCore-hosted agents

Outre les métriques générées par le service, AgentCore vous pouvez également collecter des données de durée et de suivi ainsi que des métriques personnalisées émises à partir du code de votre agent.

Lorsque vous utilisez des frameworks d'agents tels que Strands LangChainou CrewAI avec des bibliothèques d'instrumentation tierces prises en charge, le framework lui-même intègre la prise en charge des conventions sémantiques OTEL et GenAI, et il peut également être instrumenté avec un package d'instrumentation automatique tel que. opentelemetry-instrument-langchain Il est également possible d'envoyer des conventions sémantiques, de la télémétrie et des spans à l'IA générative en définissant un traceur personnalisé. AgentCore prend en charge l'utilisation des bibliothèques d'instrumentation suivantes dans votre infrastructure d'agents :

Pour consulter 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 ADOT ( AWS Distro for Open Telemetry) au code de votre 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 CloudWatch Transaction Search et ajouter le SDK ADOT à votre code.

Si vous hébergez votre agent sur AWS Lambda, utilisez la couche AWS Lambda pour le AWS site Web de OpenTelemetry distribution. OpenTelemetry Ajoutez la couche à votre fonction, puis définissez la variable d'AWS_LAMBDA_EXEC_WRAPPERenvironnement 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.

Pour les agents exécutés en dehors de l' AgentCore environnement d'exécution, vous devez également créer un groupe journal 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
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.

Support de l'identifiant de session

Pour propager l'identifiant de session, vous devez l'invoquer en utilisant l'identifiant de session dans le bagage 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é pour le AgentCore temps d'exécution, la mémoire, la passerelle, les outils intégrés et les 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, pour ce qui est de la mémoire, de la passerelle et des ressources d'outils intégrées, les destinations des journaux AgentCore ne sont pas configurées automatiquement 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 du groupe de journaux par défaut pour les ressources de mémoire et de passerelle est au /aws/vendedlogs/bedrock-agentcore/{resource-type}/APPLICATION_LOGS/{resource-id} format « where {resource-type} is memory or gateway ».

Pour les journaux de mémoire et de passerelle, vous pouvez également configurer les destinations des journaux dans les journaux Amazon S3 ou dans 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 les sections 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 pour la mémoire ou les journaux de passerelle dans la AgentCore console, suivez les procédures suivantes.

Configuration du suivi de la livraison à CloudWatch l'aide de la console

Cette section décrit comment activer la livraison de traces CloudWatch pour suivre le flux d'interactions dans votre application, vous permettant ainsi de visualiser les demandes, d'identifier les obstacles aux 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 du 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 appelez votre agent afin d'améliorer l'observabilité et les capacités de suivi :

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

Vous pouvez appeler 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 d' Build-in outils suivantes afin d'améliorer l'observabilité et les capacité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 appeler 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 capacités de suivi :

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

Bonnes pratiques en matière d'observabilité

Tenez compte des meilleures 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 des agents hébergés dans l' AgentCore environnement d'exécution à d'autres plateformes d'observabilité afin de capturer et de visualiser les résultats 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 du AgentCore moteur d'exécution, garantissant ainsi qu'aucune des configurations ADOT par défaut n'est définie.