Aggiungi osservabilità alle tue risorse Amazon Bedrock AgentCore

Amazon Bedrock AgentCore fornisce una serie di parametri integrati per monitorare le prestazioni delle risorse per AgentCore runtime, memoria, gateway, strumenti integrati e tipi di risorse di identità. Questi dati predefiniti sono disponibili in Amazon CloudWatch. Per visualizzare l'intera gamma di dati di osservabilità nella CloudWatch console o per generare metriche di runtime personalizzate per gli agenti, devi strumentare il codice utilizzando l'SDK AWS Distro for Open Telemetry (ADOT).

Per visualizzare la dashboard di osservabilità in CloudWatch, apri la pagina Amazon CloudWatch GenAi Observability.

Consulta le sezioni seguenti per saperne di più sulla configurazione delle risorse per visualizzare i parametri di osservabilità nella pagina di osservabilità dell'IA generativa della CloudWatch console e nei log. CloudWatch

Abilitare l'osservabilità AgentCore

Per visualizzare metriche, intervalli e tracce generati dal AgentCore servizio, devi prima completare una configurazione unica per attivare Amazon CloudWatch Transaction Search. Per visualizzare gli intervalli di risorse di memoria forniti dal servizio, devi anche abilitare il tracciamento quando crei una memoria. Per ulteriori informazioni, consulta Enabling observability for AgentCore runtime, memory, gateway, strumenti integrati e risorse di identità.

Le sezioni seguenti descrivono come eseguire queste azioni di configurazione e abilitare l'osservabilità nel codice dell'agente.

Abilitazione della ricerca CloudWatch delle transazioni

Puoi abilitare CloudWatch Transaction Search utilizzando la CloudWatch console o utilizzando un'API tramite l'interfaccia a riga di AWS comando (AWS CLI) o uno degli AWS SDK.

Utilizza una delle seguenti procedure per abilitare la ricerca delle transazioni.

Destinazione Span per agenti ospitati nel runtime di Amazon Bedrock AgentCore

Con il AgentCore runtime, una funzionalità di Amazon Bedrock AgentCore, puoi configurare un agente in modo che distribuisca i suoi intervalli allo stesso gruppo di CloudWatch log Amazon dei log dell'agente. Con questa configurazione, gli intervalli vengono inseriti nel flusso di spans log in anziché nel /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name> gruppo di log condiviso. aws/spans È possibile riunire intervalli, log strutturati e output standard in un unico gruppo di log per agente, limitare il controllo degli accessi e la crittografia a un singolo agente ed esportare i dati di telemetria da un'unica posizione.

Nelle AWS regioni supportate, gli agenti appena creati utilizzano il gruppo di log dell'agente come destinazione span predefinita. Gli agenti creati prima che una regione supporti la destinazione span unificata mantengono il gruppo di aws/spans log condiviso come predefinito.

Puoi sostituire l'impostazione predefinita per un singolo agente con la variabile di UNIFIED_TRACES_DESTINATION_ENABLED ambiente nel runtime dell'agente:

Per AgentCore consegnare gli intervalli al gruppo di log dell'agente, deve essere vero quanto segue:

La modifica della destinazione dello span non comporta lo spostamento dei dati di span esistenti. Gli span AgentCore già consegnati rimangono nel gruppo di log originale.

Abilitazione dell'osservabilità nel codice dell'agente per gli agenti AgentCore-hosted

Oltre alle metriche generate dal servizio, AgentCore puoi anche raccogliere dati di span and trace e metriche personalizzate emesse dal codice del tuo agente.

Quando si utilizzano framework di agenti come Strands o CrewAI con librerie di strumentazione di terze parti supportate, il framework stesso include il supporto integrato per le convenzioni semantiche OTEL e GenAI e può anche essere strumentato con un pacchetto di strumentazione automatica come. LangChainopentelemetry-instrument-langchain È anche possibile inviare convenzioni semantiche di intelligenza artificiale generativa, telemetria e intervalli definendo un tracciante personalizzato. AgentCore supporta l'uso delle seguenti librerie di strumentazione nel framework degli agenti:

Per visualizzare questi dati nella pagina di osservabilità dell'IA generativa della CloudWatch console e in Amazon CloudWatch, devi aggiungere l'SDK AWS Distro for Open Telemetry (ADOT) al codice del tuo agente.

Per aggiungere il supporto ADOT e abilitare AgentCore l'osservabilità, segui i passaggi della procedura seguente.

Aggiungi osservabilità al tuo agente AgentCore

Abilitazione dell'osservabilità per gli agenti ospitati all'esterno di AgentCore

Per abilitare l'osservabilità per gli agenti ospitati al di fuori del AgentCore runtime, segui innanzitutto i passaggi nelle sezioni precedenti per abilitare CloudWatch Transaction Search e aggiungi l'ADOT SDK al tuo codice.

Se ospiti il tuo agente su AWS Lambda, usa il AWS Lambda Layer for OpenTelemetry sul sito Web Distro for. AWS OpenTelemetry Aggiungi il layer alla tua funzione, quindi imposta la variabile di AWS_LAMBDA_EXEC_WRAPPER ambiente su. /opt/otel-instrument Il layer quindi strumenta automaticamente la tua funzione. Con questo approccio, non è necessario aggiungere il aws-opentelemetry-distro pacchetto o eseguire il opentelemetry-instrument comando descritto in precedenza.

Per gli agenti che funzionano al di fuori del AgentCore runtime, è inoltre necessario creare un gruppo di log degli agenti da includere nelle variabili di ambiente.

Configurate le variabili di AWS ambiente, quindi impostate le variabili di ambiente Open Telemetry come illustrato di seguito.

AWS variabili di ambiente

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>

variabili di ambiente 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

Sostituiscile <agent-name> con il nome del tuo agente e <agent-id> con un identificatore univoco per il tuo agente.

Supporto per l'ID di sessione

Per propagare l'ID di sessione, è necessario richiamare l'utilizzo dell'identificatore di sessione nel bagaglio 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

Consentire l'osservabilità per AgentCore runtime, memoria, gateway, strumenti integrati e risorse di identità

Quando si crea una risorsa AgentCore di runtime (agente), per impostazione predefinita, AgentCore runtime crea un gruppo di CloudWatch log per i log forniti dal servizio. Tuttavia, per quanto riguarda la memoria, il gateway e le risorse degli strumenti integrati, AgentCore non configura automaticamente le destinazioni dei log.

Per quanto riguarda le risorse di memoria e gateway, puoi configurare le destinazioni dei log nella console o utilizzando un AWS SDK. Se si utilizza la console per configurare una destinazione CloudWatch Logs, il nome del gruppo di log predefinito per le risorse di memoria e gateway ha la forma/aws/vendedlogs/bedrock-agentcore/{resource-type}/APPLICATION_LOGS/{resource-id}, where {resource-type} is or. memory gateway

Per i log di memoria e gateway, puoi anche configurare le destinazioni dei log nei log di Amazon S3 o nei log di flusso Firehose utilizzando la console. AgentCore Per ulteriori informazioni sull'archiviazione dei log in Amazon S3 o Firehose, consulta Caricamento, download e utilizzo di oggetti in Amazon S3 e Creazione di un flusso di distribuzione Amazon Data Firehose.

Per ulteriori informazioni sui dati di registro emessi da AgentCore per le risorse di memoria e gateway, consulta Dati di registro forniti (memoria) o Dati di registro forniti (gateway).

Per quanto riguarda le risorse degli strumenti integrate, il AgentCore servizio non fornisce log per impostazione predefinita, ma è possibile generare log personalizzati a partire dal codice. Se fornite i vostri output di log, dovete configurare manualmente le destinazioni dei log per archiviare questi dati.

Per vedere quali dati di osservabilità AgentCore forniscono di default per ogni tipo di risorsa, consulta i dati di osservabilità AgentCore generati da Amazon Bedrock.

Configura le destinazioni dei log utilizzando la console

Per configurare le destinazioni dei log per la memoria o i log del gateway nella AgentCore console, utilizzare le seguenti procedure.

Configura Tracing Delivery per CloudWatch l'utilizzo della console

Questa sezione descrive come abilitare Trace Delivery CloudWatch per tracciare il flusso di interazioni attraverso l'applicazione, consentendoti di visualizzare le richieste, identificare i punti deboli nelle prestazioni, risolvere gli errori e ottimizzare le prestazioni.

Configura le risorse utilizzando CloudWatch un AWS SDK

Per configurare una fonte di distribuzione per log and trace (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)

Osservabilità migliorata in AgentCore fase di esecuzione con intestazioni personalizzate

Puoi richiamare il tuo agente con intestazioni HTTP aggiuntive per fornire opzioni di osservabilità avanzate. L'esempio seguente mostra le invocazioni, incluse richieste di intestazione aggiuntive opzionali per gli agenti ospitati nel runtime. AgentCore

Esempio di invocazione 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"}',
    )

È possibile includere le seguenti intestazioni opzionali quando si richiama l'agente per migliorare le capacità di osservabilità e tracciamento:

Osservabilità migliorata degli strumenti AgentCore integrati con intestazioni personalizzate

Puoi richiamare i tuoi Built-in strumenti con intestazioni HTTP aggiuntive per fornire opzioni di osservabilità avanzate. Puoi includere le seguenti intestazioni opzionali quando integri le seguenti API Build-in Tools per migliorare le capacità di osservabilità e tracciamento:

Le seguenti API supportano le intestazioni personalizzate:

Migliore osservabilità AgentCore dell'identità con intestazioni personalizzate

Puoi richiamare le tue risorse di identità con intestazioni HTTP aggiuntive per fornire opzioni di osservabilità avanzate. Puoi includere le seguenti intestazioni opzionali quando integri le seguenti API di identità per migliorare le funzionalità di osservabilità e tracciamento:

Le seguenti API supportano le intestazioni personalizzate:

Migliori pratiche di osservabilità

Considerate le seguenti best practice quando implementate l'osservabilità per gli agenti in: AgentCore

Utilizzo di altre piattaforme di osservabilità

Per integrare gli agenti ospitati nel AgentCore runtime con altre piattaforme di osservabilità per acquisire e visualizzare gli output di telemetria, imposta la seguente variabile di ambiente:

DISABLE_ADOT_OBSERVABILITY=true

L'impostazione di questa variabile in modo da true annullare l'impostazione delle variabili di ambiente ADOT predefinite del AgentCore runtime, assicurando che nessuna delle configurazioni ADOT predefinite sia impostata.