Erste Schritte mit AgentCore Observability

Amazon Bedrock Amazon Bedrock AgentCore Observability hilft Ihnen dabei, die Leistung von Agenten in Produktionsumgebungen zu verfolgen, zu debuggen und zu überwachen. Dieses Handbuch hilft Ihnen bei der Implementierung von Observability-Funktionen in Ihren Agentenanwendungen.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie über Folgendes verfügen:

Amazon Bedrock AgentCore Observability bietet zwei Möglichkeiten, die Überwachung an unterschiedliche Infrastrukturanforderungen anzupassen:

Da es sich um eine einmalige Einrichtung pro AWS Konto handelt, müssen Erstbenutzer die Transaktionssuche bei Amazon aktivieren CloudWatch. Es gibt zwei Möglichkeiten, dies zu tun: über die API und über die CloudWatch Konsole.

Schritt 1: Aktivieren Sie die Transaktionssuche auf CloudWatch

Nachdem Sie die Transaktionssuche aktiviert haben, kann es zehn Minuten dauern, bis Spans zur Suche und Analyse verfügbar sind. Wählen Sie eine der folgenden Optionen:

Option 1: Aktivieren Sie die Transaktionssuche mithilfe einer API

Um die Transaktionssuche mithilfe der API zu aktivieren

Option 2: Aktivieren Sie die Transaktionssuche in der CloudWatch Konsole

Um die Transaktionssuche in der CloudWatch Konsole zu aktivieren

Lassen Sie uns nun die beiden Möglichkeiten zur Konfiguration der Observability untersuchen.

Schritt 2: Observability für von Amazon Bedrock AgentCore Runtime gehostete Agenten aktivieren

Amazon AgentCore Runtime-hosted Bedrock-Agenten werden direkt in der Amazon AgentCore Bedrock-Umgebung bereitgestellt und ausgeführt und bieten automatische Instrumentierung mit minimaler Konfiguration. Wenn Sie einen Agenten über die AgentCore CLI bereitstellen, wird Ihr Agent von der Runtime automatisch in Kenntnis gesetzt OpenTelemetry — es sind keine zusätzlichen OTEL-Bibliotheken oder Konfigurationen erforderlich.

Ein vollständiges Beispiel finden Sie in diesem Notizbuch

Erstellen Sie Ihr Agentenprojekt

Erstellen Sie mit der AgentCore CLI ein neues Projekt. Dadurch werden Ihr Projektordner, Ihre virtuelle Umgebung und Ihre Abhängigkeiten eingerichtet:

npm install -g @aws/agentcore
agentcore create --name StrandsClaudeGettingStarted

Ersetzen Sie im Agentenverzeichnis des Projekts den Standard-Agentencode durch Ihre eigene Agentenlogik. Das Folgende ist ein Beispiel für die Verwendung des Strands Agents SDK:

## app/StrandsClaudeGettingStarted/main.py
from strands import Agent, tool
from strands_tools import calculator
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands.models import BedrockModel

app = BedrockAgentCoreApp()

@tool
def weather():
    """Get weather"""
    return "sunny"

model = BedrockModel(
    model_id="us.anthropic.claude-3-7-sonnet-20250219-v1:0",
)
agent = Agent(
    model=model,
    tools=[calculator, weather],
    system_prompt="You're a helpful assistant. You can do simple math calculation, and tell the weather."
)

@app.entrypoint
def strands_agent_bedrock(payload):
    """Invoke the agent with a payload"""
    user_input = payload.get("prompt")
    response = agent(user_input)
    return response.message['content'][0]['text']

if __name__ == "__main__":
    app.run()

Stellen Sie Ihren Agenten bereit und rufen Sie ihn auf

Stellen Sie den Agenten in AgentCore Runtime bereit. Die AgentCore CLI kümmert sich um die Paketierung, Bereitstellung und automatische OTEL-Instrumentierung:

cd StrandsClaudeGettingStarted
agentcore deploy

Nach der Bereitstellung läuft Ihr Agent auf AgentCore Runtime und wird automatisch instrumentiert mit OpenTelemetry. Rufen Sie Ihren Agenten auf und sehen Sie sich die Traces, Sessions und Metriken im GenAI Observability Dashboard in Amazon an: CloudWatch

agentcore invoke

Alternativ können Sie Ihren Agenten mithilfe des SDK programmgesteuert aufrufen: AWS

import boto3, json

client = boto3.client('bedrock-agentcore')

response = client.invoke_agent_runtime(
    agentRuntimeArn="YOUR_AGENT_RUNTIME_ARN",
    runtimeSessionId="my-observability-session-001",
    payload=json.dumps({"prompt": "What is 2 + 2?"}),
    qualifier="DEFAULT"
)

print(json.loads(response['response'].read()))

Schritt 3: Beobachtbarkeit für Agenten aktivieren, die nicht zu Amazon Bedrock gehören AgentCore-hosted

Für Agenten, die außerhalb der Amazon AgentCore Bedrock-Laufzeit laufen, können Sie dieselben Überwachungsfunktionen für Agenten bereitstellen, die in Ihrer eigenen Infrastruktur eingesetzt werden. Dies ermöglicht eine konsistente Beobachtbarkeit, unabhängig davon, wo Ihre Agenten ausgeführt werden. Gehen Sie wie folgt vor, um die Umgebungsvariablen zu konfigurieren, die für die Beobachtung Ihrer Agenten erforderlich sind.

Ein vollständiges Beispiel finden Sie im Beispiel Agents on Amazon EKS auf der GitHub Website.

Konfiguration AWS Umgebungsvariablen

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

Konfigurieren Sie die CloudWatch Protokollierung

Erstellen Sie eine Protokollgruppe und einen Protokollstream für Ihren Agenten in Amazon CloudWatch , mit denen Sie die folgenden Umgebungsvariablen konfigurieren können.

OpenTelemetry Umgebungsvariablen konfigurieren

export AGENT_OBSERVABILITY_ENABLED=true # Activates the ADOT pipeline
export OTEL_PYTHON_DISTRO=aws_distro # Uses AWS Distro for OpenTelemetry
export OTEL_PYTHON_CONFIGURATOR=aws_configurator # Sets AWS configurator for ADOT SDK
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf # Configures export protocol
export  OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=<YOUR-LOG-GROUP>,x-aws-log-stream=<YOUR-LOG-STREAM>,x-aws-metric-namespace=<YOUR-NAMESPACE>
# Directs logs to CloudWatch groups
export OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-aws-log-group=<YOUR-LOG-GROUP>,x-aws-log-stream=<YOUR-TRACES-LOG-STREAM>
# (Optional) Directs spans to your log group instead of the aws/spans log group. Requires ADOT version 0.18.0 or later.
export OTEL_RESOURCE_ATTRIBUTES=service.name=<YOUR-AGENT-NAME> # Identifies your agent in observability data
export OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false # AWS Lambda Layer for OpenTelemetry only: disables Application Signals
export OTEL_LOGS_EXPORTER=otlp # AWS Lambda Layer for OpenTelemetry only: exports logs over OTLP
export OTEL_METRICS_EXPORTER=awsemf # AWS Lambda Layer for OpenTelemetry only: exports metrics as CloudWatch EMF

<YOUR-AGENT-NAME>Ersetzen Sie ihn durch einen eindeutigen Namen, um diesen Agenten im GenAI Observability-Dashboard und in den Protokollen zu identifizieren.

Lokal einen Agenten erstellen

# Create agent.py -  Strands agent that is a weather assistant
from strands import Agent
from strands_tools import http_request

# Define a weather-focused system prompt
WEATHER_SYSTEM_PROMPT = """You are a weather assistant with HTTP capabilities. You can:

1. Make HTTP requests to the National Weather Service API
2. Process and display weather forecast data
3. Provide weather information for locations in the United States

When retrieving weather information:
1. First get the coordinates or grid information using https://api.weather.gov/points/{latitude},{longitude} or https://api.weather.gov/points/{zipcode}
2. Then use the returned forecast URL to get the actual forecast

When displaying responses:
- Format weather data in a human-readable way
- Highlight important information like temperature, precipitation, and alerts
- Handle errors appropriately
- Convert technical terms to user-friendly language

Always explain the weather conditions clearly and provide context for the forecast.
"""

# Create an agent with HTTP capabilities
weather_agent = Agent(
    system_prompt=WEATHER_SYSTEM_PROMPT,
    tools=[http_request],  # Explicitly enable http_request tool
)

response = weather_agent("What's the weather like in Seattle?")
print(response)

Führen Sie Ihren Agenten mit dem Befehl zur automatischen Instrumentierung aus

aws-opentelemetry-distroIn Ihrer Datei requirements.txt wird der opentelemetry-instrument Befehl:

Verwenden Sie den folgenden Befehl, um Ihren Agenten mit automatischer Instrumentierung auszuführen:

opentelemetry-instrument python agent.py

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.

Sie können jetzt Ihre Traces, Sessions und Metriken im GenAI Observability Dashboard auf Amazon CloudWatch mit dem Wert anzeigen YOUR-AGENT-NAME, den Sie in Ihren Umgebungsvariablen konfiguriert haben.

Um Traces über mehrere Agentenläufe hinweg zu korrelieren, können Sie mithilfe von Baggage eine Sitzungs-ID mit Ihren Telemetriedaten verknüpfen: OpenTelemetry

from opentelemetry import baggage, context
ctx = baggage.set_baggage("session.id", session_id)

Schritt 4: Beobachten Sie Ihren Agenten mit GenAI Observability auf Amazon CloudWatch

Nach der Implementierung von Observability können Sie die gesammelten Daten einsehen unter: CloudWatch

Beobachten Sie Ihren Agenten

Logs anzeigen CloudWatch

Um Logs einzusehen CloudWatch

Spuren und Spannweiten anzeigen

Um Spuren und Spannweiten anzuzeigen

Anzeigen von -Metriken

Um Metriken anzuzeigen

Bewährte Methoden