# Erste Schritte mit AgentCore Observability
<a name="observability-get-started"></a>

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.

**Topics**
+ [Voraussetzungen](#prerequisites)
+ [Schritt 1: Aktivieren Sie die Transaktionssuche auf CloudWatch](#enabling-transaction-search)
+ [Schritt 2: Observability für von Amazon Bedrock AgentCore Runtime gehostete Agenten aktivieren](#enabling-observability-runtime-hosted)
+ [Schritt 3: Beobachtbarkeit für Agenten aktivieren, die nicht zu Amazon Bedrock gehören AgentCore-hosted](#enabling-observability-non-runtime-hosted)
+ [Schritt 4: Beobachten Sie Ihren Agenten mit GenAI Observability auf Amazon CloudWatch](#agentcore-observability-genai-cloudwatch)
+ [Bewährte Methoden](#best-practices)

## Voraussetzungen
<a name="prerequisites"></a>

Bevor Sie beginnen, stellen Sie sicher, dass Sie über Folgendes verfügen:
+  ** AWS Konto** mit konfigurierten Anmeldeinformationen (`aws configure`) und aktiviertem Modellzugriff auf das Foundation-Modell, das Sie verwenden möchten.
+  **Python 3.10\+ installiert**
+  **Aktivieren Sie die Transaktionssuche** bei Amazon CloudWatch. Erstbenutzer müssen die [CloudWatch Transaktionssuche](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Enable-TransactionSearch.html) nur einmal aktivieren, um Bedrock Amazon Bedrock Spans and Traces AgentCore anzuzeigen
+  **(nur für Non-runtime Agenten) Fügen Sie die OpenTelemetry Bibliothek** — Include `aws-opentelemetry-distro` (ADOT) zu Ihrer Datei requirements.txt hinzu. Wenn Sie Ihren Agenten auf AWS Lambda hosten, verwenden Sie stattdessen den [AWS Lambda-Layer für OpenTelemetry](https://aws-otel.github.io/docs/getting-started/lambda) auf der Website AWS Distro for OpenTelemetry .
+  **(nur Non-runtime Agenten)** Stellen Sie sicher, dass Ihr Framework so konfiguriert ist, dass es Traces ausgibt (z. B. `strands-agents[otel]` Paket). Manchmal müssen Sie möglicherweise den Auto-Instrumentor Ihres Agent-Frameworks einbeziehen (z. B.`opentelemetry-instrumentation-langchain`).

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

1. Agenten von Amazon Bedrock AgentCore Runtime-hosted 

1. Non-runtime gehostete Agenten

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
<a name="enabling-transaction-search"></a>

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
<a name="enable-transaction-search-api"></a>

 **Um die Transaktionssuche mithilfe der API zu aktivieren** 

1. Erstellen Sie mithilfe der CLI eine Richtlinie, die Zugriff auf Aufnahmebereiche in CloudWatch AWS Protokollen gewährt.

   Im Folgenden finden Sie ein Beispiel zur Formatierung Ihres AWS CLI-Befehls mit`PutResourcePolicy`.

   ```
   aws logs put-resource-policy --policy-name MyResourcePolicy --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Sid": "TransactionSearchXRayAccess", "Effect": "Allow", "Principal": { "Service": "xray.amazonaws.com" }, "Action": "logs:PutLogEvents", "Resource": [ "arn:partition:logs:region:account-id:log-group:aws/spans:*", "arn:partition:logs:region:account-id:log-group:/aws/application-signals/data:*" ], "Condition": { "ArnLike": { "aws:SourceArn": "arn:partition:xray:region:account-id:*" }, "StringEquals": { "aws:SourceAccount": "account-id" } } } ]}'
   ```

1. Konfigurieren Sie das Ziel von Trace-Segmenten.

   Im Folgenden finden Sie ein Beispiel zur Formatierung Ihres AWS CLI-Befehls mit`UpdateTraceSegmentDestination`.

   ```
   aws xray update-trace-segment-destination --destination CloudWatchLogs
   ```

1.  **Optional:** Konfigurieren Sie die Anzahl der zu indizierenden Bereiche.

   Konfigurieren Sie den gewünschten Stichprobenprozentsatz mit`UpdateIndexingRule`.

   ```
   aws xray update-indexing-rule --name "Default" --rule '{"Probabilistic": {"DesiredSamplingPercentage": number}}'
   ```

### Option 2: Aktivieren Sie die Transaktionssuche in der CloudWatch Konsole
<a name="enable-transaction-search-console"></a>

 **Um die Transaktionssuche in der CloudWatch Konsole zu aktivieren** 

1. Öffnen Sie die CloudWatch Konsole unter [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. Wählen Sie im Navigationsbereich unter **Setup** die Option **Einstellungen** aus.

1. Wählen Sie **Konto** und anschließend den Tab **X-Ray Traces** aus.

1. Wählen Sie im Abschnitt **Transaktionssuche** die Option **Einstellungen anzeigen** aus.

1. Wählen Sie auf der sich öffnenden Seite **Bearbeiten** aus.

1. Wählen Sie **Transaktionssuche aktivieren**.

1. Wählen Sie „**Für X-Ray Benutzer**“ und geben Sie den Prozentsatz der zu indizierenden Traces ein. Sie können 1% der Traces kostenlos indizieren und diesen Prozentsatz später an Ihre Bedürfnisse anpassen.

1. Wählen Sie **Speichern**. Warten Sie, bis **bei Ingest OpenTelemetry Spans** die **Anzeige Aktiviert** angezeigt wird, bevor Sie Traces senden.

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
<a name="enabling-observability-runtime-hosted"></a>

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](https://github.com/awslabs/amazon-bedrock-agentcore-samples/blob/main/01-tutorials/06-AgentCore-observability/01-Agentcore-runtime-hosted/Strands%20Agents/runtime_with_strands_and_bedrock_models.ipynb) 

### Erstellen Sie Ihr Agentenprojekt
<a name="create-agent-strands"></a>

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
<a name="deploy-invoke-agent"></a>

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
<a name="enabling-observability-non-runtime-hosted"></a>

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](https://github.com/awslabs/agentcore-samples/tree/main/03-integrations/agents-hosted-outside-runtime/agents-on-eks) auf der GitHub Website.

### Konfiguration AWS Umgebungsvariablen
<a name="configure-aws-environment-variables"></a>

```
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
<a name="configure-cloudwatch-logging"></a>

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
<a name="configure-opentelemetry-environment-variables"></a>

```
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.

**Anmerkung**  
Wenn Sie festlegen`OTEL_EXPORTER_OTLP_TRACES_HEADERS`, dass Spans an Ihre eigene Protokollgruppe gesendet werden, müssen Sie auch eine Amazon CloudWatch Logs-Ressourcenrichtlinie hinzufügen. Die Richtlinie muss es X-Ray (`xray.amazonaws.com`) ermöglichen, diese Protokollgruppe `logs:PutLogEvents` aufzurufen. Verwenden Sie dieselbe Richtlinie wie unter [Transaktionssuche mithilfe einer API aktivieren](#enable-transaction-search-api), und geben Sie den ARN Ihrer Protokollgruppe ein`Resource`. Ohne diese Richtlinie X-Ray können keine Spans an Ihre Protokollgruppe übermittelt werden.

### Lokal einen Agenten erstellen
<a name="create-agent-locally"></a>

```
# 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
<a name="run-agent-automatic-instrumentation"></a>

`aws-opentelemetry-distro`In Ihrer Datei requirements.txt wird der `opentelemetry-instrument` Befehl:
+ Laden Sie Ihre OTEL-Konfiguration aus Ihren Umgebungsvariablen
+ Automatisches Instrumentieren von Strands, Amazon Bedrock-Anrufen, Agententools und Datenbanken sowie anderen Anfragen des Agenten
+ Senden Sie Spuren an CloudWatch
+ Ermöglicht es Ihnen, den Entscheidungsprozess des Agenten im GenAI Observability Dashboard zu visualisieren

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](https://aws-otel.github.io/docs/getting-started/lambda) 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.

**ADOT Collector wird für die Agentenbeobachtbarkeit nicht unterstützt**  
Der ADOT Collector wird für die Beobachtbarkeit durch Agenten nicht unterstützt. Um Telemetrie von einem außerhalb der AgentCore Laufzeit gehosteten Agenten zu senden, müssen Sie entweder das ADOT SDK oder den AWS Lambda Layer for verwenden. OpenTelemetry

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](#configure-opentelemetry-environment-variables) 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
<a name="agentcore-observability-genai-cloudwatch"></a>

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

### Beobachten Sie Ihren Agenten
<a name="agentcore-observability-observe"></a>

1. Öffnen Sie [GenAI Observability](https://console.aws.amazon.com/cloudwatch/home#gen-ai-observability) auf der Konsole CloudWatch 

1. Sie können die Daten zu Modellaufrufen und Agenten auf Bedrock Amazon Bedrock AgentCore im Dashboard einsehen.

1. Auf der Registerkarte Bedrock Agentcore können Sie die Agentenansicht, die Sitzungsansicht und die Traces-Ansicht aufrufen.

1. In der Agentenansicht werden all Ihre Agenten aufgeführt, die aktiv sind und nicht. Sie können auch einen Agenten auswählen und weitere Details wie Laufzeitmetriken, Sitzungen und Traces für einen Agenten anzeigen.

1. Auf der Registerkarte „**Sitzungsansicht**“ können Sie durch alle Sitzungen navigieren, die den Agenten zugeordnet sind.

1. Auf der Registerkarte **Trace-Ansicht** können Sie sich die Traces und Span-Informationen für Agenten ansehen. Erkunden Sie auch die Trace-Trajektorie und den Zeitplan, indem Sie einen Trace auswählen.

### Logs anzeigen CloudWatch
<a name="view-logs-cloudwatch"></a>

 **Um Logs einzusehen CloudWatch** 

1. Öffnen Sie die [CloudWatch -Konsole](https://console.aws.amazon.com/cloudwatch/). 

1. Erweitern Sie im linken Navigationsbereich die Option **Protokolle** und wählen Sie **Protokollgruppen** 

1. Suchen Sie nach der Protokollgruppe Ihres Agenten:
   + Speicherort der Standardprotokolle (stdout/stderr): `/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>/[runtime-logs] <UUID>` 
   + Strukturierte Protokolle von OTEL: `/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>/runtime-logs` 

### Spuren und Spannweiten anzeigen
<a name="view-traces-spans"></a>

 **Um Spuren und Spannweiten anzuzeigen** 

1. Öffnen Sie die [CloudWatch -Konsole](https://console.aws.amazon.com/cloudwatch/). 

1. Wählen Sie in der linken Navigationsleiste **Transaktionssuche** aus

1. Speicherort: der `spans` Protokollstream in der Protokollgruppe des Agenten (`/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>`) oder der `default` Protokollstream in der `aws/spans` Protokollgruppe für Agenten, die das gemeinsame Span-Ziel verwenden

1. Filtern Sie nach dem Dienstnamen oder anderen Kriterien

1. Wählen Sie einen Trace aus, um das detaillierte Ausführungsdiagramm anzuzeigen

### Anzeigen von -Metriken
<a name="view-metrics"></a>

 **Um Metriken anzuzeigen** 

1. Öffnen Sie die [CloudWatch -Konsole](https://console.aws.amazon.com/cloudwatch/). 

1. Wählen Sie im linken Navigationsbereich **Metriken** aus

1. Navigieren Sie zum `bedrock-agentcore` Namespace

1. Erkunden Sie die verfügbaren Metriken

## Bewährte Methoden
<a name="best-practices"></a>

1.  **Einfach anfangen, dann erweitern** — Die von Amazon Bedrock bereitgestellte Standard-Observability AgentCore erfasst automatisch die meisten wichtigen Kennzahlen, einschließlich Modellaufrufen, Token-Nutzung und Toolausführung.

1.  **Für die Entwicklungsphase konfigurieren** — Passen Sie Ihre Observability-Konfiguration an Ihre aktuelle Entwicklungsphase an und passen Sie sie schrittweise an.

1.  **Verwenden Sie eine einheitliche Benennung** — Legen Sie von Anfang an Namenskonventionen für Dienste, Bereiche und Attribute fest

1.  **Sensible Daten filtern** — Verhindern Sie die Offenlegung vertraulicher Informationen, indem Sie sensible Daten aus Observability-Attributen und Payloads herausfiltern.

1.  **Benachrichtigungen einrichten** — Konfigurieren Sie CloudWatch Alarme, um Sie über potenzielle Probleme zu informieren, bevor sie sich auf Benutzer auswirken