# 谷歌 ADK
本页介绍如何检测 [Google 代理开发套件 (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-instrumentation-google-adk`) 对 Google ADK 代理进行**OpenInference**检测。该库以作用域名称发射遥测数据，Amazon Bedrock AgentCore 评估读取该名称`openinference.instrumentation.google_adk`。
当您的代理与 AWS 发行版 OpenTelemetry (ADOT) 一起运行时，例如在 Amazon Bedrock AgentCore Runtime 上，您无需添加显式的检测代码。将仪器库添加到项目的依赖项中就足够了。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 评估使用该属性对跨度进行分类。`openinference.span.kind`
| 跨度类型 | 识别属性 |
| --- | --- |
| 调用代理 | `openinference.span.kind`= `CHAIN` 或 `AGENT` |
| 执行工具 | `openinference.span.kind` = `TOOL` |
| 推理 | `openinference.span.kind` = `LLM` |
Google ADK 会发出一个嵌套的跨度树：外部`invocation`跨度 (`CHAIN`) 包裹一个 sp `agent_run` an (`AGENT`)，它反过来封装 `call_llm` (`LLM`) 和 `execute_tool` () 跨度。`TOOL`外部`CHAIN`跨度带有用户提示符； AgentCore 评估使用它作为调用代理跨度。
## 如何提取评估字段
Google ADK 以 Gemini 内容格式封装其对话内容。用户提示嵌套在`new_message`对象下方为`{"new_message": {"parts": [{"text": "…"}], "role": "user"}}`，代理响应嵌套在`content`对象之下`{"content": {"parts": [{"text": "…"}], "role": "model"}}`。 AgentCore 评估会解开这些结构的包装，并用换行符连接`parts`文本。工具定义以序列化的 Gemini 请求的形式出现； AgentCore 评估从`config.tools[].function_declarations[]`中读取可用工具。
这些内容的位置取决于遥测数据的收集方式。在这两种情况下，标识属性 (`openinference.span.kind`) 都在跨度上。有关更多信息，请参阅[跨度、事件记录和遥测信](supported-frameworks-telemetry.md)号。
### 来自事件记录
拆分遥测时， AgentCore 评估会从与每个跨度相关的事件记录中读取内容：
+ **用户提示**：来自调用代理跨度的事件记录，在`body.input`。 AgentCore 评估揭开了文本的`new_message.parts`包装。
+ **代理响应**：来自调用代理跨度的事件记录，在`body.output`。 AgentCore 评估揭开了文本的`content.parts`包装。
+ **工具调用**：来自执行工具跨度`tool.name`属性的工具名称。工具参数和结果来自该跨度的事件记录，位于`body.input`和中`body.output`。
有关示例，请参阅[包含事件记录的跨度示](#google-adk-examples-with)例。
### 来自跨度属性
如果未拆分遥测，则相同的内容将作为属性保留在跨度上：
+ **用户提示**和**代理响应**：从`input.value`和`output.value`在调用代理跨度上。 AgentCore 评估会解开`new_message.parts`和文本。`content.parts`
+ **工具调用**：执行工具跨度上的工具名称`input.value`以及来自和`output.value`的参数和结果。`tool.name`
有关示例，请参阅[没有事件记录的跨度示](#google-adk-examples-without)例。
## 包含事件记录的示例
拆分遥测时，跨度带有识别属性，内容存在于相关的事件记录中。以下示例来自部署在亚马逊 Bedrock Runtime 上的 Google ADK 旅行计划代理。 AgentCore
**注意**
这些示例不是完整的跨度。它们显示来自真实代理互动的代表性数据，为了便于阅读，省略了一些字段，长值被截断。
**Example**
外部`invocation`跨度上的`openinference.span.kind`属性 (`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\": [ ... ]}}"
}
]
}
}
}
```
sp `call_llm` an 上的`openinference.span.kind`属性 (`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"
}
}
```
sp `call_llm` an 上的`openinference.span.kind`属性 (`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"
}
}
```