Instrumentieren Sie Ihren Agenten Wie werden Spannweiten identifiziert Wie werden Bewertungsfelder extrahiert Beispiel für Zeitspannen mit Ereignisdatensätzen Beispiel: Spans ohne Ereignisdatensätze

Google ADK

Auf dieser Seite wird erklärt, wie ein Google Agent Development Kit (ADK) -Agenten instrumentiert wird, wie Spans identifiziert werden und wie Bewertungsfelder extrahiert werden.

Topics

Instrumentieren Sie Ihren Agenten
Wie werden Spannweiten identifiziert
Wie werden Bewertungsfelder extrahiert
- Aus Ereignisaufzeichnungen
- Aus Span-Attributen
Beispiel für Spans mit Ereignisdatensätzen
Beispiel für Spans ohne Ereignisdatensätze

Instrumentieren Sie Ihren Agenten

Sie können einen Google ADK-Agenten mit der OpenInferenceInstrumentierungsbibliothek (openinference-instrumentation-google-adk) instrumentieren. Diese Bibliothek sendet Telemetrie unter dem Bereichsnamen ausopeninference.instrumentation.google_adk, den Amazon Bedrock AgentCore Evaluations liest.

Wenn Ihr Agent mit AWS Distro for OpenTelemetry (ADOT) ausgeführt wird, z. B. auf Amazon Bedrock AgentCore Runtime, müssen Sie keinen expliziten Instrumentierungscode hinzufügen. Es reicht aus, die Instrumentierungsbibliothek zu den Abhängigkeiten Ihres Projekts hinzuzufügen. ADOT erkennt es beim Start und aktiviert es automatisch.

Fügen Sie die Instrumentierungsbibliothek zu Ihren Abhängigkeiten hinzu.

Anmerkung

Verwenden Sie Version 0.1.13 oder höher. Dies ist die früheste Version, die mit dem Evaluierungsservice getestet wurde.

requirements.txt:


openinference-instrumentation-google-adk>=0.1.13

pyproject.toml:


[project]
dependencies = [
    "openinference-instrumentation-google-adk>=0.1.13",
]

Anmerkung

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

Wie werden Spannweiten identifiziert

Google ADK ist mit dieser OpenInference Konvention ausgestattet, sodass AgentCore Evaluations die Spannweiten anhand des Attributs klassifiziert. openinference.span.kind

Art der Spanne	Identifizierendes Attribut
Agent aufrufen	`openinference.span.kind`= oder `CHAIN` `AGENT`
Tool ausführen	`openinference.span.kind` = `TOOL`
Inferenz	`openinference.span.kind` = `LLM`

Google ADK gibt einen verschachtelten Span-Baum aus: Ein äußerer invocation Span (CHAIN) umschließt einen agent_run Span (AGENT), der wiederum die Spannen () und call_llm (LLM) umschließt. execute_tool TOOL Der äußere CHAIN Bereich enthält die Benutzereingabeaufforderung; AgentCore Evaluations verwendet ihn als Span für den Aufruf des Agenten.

Wie werden Bewertungsfelder extrahiert

Google ADK verpackt seinen Konversationsinhalt im Gemini-Inhaltsformat. Die Benutzeraufforderung ist unter einem new_message Objekt als verschachtelt{"new_message": {"parts": [{"text": "…"}], "role": "user"}}, und die Agentenantwort ist unter einem Objekt als verschachtelt. content {"content": {"parts": [{"text": "…"}], "role": "model"}} AgentCore Evaluations entschlüsselt diese Strukturen und verbindet den Text mit Zeilenumbrüchen. parts Die Werkzeugdefinitionen kommen als serialisierte Gemini-Anfrage an; AgentCore Evaluations liest die verfügbaren Tools aus. config.tools[].function_declarations[]

Der Speicherort dieser Inhalte hängt davon ab, wie die Telemetrie erfasst wurde. Das identifizierende Attribut (openinference.span.kind) befindet sich in beiden Fällen auf der Spanne. Weitere Informationen finden Sie unter Spans, Ereignisaufzeichnungen und Telemetriesignale.

Aus Ereignisaufzeichnungen

Wenn die Telemetrie aufgeteilt wird, liest AgentCore Evaluations Inhalte aus den Ereignisdatensätzen, die den einzelnen Bereichen zugeordnet sind:

Benutzeraufforderung: aus dem Ereignisdatensatz des Invoke Agent Span, in. body.input AgentCore Evaluationen entpacken den Text. new_message.parts
Antwort des Agenten: aus dem Ereignisdatensatz des Invoke Agent Span, in. body.output AgentCore Evaluationen entpacken den Text. content.parts
Werkzeugaufruf: Der Werkzeugname aus dem tool.name Attribut im Bereich des Ausführungswerkzeugs. Die Werkzeugargumente und das Ergebnis stammen aus dem Ereignisdatensatz dieser Spanne, in body.input undbody.output.

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

Aus Span-Attributen

Wenn die Telemetrie nicht aufgeteilt wird, verbleibt derselbe Inhalt als Attribute im Bereich:

Benutzeraufforderung und Agentenantwort: von input.value und nach output.value dem Agentenaufruf. AgentCore Evaluationen entpacken den new_message.parts Endtext. content.parts
Werkzeugaufruf: der Werkzeugname von tool.name sowie die Argumente und das Ergebnis von input.value und im output.value Bereich des Ausführungswerkzeugs.

Beispiele finden Sie unter Beispielbereiche 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 Google ADK-Reiseplanungsagenten, der auf Amazon Bedrock Runtime bereitgestellt wurde. AgentCore

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 openinference.span.kind Attribut (CHAIN) im äußeren invocation Bereich kennzeichnet dies als Span für den Aufruf des Agenten. Der Bereich enthält keinen Konversationsinhalt; er befindet sich im korrelierten Ereignisdatensatz.


{
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "spanId": "70f2e87a30c34420",
  "name": "invocation",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.14"
  },
  "attributes": {
    "openinference.span.kind": "CHAIN",
    "input.mime_type": "application/json",
    "output.mime_type": "application/json",
    "user.id": "default_user",
    "session.id": "sea-nyc-trip-2-turns-google-adk-adot"
  },
  "status": {
    "code": "OK"
  }
}

Der Datensatz des korrelierten Ereignisses enthält die Konversation. Die Benutzeraufforderung ist untergeordnetnew_message.parts, und die Antwort des Agenten ist untergeordnet. content.parts


{
  "spanId": "70f2e87a30c34420",
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "scope": {
    "name": "openinference.instrumentation.google_adk"
  },
  "body": {
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "{\"new_message\": {\"parts\": [{\"text\": \"Hey, how can you help me\"}], \"role\": \"user\"}, \"state_delta\": null, \"run_config\": null}"
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "{\"model_version\": \"gemini-2.5-flash\", \"content\": {\"parts\": [{\"text\": \"I can help you with your travel plans! I can:\\n- Search and book flights\\n- Find and book hotels\\n- Suggest and book activities\"}], \"role\": \"model\"}, \"finish_reason\": \"STOP\"}"
        }
      ]
    }
  }
}

Execute tool span

Das openinference.span.kind Attribut (TOOL) identifiziert dies als einen Bereich für das Ausführungswerkzeug; es tool.name enthält den Namen des Tools. Die Werkzeugargumente und das Ergebnis befinden sich im korrelierten Ereignisdatensatz.


{
  "traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
  "spanId": "9028a8dd94943456",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.14"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.type": "FunctionTool",
    "gen_ai.tool.call.id": "adk-12345678-1234-1234-1234-123456789012",
    "tool.name": "search_flights",
    "tool.parameters": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "session.id": "sea-nyc-trip-2-turns-google-adk-adot"
  },
  "status": {
    "code": "OK"
  }
}


{
  "spanId": "9028a8dd94943456",
  "traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
  "scope": {
    "name": "openinference.instrumentation.google_adk"
  },
  "body": {
    "input": {
      "messages": [
        { "role": "user", "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}" }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": "{\"id\": \"adk-12345678-...\", \"name\": \"search_flights\", \"response\": {\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}}"
        }
      ]
    }
  }
}

Inference span

Das openinference.span.kind Attribut (LLM) in der call_llm Spanne identifiziert diese als Inferenzspanne. Es enthält die Modell-Metadaten und in den Indizes llm.input_messages. und llm.output_messages. Attributen die Nachrichten für den Modellaufruf.


{
  "traceId": "6a387ee61078243c1cc455ed45c6c313",
  "spanId": "1c4e5f8a2b9d0e73",
  "name": "call_llm",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.14"
  },
  "attributes": {
    "openinference.span.kind": "LLM",
    "gen_ai.operation.name": "generate_content",
    "gen_ai.request.model": "gemini-2.5-flash",
    "llm.model_name": "gemini-2.5-flash",
    "llm.input_messages.0.message.role": "system",
    "llm.input_messages.1.message.role": "user",
    "llm.input_messages.1.message.contents.0.message_content.text": "Hey, how can you help me",
    "llm.output_messages.0.message.role": "model",
    "llm.output_messages.0.message.contents.0.message_content.text": "I can help you plan your trip ...",
    "session.id": "sea-nyc-trip-2-turns-google-adk-adot"
  },
  "status": {
    "code": "OK"
  }
}

Beispiel: Spans ohne Ereignisdatensätze

Wenn die Telemetrie nicht aufgeteilt wird, verbleibt derselbe Inhalt in den Span-Attributen und es wird kein separater Ereignisdatensatz erstellt. Die folgenden Beispiele stammen von einem Google ADK-Reiseplanungsbüro.

Anmerkung

Beispiel

Invoke agent span

Das input.value Attribut enthält die Benutzeraufforderung (verschachtelt unternew_message.parts) und das output.value Attribut enthält die Antwort des Agenten (verschachtelt unter). content.parts


{
  "traceId": "6a4de7b85e61747e6b568a1f4768e89d",
  "spanId": "31ea3d5882dac680",
  "name": "invocation",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.13"
  },
  "attributes": {
    "openinference.span.kind": "CHAIN",
    "input.value": "{\"user_id\": \"test_user\", \"session_id\": \"sea-nyc-trip-2-turns-google-adk-unified\", \"new_message\": {\"parts\": [{\"text\": \"Hey, how can you help me\"}], \"role\": \"user\"}}",
    "input.mime_type": "application/json",
    "output.value": "{\"model_version\": \"gemini-2.5-flash\", \"content\": {\"parts\": [{\"text\": \"I can help you plan your trip! I can:\\n- Search and book flights\\n- Find and book hotels\\n- Suggest and book activities\"}], \"role\": \"model\"}, \"finish_reason\": \"STOP\"}",
    "output.mime_type": "application/json",
    "session.id": "sea-nyc-trip-2-turns-google-adk-unified"
  },
  "status": {
    "code": "OK"
  }
}

Execute tool span

Das input.value Attribut enthält die Werkzeugargumente und das output.value Attribut enthält das Werkzeugergebnis.


{
  "traceId": "6a4de7c376913db82e6f0f336a16731d",
  "spanId": "b64c37adefae74f0",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.13"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.call.id": "adk-12345678-1234-1234-1234-123456789012",
    "tool.name": "search_flights",
    "tool.parameters": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "input.value": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "output.value": "{\"id\": \"adk-12345678-...\", \"name\": \"search_flights\", \"response\": {\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}}",
    "session.id": "sea-nyc-trip-2-turns-google-adk-unified"
  },
  "status": {
    "code": "OK"
  }
}

Inference span

Das openinference.span.kind Attribut (LLM) in der call_llm Spanne identifiziert diese als Inferenzspanne. Die Nachrichten für den Modellaufruf befinden sich direkt in den indizierten Attributen llm.input_messages. und llm.output_messages. Attributen.


{
  "traceId": "6a4de7b85e61747e6b568a1f4768e89d",
  "spanId": "2d5f6a9b3c0e1f84",
  "name": "call_llm",
  "kind": "INTERNAL",
  "scope": {
    "name": "openinference.instrumentation.google_adk",
    "version": "0.1.13"
  },
  "attributes": {
    "openinference.span.kind": "LLM",
    "gen_ai.operation.name": "generate_content",
    "gen_ai.request.model": "gemini-2.5-flash",
    "llm.model_name": "gemini-2.5-flash",
    "llm.input_messages.0.message.role": "system",
    "llm.input_messages.1.message.role": "user",
    "llm.input_messages.1.message.contents.0.message_content.text": "Hey, how can you help me",
    "llm.output_messages.0.message.role": "model",
    "llm.output_messages.0.message.contents.0.message_content.text": "I can help you plan your trip ...",
    "session.id": "sea-nyc-trip-2-turns-google-adk-unified"
  },
  "status": {
    "code": "OK"
  }
}

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

LlamaIndex

Claude Agent SDK