# Google ADK
此頁面說明如何檢測 [Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/) 代理程式、如何識別範圍，以及如何擷取評估欄位。
**主題**
+ [檢測您的代理程式](#google-adk-instrument)
+ [如何識別跨度](#google-adk-span-identification)
+ [如何擷取評估欄位](#google-adk-extraction)
+ [從事件記錄](#google-adk-extraction-event-records)
+ [從跨度屬性](#google-adk-extraction-attributes)
+ [範例跨越事件記錄](#google-adk-examples-with)
+ [沒有事件記錄的範例範圍](#google-adk-examples-without)
## 檢測您的代理程式
您可以使用 **OpenInference** 檢測程式庫 () 檢測 Google ADK 代理程式`openinference-instrumentation-google-adk`。此程式庫會在 Amazon Bedrock AgentCore Evaluations `openinference.instrumentation.google_adk`讀取的範圍名稱 下發出遙測。
當您的代理程式使用 AWS Distro for OpenTelemetry (ADOT) 執行時，例如在 Amazon Bedrock AgentCore 執行期，您不需要新增明確的檢測程式碼。將檢測程式庫新增至專案的相依性已足夠。ADOT 在啟動時發現它並自動啟用它。
將檢測程式庫新增至您的相依性。
**注意**
使用 版本 `0.1.13` 或更新版本。這是使用 評估服務測試的最早版本。
`requirements.txt`:
```
openinference-instrumentation-google-adk>=0.1.13
```
`pyproject.toml`:
```
[project]
dependencies = [
"openinference-instrumentation-google-adk>=0.1.13",
]
```
**注意**
檢測是設定可觀測性的一個步驟。若要匯出遙測資料進行評估，請完成設定[可觀測性中的完整設定](supported-frameworks.md#supported-frameworks-setup)。
## 如何識別跨度
Google ADK 使用 OpenInference 慣例進行檢測，因此 AgentCore Evaluations 會使用 `openinference.span.kind` 屬性對範圍進行分類。
| 跨度類型 | 識別屬性 |
| --- | --- |
| 叫用代理程式 | `openinference.span.kind` = `CHAIN`或 `AGENT` |
| 執行工具 | `openinference.span.kind` = `TOOL` |
| Inference | `openinference.span.kind` = `LLM` |
Google ADK 發出巢狀範圍樹：外部範圍 `invocation` (`CHAIN`) 會包裝範圍 `agent_run` (`AGENT`)，進而包裝 `call_llm`(`LLM`) 和 `execute_tool`(`TOOL`) 範圍。外部`CHAIN`跨度帶有使用者提示；AgentCore Evaluations 將其用作調用代理程式跨度。
## 如何擷取評估欄位
Google ADK 以 Gemini 內容格式包裝其對話內容。使用者提示會巢狀化在`new_message`物件下做為 `{"new_message": {"parts": [{"text": "…"}], "role": "user"}}`，而代理程式回應則會巢狀化在`content`物件下做為 `{"content": {"parts": [{"text": "…"}], "role": "model"}}`。AgentCore Evaluations 會取消包裝這些結構，並將`parts`文字與換行聯結。工具定義會以序列化 Gemini 請求的形式抵達；AgentCore Evaluations 會從 讀取可用的工具`config.tools[].function_declarations[]`。
此內容的位置取決於收集遙測的方式。在這兩種情況下，識別屬性 (`openinference.span.kind`) 位於跨度。如需詳細資訊，請參閱[跨度、事件記錄和遙測訊號](supported-frameworks-telemetry.md)。
### 從事件記錄
分割遙測時，AgentCore Evaluations 會從與每個範圍相關的事件記錄中讀取內容：
+ **使用者提示**：從叫用客服人員的事件記錄，在 中`body.input`。AgentCore Evaluations 會取消包裝`new_message.parts`文字。
+ **客服人員回應**：在 中調用客服人員範圍的事件記錄`body.output`。AgentCore Evaluations 會取消包裝`content.parts`文字。
+ **工具呼叫**：執行工具範圍上 `tool.name` 屬性的工具名稱。工具引數和結果來自 `body.input`和 中的跨度事件記錄`body.output`。
如需範例，請參閱[範例跨越事件記錄](#google-adk-examples-with)。
### 從跨度屬性
未分割遙測時，相同的內容會保留在跨度上做為屬性：
+ **使用者提示**和**客服人員回應**：調用客服人員範圍`output.value`上的 `input.value`和 。AgentCore Evaluations 會取消包裝 `new_message.parts`和 `content.parts` 文字。
+ **工具呼叫**：執行工具範圍`output.value`上來自 的工具名稱`tool.name`，以及來自 和 的引數`input.value`和結果。
如需範例，請參閱[沒有事件記錄的範例跨度](#google-adk-examples-without)。
## 範例跨越事件記錄
分割遙測時，範圍會攜帶識別屬性，而內容會存在於相關事件記錄中。下列範例來自部署在 Amazon Bedrock AgentCore 執行期上的 Google ADK 行程規劃代理程式。
**注意**
這些範例不是完整的跨度。它們會顯示來自實際客服人員互動的代表性資料，省略一些欄位，並截斷長值以保證可讀性。
**Example**
外部範圍上的`openinference.span.kind`屬性 `invocation` (`CHAIN`) 會將此識別為叫用代理程式範圍。跨度不帶任何對話內容；它存在於相互關聯的事件記錄中。
```
{
"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"
}
}
```
相關事件記錄會承載對話。使用者提示在 下巢狀化`new_message.parts`，代理程式回應在 下巢狀化`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\"}"
}
]
}
}
}
```
`openinference.span.kind` 屬性 (`TOOL`) 將此識別為執行工具範圍； `tool.name`會保留工具名稱。工具引數和結果會即時存在於相關事件記錄中。
```
{
"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\": [ ... ]}}"
}
]
}
}
}
```
跨度上的`openinference.span.kind`屬性 `call_llm` (`LLM`) 會將此識別為推論跨度。它攜帶模型中繼資料，以及在索引`llm.input_messages. `和`llm.output_messages.`屬性中，模型呼叫的訊息。
```
{
"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"
}
}
```
## 沒有事件記錄的範例範圍
未分割遙測時，相同的內容會保留在跨度屬性上，而且不會產生單獨的事件記錄。下列範例來自 Google ADK 旅行規劃代理程式。
**注意**
這些範例不是完整的跨度。它們會顯示來自實際客服人員互動的代表性資料，省略一些欄位，並截斷長值以保證可讀性。
**Example**
`input.value` 屬性會保留使用者提示字元 （巢狀在 下`new_message.parts`)，而`output.value`屬性會保留客服人員回應 （巢狀在 下`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"
}
}
```
`input.value` 屬性會保留工具引數，而 `output.value` 屬性則會保留工具結果。
```
{
"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"
}
}
```
跨度上的`openinference.span.kind`屬性 `call_llm` (`LLM`) 會將此識別為推論跨度。模型呼叫的訊息會內嵌在索引`llm.input_messages. `和`llm.output_messages.`屬性上。
```
{
"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"
}
}
```