Erweitern Sie Ihre Amazon AgentCore Bedrock-Ressourcen um Beobachtbarkeit

Amazon Bedrock AgentCore bietet eine Reihe integrierter Metriken zur Überwachung der Leistung von Ressourcen für die Typen AgentCore Runtime, Memory, Gateway, integrierte Tools und Identitätsressourcen. Diese Standarddaten sind in Amazon verfügbar CloudWatch. Um das gesamte Spektrum der Observability-Daten in der CloudWatch Konsole anzuzeigen oder benutzerdefinierte Laufzeitmetriken für Agenten auszugeben, müssen Sie Ihren Code mit dem AWS Distro for Open Telemetry (ADOT) SDK instrumentieren.

Um das Observability-Dashboard in aufzurufen CloudWatch, öffnen Sie die Amazon CloudWatch GenAi Observability-Seite.

In den folgenden Abschnitten erfahren Sie mehr über die Konfiguration Ihrer Ressourcen zur Anzeige von Observability-Metriken auf der generativen KI-Observability-Seite der CloudWatch Konsole und in Logs. CloudWatch

Observability aktivieren AgentCore

Um die vom AgentCore Service generierten Metriken, Spans und Traces anzuzeigen, müssen Sie zunächst eine einmalige Einrichtung durchführen, um Amazon CloudWatch Transaction Search zu aktivieren. Um die vom Service bereitgestellten Spans für Speicherressourcen anzuzeigen, müssen Sie bei der Erstellung eines Speichers auch die Ablaufverfolgung aktivieren. Weitere Informationen finden Sie unter Aktivieren von Observability für AgentCore Laufzeit-, Speicher-, Gateway-, integrierte Tools und Identitätsressourcen.

In den folgenden Abschnitten wird beschrieben, wie Sie diese Setup-Aktionen ausführen und Observability in Ihrem Agentencode aktivieren.

CloudWatch Transaktionssuche aktivieren

Sie können die CloudWatch Transaktionssuche entweder mithilfe der CloudWatch Konsole oder mithilfe einer API über die AWS Befehlszeilenschnittstelle (AWS CLI) oder eines der AWS SDKs aktivieren.

Verwenden Sie eines der folgenden Verfahren, um die Transaktionssuche zu aktivieren.

Span-Ziel für Agenten, die in Amazon Bedrock AgentCore Runtime gehostet werden

Mit AgentCore Runtime, einer Funktion von Amazon Bedrock AgentCore, können Sie einen Agenten so konfigurieren, dass er seine Spans an dieselbe CloudWatch Amazon-Protokollgruppe übermittelt wie die Protokolle des Agenten. Bei dieser Konfiguration werden die Spans in den spans Log-Stream übertragen und nicht in /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name> die gemeinsam genutzte aws/spans Protokollgruppe. Sie können Spans, strukturierte Protokolle und Standardausgaben in einer Protokollgruppe für jeden Agenten zusammenfassen, die Zugriffskontrolle und Verschlüsselung auf einen einzelnen Agenten beschränken und Telemetrie von einem einzigen Standort aus exportieren.

In unterstützten AWS Regionen verwenden neu erstellte Agenten die Protokollgruppe des Agenten als Standard-Span-Ziel. Agenten, die erstellt wurden, bevor eine Region das einheitliche Span-Ziel unterstützt, behalten die gemeinsame aws/spans Protokollgruppe als Standard bei.

Sie können den Standard für einen einzelnen Agenten mit der UNIFIED_TRACES_DESTINATION_ENABLED Umgebungsvariablen in Ihrer Agenten-Laufzeit außer Kraft setzen:

Damit AgentCore die Spans an die Protokollgruppe des Agenten übermittelt werden können, muss Folgendes zutreffen:

Durch das Ändern des Span-Ziels werden vorhandene Span-Daten nicht verschoben. Spans, die AgentCore bereits übermittelt wurden, verbleiben in ihrer ursprünglichen Protokollgruppe.

Aktivierung der Beobachtbarkeit im Agentencode für Agenten AgentCore-hosted

Zusätzlich zu den vom Service generierten Metriken können AgentCore Sie damit auch Span- und Trace-Daten sowie benutzerdefinierte Messwerte sammeln, die aus Ihrem Agentencode stammen.

Wenn Sie Agenten-Frameworks wie Strands oder CrewAI mit unterstützten Instrumentierungsbibliotheken von Drittanbietern verwenden, bietet das Framework selbst integrierte Unterstützung für die semantischen Konventionen von OTEL und GenAI und kann auch mit einem automatischen Instrumentierungspaket wie instrumentiert werden. LangChainopentelemetry-instrument-langchain Es ist auch möglich, semantische Konventionen von Generative AI, Telemetrie und Spannweiten zu senden, indem ein benutzerdefinierter Tracer definiert wird. AgentCore unterstützt die Verwendung der folgenden Instrumentierungsbibliotheken in Ihrem Agenten-Framework:

Um diese Daten auf der generativen KI-Observabilitätsseite der CloudWatch Konsole und in Amazon anzuzeigen CloudWatch, müssen Sie Ihrem Agentencode das SDK AWS Distro for Open Telemetry (ADOT) hinzufügen.

Gehen Sie wie folgt vor, um ADOT-Unterstützung hinzuzufügen und AgentCore Observability zu aktivieren.

Fügen Sie Ihrem Agenten Observability hinzu AgentCore

Aktivierung der Beobachtbarkeit für Agenten, die außerhalb von gehostet werden AgentCore

Um Observability für Agenten zu aktivieren, die außerhalb der AgentCore Runtime gehostet werden, folgen Sie zunächst den Schritten in den vorherigen Abschnitten, um die CloudWatch Transaktionssuche zu aktivieren, und fügen Sie Ihrem Code das ADOT-SDK hinzu.

Wenn Sie Ihren Agenten auf AWS Lambda hosten, verwenden Sie den AWS Lambda-Layer für OpenTelemetry auf der AWS Distro for -Website. OpenTelemetry Fügen Sie die Ebene zu Ihrer Funktion hinzu und setzen Sie dann die AWS_LAMBDA_EXEC_WRAPPER Umgebungsvariable auf. /opt/otel-instrument Die Ebene instrumentiert dann automatisch Ihre Funktion. Bei diesem Ansatz müssen Sie das aws-opentelemetry-distro Paket nicht hinzufügen oder den zuvor beschriebenen opentelemetry-instrument Befehl ausführen.

Für Agenten, die außerhalb der AgentCore Runtime ausgeführt werden, müssen Sie außerdem eine Agenten-Protokollgruppe erstellen, die Sie in Ihre Umgebungsvariablen aufnehmen.

Konfigurieren Sie Ihre AWS Umgebungsvariablen und legen Sie dann Ihre Open Telemetrie-Umgebungsvariablen fest, wie im Folgenden gezeigt.

AWS Umgebungsvariablen

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>

OTEL-Umgebungsvariablen

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>Ersetzen Sie es durch den Namen Ihres Agenten und <agent-id> durch eine eindeutige Kennung für Ihren Agenten.

Unterstützung für Sitzungs-IDs

Um die Sitzungs-ID weiterzugeben, müssen Sie den Aufruf mit der Sitzungs-ID im OTEL-Backage aufrufen:

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

Aktivierung von Observability für AgentCore Laufzeit-, Speicher-, Gateway-, integrierte Tools und Identitätsressourcen

Wenn Sie eine AgentCore Laufzeitressource (Agent) erstellen, erstellt AgentCore Runtime standardmäßig eine CloudWatch Protokollgruppe für die vom Dienst bereitgestellten Protokolle. Für Speicher-, Gateway- und integrierte Toolressourcen werden Protokollziele jedoch AgentCore nicht automatisch für Sie konfiguriert.

Für Speicher- und Gatewayressourcen können Sie Protokollziele entweder in der Konsole oder mithilfe eines AWS SDK konfigurieren. Wenn Sie die Konsole verwenden, um ein CloudWatch Logs-Ziel zu konfigurieren, hat der Standard-Protokollgruppenname für Speicher- und Gateway-Ressourcen die Form/aws/vendedlogs/bedrock-agentcore/{resource-type}/APPLICATION_LOGS/{resource-id}, wobei entweder memory oder {resource-type} stehtgateway.

Für Speicher- und Gateway-Protokolle können Sie mithilfe der AgentCore Konsole auch Protokollziele in Amazon S3 S3-Protokollen oder Firehose-Stream-Protokollen konfigurieren. Weitere Informationen zum Speichern von Protokollen in Amazon S3 oder Firehose finden Sie unter Hochladen, Herunterladen und Arbeiten mit Objekten in Amazon S3 und Erstellen eines Amazon Data Firehose-Lieferdatenstroms.

Weitere Informationen zu den Protokolldaten, die von AgentCore Arbeitsspeicher- und Gateway-Ressourcen ausgegeben werden, finden Sie unter Bereitgestellte Protokolldaten (Speicher) oder Bereitgestellte Protokolldaten (Gateway).

Für integrierte Toolressourcen stellt der AgentCore Dienst standardmäßig keine Protokolle bereit, aber Sie können Ihre eigenen Protokolle anhand Ihres Codes ausgeben. Wenn Sie Ihre eigenen Protokollausgaben bereitstellen, müssen Sie die Protokollziele zum Speichern dieser Daten manuell konfigurieren.

Informationen darüber, was Observability-Daten standardmäßig für jeden Ressourcentyp AgentCore bieten, finden Sie unter Von Amazon Bedrock AgentCore generierte Observabilitätsdaten.

Konfigurieren Sie Protokollziele mithilfe der Konsole

Gehen Sie wie folgt vor, um Protokollziele für Speicher- oder Gateway-Protokolle in der AgentCore Konsole zu konfigurieren.

Konfigurieren Sie die Zustellung mit Ablaufverfolgung für die CloudWatch Verwendung der Konsole

In diesem Abschnitt wird beschrieben, wie Sie Trace Delivery aktivieren CloudWatch , um den Fluss der Interaktionen in Ihrer Anwendung nachzuverfolgen. Auf diese Weise können Sie Anfragen visualisieren, Leistungsengpässe identifizieren, Fehler beheben und die Leistung optimieren.

Konfigurieren Sie CloudWatch Ressourcen mithilfe eines AWS SDK

So konfigurieren Sie eine Zustellungsquelle für Logs and 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)

Verbesserte AgentCore Laufzeitbeobachtbarkeit mit benutzerdefinierten Headern

Sie können Ihren Agenten mit zusätzlichen HTTP-Headern aufrufen, um erweiterte Observability-Optionen bereitzustellen. Das folgende Beispiel zeigt Aufrufe, einschließlich optionaler zusätzlicher Header-Anfragen für Agenten, die in der Runtime gehostet werden. AgentCore

Beispiel für einen Boto3-Aufruf

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

Sie können die folgenden optionalen Header hinzufügen, wenn Sie Ihren Agenten aufrufen, um die Beobachtbarkeit und die Nachverfolgungsfunktionen zu verbessern:

Verbesserte Beobachtbarkeit der AgentCore integrierten Tools mit benutzerdefinierten Headern

Sie können Ihre Built-in Tools mit zusätzlichen HTTP-Headern aufrufen, um erweiterte Observability-Optionen bereitzustellen. Sie können die folgenden optionalen Header hinzufügen, wenn Sie die folgenden Build-in Tools-APIs integrieren, um die Beobachtbarkeit und die Tracing-Funktionen zu verbessern:

Die folgenden APIs unterstützen benutzerdefinierte Header:

Verbesserte AgentCore Identitätserkennbarkeit mit benutzerdefinierten Headern

Sie können Ihre Identitätsressourcen mit zusätzlichen HTTP-Headern aufrufen, um erweiterte Observability-Optionen bereitzustellen. Sie können bei der Integration der folgenden Identitäts-APIs die folgenden optionalen Header einbeziehen, um die Beobachtbarkeit und die Nachverfolgungsfunktionen zu verbessern:

Die folgenden APIs unterstützen benutzerdefinierte Header:

Bewährte Verfahren zur Beobachtbarkeit

Beachten Sie die folgenden bewährten Methoden bei der Implementierung von Observability für Agenten in: AgentCore

Verwendung anderer Observability-Plattformen

Um in der AgentCore Runtime gehostete Agenten in andere Observability-Plattformen zu integrieren, um Telemetrieausgaben zu erfassen und anzuzeigen, legen Sie die folgende Umgebungsvariable fest:

DISABLE_ADOT_OBSERVABILITY=true

Wenn Sie diese Variable auf setzen, true werden die standardmäßigen ADOT-Umgebungsvariablen der AgentCore Laufzeit deaktiviert, sodass sichergestellt ist, dass keine der ADOT-Standardkonfigurationen festgelegt ist.