View a markdown version of this page

Strands Agents - Amazon Grundgestein AgentCore
Instrumentieren Sie Ihren AgentenWie werden Spannweiten identifiziertWie werden Bewertungsfelder extrahiertBeispiel für Zeitspannen mit EreignisdatensätzenBeispiel für Zeiträume ohne Ereignisdatensätze

Strands Agents

Auf dieser Seite wird erklärt, wie ein Strands Agents-Agent instrumentiert wird, wie Spans identifiziert werden und wie Bewertungsfelder extrahiert werden.

Topics

Instrumentieren Sie Ihren Agenten

Das Strands Agents SDK enthält integrierte Telemetrie und erfordert keine zusätzliche Instrumentierungsbibliothek. Es erzeugt Spans und Ereignisdatensätze unter dem Bereichsnamen. strands.telemetry.tracer Bei der Bereitstellung auf Amazon Bedrock AgentCore Runtime mit der AWS Distribution for OpenTelemetry (ADOT) fügt die Runtime das session.id Attribut ein und exportiert automatisch Spans und Event-Datensätze.

Anmerkung

Die Instrumentierung ist ein Schritt bei der Einrichtung der Beobachtbarkeit. Um Telemetrie zur Auswertung zu exportieren, schließen Sie die vollständigen Einstellungen unter Beobachtbarkeit einrichten ab.

Wie werden Spannweiten identifiziert

Strands legt das gen_ai.operation.name Attribut für jeden Bereich fest. Der Bewertungsdienst verwendet dieses Attribut, um Bereiche zu klassifizieren:

Art der Spanne Identifizierendes Attribut Beispiel für einen Spannamen

Agent aufrufen

gen_ai.operation.name = invoke_agent

invoke_agent TravelAgent

Tool ausführen

gen_ai.operation.name = execute_tool

execute_tool search_flights

Inferenz

gen_ai.operation.name = chat

chat

Wie werden Bewertungsfelder extrahiert

Der Speicherort der Konversationsinhalte hängt davon ab, wie Telemetriedaten erfasst wurden. Wenn ADOT die Telemetrie aufteilt, befindet sich der Inhalt in einem separaten Ereignisdatensatz. Wenn die Telemetrie nicht aufgeteilt wird, verbleibt der Inhalt als Inline-Ereignisse in der Spanne. Weitere Informationen finden Sie unter Spans, Ereignisdatensätze und Telemetriesignale. Das identifizierende Attribut (gen_ai.operation.name) befindet sich in beiden Fällen auf der Spanne.

Aus Ereignisaufzeichnungen

Wenn die Telemetrie aufgeteilt wird, liest der Dienst Inhalte aus dem Ereignisdatensatz, der jeder Spanne zugeordnet ist:

  • Benutzeraufforderung: Aus den Eingabenachrichten des Agenten (input.messages) wird der Inhalt der Nachricht mit einer Benutzerrolle angezeigt.

  • Antwort des Agenten: aus den Agentenausgangsnachrichten (output.messages) der Inhalt der Nachricht mit der Rolle eines Assistenten.

  • Werkzeugaufruf: Der Werkzeugname aus dem gen_ai.tool.name Attribut im Bereich des Ausführungswerkzeugs. Die Werkzeugargumente und das Ergebnis stammen aus dem Ereignisdatensatz (inputundoutput) dieser Spanne.

Beispiele finden Sie unter Beispiel für Spans mit Ereignisdatensätzen.

Aus Inline-Span-Ereignissen

Wenn die Telemetrie nicht aufgeteilt wird, wird derselbe Inhalt in Inline-Span-Ereignissen anstelle eines separaten Ereignisdatensatzes übertragen:

  • Benutzeraufforderung: aus dem gen_ai.user.message Ereignis, das content Attribut.

  • Antwort des Agenten: aus dem gen_ai.choice Ereignis, das message Attribut.

  • Werkzeugaufruf: Der Werkzeugname aus dem gen_ai.tool.name Attribut im Span. Die Werkzeugargumente stammen aus dem gen_ai.tool.message Ereignis, und das Ergebnis stammt aus dem gen_ai.choice Ereignis.

Beispiele finden Sie unter Beispiel für Spans ohne Ereignisdatensätze.

Beispiel für Zeitspannen mit Ereignisdatensätzen

Wenn die Telemetrie aufgeteilt wird, enthält die Spanne die identifizierenden Attribute und der Inhalt befindet sich in einem korrelierten Ereignisdatensatz. Die folgenden Beispiele stammen von einem Reiseplanungsagenten von Strands, der auf Amazon AgentCore Bedrock Runtime eingesetzt wurde.

Anmerkung

Bei diesen Beispielen handelt es sich nicht um vollständige Zeitspannen. Sie zeigen repräsentative Daten aus einer echten Agenteninteraktion, wobei einige Felder weggelassen und lange Werte aus Gründen der Lesbarkeit gekürzt wurden.

Beispiel
Invoke agent span

Das gen_ai.operation.name Attribut (invoke_agent) identifiziert dies als eine Spanne für den Aufruf-Agenten. Das gen_ai.agent.tools Attribut listet die Tools auf, die dem Agenten zur Verfügung stehen.

{
  "traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
  "spanId": "d24936b8989b6d42",
  "parentSpanId": "0ff3498548044e4b",
  "name": "invoke_agent TravelAgent",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands.telemetry.tracer",
    "version": ""
  },
  "startTimeUnixNano": 1776929864011990383,
  "endTimeUnixNano": 1776929869634304466,
  "durationNano": 5622314083,
  "attributes": {
    "gen_ai.operation.name": "invoke_agent",
    "gen_ai.system": "strands-agents",
    "gen_ai.agent.name": "TravelAgent",
    "gen_ai.request.model": "us.anthropic.claude-sonnet-4-20250514-v1:0",
    "gen_ai.usage.input_tokens": 983,
    "gen_ai.usage.output_tokens": 232,
    "gen_ai.usage.total_tokens": 1215,
    "gen_ai.agent.tools": "[\"search_flights\", \"book_flight\", \"search_hotels\", \"book_hotel\", \"search_activities\", \"book_activity\"]",
    "session.id": "sea-nyc-trip-2-turns-adot_v17-20260423003743"
  },
  "status": {
    "code": "OK"
  }
}

Der korrelierte Ereignisdatensatz enthält den Inhalt der Konversation. Die Benutzeraufforderung ist die Nachricht in der Benutzerrolleinput.messages, und die Antwort des Agenten ist die Nachricht der Assistentenrolle in. output.messages

{
  "spanId": "d24936b8989b6d42",
  "traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
  "scope": {
    "name": "strands.telemetry.tracer"
  },
  "body": {
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "Hey, how can you help me"
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": {
            "message": "Hi there! I'm your travel planning assistant ...",
            "finish_reason": "end_turn"
          }
        }
      ]
    }
  }
}
Execute tool span

Das gen_ai.operation.name Attribut (execute_tool) identifiziert dies als einen Bereich für das Ausführungstool. Das gen_ai.tool.name Attribut enthält den Namen des Werkzeugs.

{
  "traceId": "69e9cc4d132b180909ba49f613f273dd",
  "spanId": "fff785ce12d6fda8",
  "parentSpanId": "96915bf5ecc78743",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands.telemetry.tracer",
    "version": ""
  },
  "startTimeUnixNano": 1776929872258292842,
  "endTimeUnixNano": 1776929872259611427,
  "durationNano": 1318585,
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.call.id": "tooluse_hiWwdtThuD67G5cK8cp5mj",
    "gen_ai.tool.status": "success",
    "gen_ai.tool.description": "Search for available flights between cities.",
    "session.id": "sea-nyc-trip-2-turns-adot_v17-20260423003743"
  },
  "status": {
    "code": "OK"
  }
}

Der korrelierte Ereignisdatensatz enthält die Werkzeugeingabe (Argumente) und die Ausgabe (Ergebnis).

{
  "spanId": "fff785ce12d6fda8",
  "traceId": "69e9cc4d132b180909ba49f613f273dd",
  "scope": {
    "name": "strands.telemetry.tracer"
  },
  "body": {
    "input": {
      "messages": [
        {
          "role": "tool",
          "content": {
            "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
            "role": "tool",
            "id": "tooluse_hiWwdtThuD67G5cK8cp5mj"
          }
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": {
            "message": "[{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
            "id": "tooluse_hiWwdtThuD67G5cK8cp5mj"
          }
        }
      ]
    }
  }
}

Beispiel für Zeiträume ohne Ereignisdatensätze

Wenn die Telemetrie nicht aufgeteilt wird, wird derselbe Inhalt in Inline-Span-Ereignissen innerhalb der Spanne übertragen, ohne dass ein separater Ereignisdatensatz vorhanden ist. Die folgenden Beispiele stammen von einem Reiseplanungsbüro von Strands.

Anmerkung

Bei diesen Beispielen handelt es sich nicht um vollständige Zeitspannen. Sie zeigen repräsentative Daten aus einer echten Agenteninteraktion, wobei einige Felder weggelassen und lange Werte aus Gründen der Lesbarkeit gekürzt wurden.

Beispiel
Invoke agent span

Das gen_ai.user.message Ereignis enthält die Benutzeraufforderung und das gen_ai.choice Ereignis enthält die Antwort des Agenten.

{
  "traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
  "spanId": "d2ee0e4765cc773e",
  "name": "invoke_agent TravelAgent",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands.telemetry.tracer"
  },
  "attributes": {
    "gen_ai.operation.name": "invoke_agent",
    "gen_ai.agent.name": "TravelAgent",
    "session.id": "sea-nyc-trip-2-turns-unified"
  },
  "events": [
    {
      "name": "gen_ai.user.message",
      "attributes": {
        "content": "[{\"text\": \"Hey, how can you help me\"}]"
      }
    },
    {
      "name": "gen_ai.choice",
      "attributes": {
        "message": "Hi there! I'm your travel planning assistant ...",
        "finish_reason": "end_turn"
      }
    }
  ]
}
Execute tool span

Das gen_ai.tool.message Ereignis enthält die Tool-Argumente und das gen_ai.choice Ereignis enthält das Tool-Ergebnis.

{
  "traceId": "69e9cc4d132b180909ba49f613f273dd",
  "spanId": "0a988e27758ebb53",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands.telemetry.tracer"
  },
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.call.id": "tooluse_JuGterOaZfQV2c55Rp3S7C",
    "gen_ai.tool.status": "success",
    "session.id": "sea-nyc-trip-2-turns-unified"
  },
  "events": [
    {
      "name": "gen_ai.tool.message",
      "attributes": {
        "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
        "role": "tool",
        "id": "tooluse_JuGterOaZfQV2c55Rp3S7C"
      }
    },
    {
      "name": "gen_ai.choice",
      "attributes": {
        "message": "[{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
        "id": "tooluse_JuGterOaZfQV2c55Rp3S7C"
      }
    }
  ]
}