# Google ADK
Auf dieser Seite wird erklärt, wie ein [Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/) -Agenten instrumentiert wird, wie Spans identifiziert werden und wie Bewertungsfelder extrahiert werden.
**Topics**
+ [Instrumentieren Sie Ihren Agenten](#google-adk-instrument)
+ [Wie werden Spannweiten identifiziert](#google-adk-span-identification)
+ [Wie werden Bewertungsfelder extrahiert](#google-adk-extraction)
+ [Aus Ereignisaufzeichnungen](#google-adk-extraction-event-records)
+ [Aus Span-Attributen](#google-adk-extraction-attributes)
+ [Beispiel für Spans mit Ereignisdatensätzen](#google-adk-examples-with)
+ [Beispiel für Spans ohne Ereignisdatensätze](#google-adk-examples-without)
## Instrumentieren Sie Ihren Agenten
Sie können einen Google ADK-Agenten mit der **OpenInference**Instrumentierungsbibliothek (`openinference-instrumentation-google-adk`) instrumentieren. Diese Bibliothek sendet Telemetrie unter dem Bereichsnamen aus`openinference.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](supported-frameworks.md#supported-frameworks-setup) 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](supported-frameworks-telemetry.md).
### 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` und`body.output`.
Beispiele finden Sie unter [Beispiel für Spans mit Ereignisdatensätzen](#google-adk-examples-with).
### 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](#google-adk-examples-without).
## 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.
**Example**
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 untergeordnet`new_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\"}"
}
]
}
}
}
```
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\": [ ... ]}}"
}
]
}
}
}
```
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**
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.
**Example**
Das `input.value` Attribut enthält die Benutzeraufforderung (verschachtelt unter`new_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"
}
}
```
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"
}
}
```
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"
}
}
```