Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Aggiungi osservabilità alle tue risorse Amazon Bedrock AgentCore

Amazon Bedrock AgentCore fornisce una serie di metriche integrate per monitorare le prestazioni delle risorse per il AgentCore runtime, la memoria, il gateway, gli strumenti integrati e i 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, apri la pagina Amazon Observability. CloudWatch CloudWatch GenAi

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

Abilitazione dell'osservabilità AgentCore

Per visualizzare le metriche, gli intervalli e le tracce generati dal AgentCore servizio, devi prima completare una configurazione unica per attivare Amazon Transaction Search. CloudWatch Per visualizzare gli intervalli di risorse di memoria forniti dal servizio, devi anche abilitare la traccia quando crei una memoria. Per saperne di più, vedi Abilitazione dell'osservabilità per 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.

Attivazione della ricerca CloudWatch delle transazioni

Puoi abilitare la ricerca CloudWatch delle transazioni 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 Transaction Search.

Destinazione Span per gli 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 log di Amazon dei log dell'agente. CloudWatch Con questa configurazione, gli intervalli vengono indirizzati allo stream di spans log in/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>, anziché al gruppo di log condivisoaws/spans. Puoi tenere insieme gli intervalli, i log strutturati e l'output standard in un gruppo di log per agente, estendere il controllo degli accessi e la crittografia a un singolo agente ed esportare la telemetria da un'unica posizione.

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

È possibile sovrascrivere l'impostazione predefinita per un singolo agente con la variabile di UNIFIED_TRACES_DESTINATION_ENABLED ambiente nel runtime dell'agente:

AgentCore Per inviare 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 dello span esistenti. Gli intervalli AgentCore già distribuiti 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 LangChain, 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. opentelemetry-instrument-langchain È anche possibile inviare telemetria e intervalli di convenzioni semantiche di intelligenza artificiale generativa definendo un tracciante personalizzato. https://opentelemetry.io/docs/specs/semconv/gen-ai/ https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/ 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 l'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 ADOT SDK al tuo codice.

Se ospiti il tuo agente su AWS Lambda, utilizza Lambda Layer for OpenTelemetry sul AWS sito web di Distro for. AWS OpenTelemetry Aggiungi il livello alla tua funzione, quindi imposta la variabile di AWS_LAMBDA_EXEC_WRAPPER ambiente su. /opt/otel-instrument Il livello 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 in esecuzione al di fuori del AgentCore runtime, è inoltre necessario creare un gruppo di log di 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
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

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

Supporto per gli ID di sessione

Per diffondere l'ID di sessione, è necessario richiamarlo utilizzando l'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

Abilitazione dell'osservabilità di 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 utilizzi la console per configurare una destinazione CloudWatch Logs, il nome del gruppo di log predefinito per le risorse di memoria e gateway ha il formato/aws/vendedlogs/bedrock-agentcore/{resource-type}/APPLICATION_LOGS/{resource-id}, dove {resource-type} è memory ogateway.

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 AgentCore console. Per ulteriori informazioni sull'archiviazione dei log in Amazon S3 o Firehose, consulta Caricare, scaricare e lavorare con oggetti in Amazon S3 e Creazione di un flusso di distribuzione Amazon Data Firehose.

Per ulteriori informazioni sui dati di log emessi da AgentCore for memory and gateway resources, consulta Provider log data (memory) o Provider log data (gateway).

Per quanto riguarda le risorse degli strumenti integrate, il AgentCore servizio non fornisce registri per impostazione predefinita, ma puoi generare i tuoi log dal tuo codice. Se fornisci i tuoi output di log, devi configurare manualmente le destinazioni dei log per archiviare questi dati.

Per vedere cosa AgentCore forniscono di default i dati di osservabilità 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 il tracciamento della consegna CloudWatch tramite la console

Questa sezione descrive come abilitare la distribuzione delle tracce CloudWatch per tracciare il flusso di interazioni attraverso l'applicazione, consentendoti di visualizzare le richieste, identificare i colli di bottiglia nelle prestazioni, risolvere gli errori e ottimizzare le prestazioni.

Configura le risorse utilizzando CloudWatch un AWS SDK

Per configurare una fonte di consegna per log e 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à AgentCore di runtime migliorata con intestazioni personalizzate

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

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

Puoi includere le seguenti intestazioni opzionali quando invoci il tuo 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 intestazioni personalizzate:

Osservabilità AgentCore dell'identità migliorata 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 capacità di osservabilità e tracciamento:

Le seguenti API supportano le intestazioni personalizzate:

Le migliori pratiche di osservabilità

Prendi in considerazione le seguenti best practice quando implementi 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 per true annullare l'impostazione delle variabili di ambiente ADOT predefinite del AgentCore runtime, assicurando che nessuna delle configurazioni ADOT predefinite sia impostata.