本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 谷歌 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-split)
+ [统一遥测中的示例跨度 ](#google-adk-examples-unified)
## 为您的代理提供仪器
您可以使用仪器库 (`openinference-instrumentation-google-adk`) 对谷歌 ADK 代理进行**OpenInference**检测。该库以范围名称发射遥测数据`openinference.instrumentation.google_adk`，亚马逊基岩 AgentCore 评估读取了该名称。
当您的代理使用 Amazon 发行版 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-telemetry.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`) 包裹跨度 ()，而`agent_run`跨度 (`AGENT`) 又包装 `call_llm` (`LLM`) 和 `execute_tool` () 跨度。`TOOL`外部`CHAIN`跨度带有用户提示符； AgentCore 评估使用它作为调用代理跨度。
## 如何提取评估字段
谷歌ADK将其对话内容包装为双子座内容格式。用户提示符嵌套在`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-split)示例。
### 来自跨度属性
使用统一的遥测技术，将相同的内容作为属性保留在跨度上：
+ **用户提示**和**代理响应**：从`input.value`调用代理跨度开始。`output.value` AgentCore 评估会解开`new_message.parts`和文本。`content.parts`
+ **工具调用**：执行工具跨度上的工具名称`input.value`以及来自和`output.value`的参数和结果。`tool.name`
有关更多信息，请参阅统一遥测[中的跨度](#google-adk-examples-unified)示例。
## 分体遥测中的示例跨度
使用分离式遥测，跨度携带识别属性，内容存在于相关的事件记录中。以下示例来自部署在亚马逊 Bedrock Runtime 上的谷歌 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\": [ ... ]}}"
}
]
}
}
}
```
`call_llm`跨度上的`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"
}
}
```
## 统一遥测中的示例跨度
使用统一的遥测技术，跨度属性上的内容相同，不会生成单独的事件记录。以下示例来自谷歌 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"
}
}
```
`call_llm`跨度上的`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"
}
}
```