View a markdown version of this page

谷歌 ADK - 亚马逊基岩 AgentCore
为您的代理提供仪器如何识别跨度如何提取评估字段分体遥测中的示例跨度统一遥测中的示例跨度

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

谷歌 ADK

本页介绍如何对 Google 代理开发套件 (ADK) 代理进行检测、如何确定跨度以及如何提取评估字段。

主题

为您的代理提供仪器

您可以使用仪器库 (openinference-instrumentation-google-adk) 对谷歌 ADK 代理进行OpenInference检测。该库以范围名称发射遥测数据openinference.instrumentation.google_adk，亚马逊基岩 AgentCore 评估读取了该名称。

当您的代理使用 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",
]
注意

仪器仪表是设置可观测性的一个步骤。要导出遥测数据进行评估，请在设置可观测性中完成完整设置。

如何识别跨度

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) 都处于跨度内。有关更多信息，请参阅遥测设置和交付。

来自事件记录

使用分离式遥测， AgentCore 评估从与每个跨度相关的事件记录中读取内容：

  • 用户提示：来自调用代理跨度的事件记录，在body.input。 AgentCore 评估可以解开文本。new_message.parts

  • 代理响应：来自调用代理跨度的事件记录，在body.output。 AgentCore 评估可以解开文本。content.parts

  • 工具调用：执行工具跨度上tool.name属性的工具名称。工具参数和结果来自该跨度的事件记录，以body.input和为单位body.output。

有关更多信息，请参见分割遥测中的跨度示例。

来自跨度属性

使用统一的遥测技术，将相同的内容作为属性保留在跨度上：

  • 用户提示和代理响应：从input.value调用代理跨度开始。output.value AgentCore 评估会解开new_message.parts和文本。content.parts

  • 工具调用：执行工具跨度上的工具名称input.value以及来自和output.value的参数和结果。tool.name

有关更多信息，请参阅统一遥测中的跨度示例。

分体遥测中的示例跨度

使用分离式遥测，跨度携带识别属性，内容存在于相关的事件记录中。以下示例来自部署在亚马逊 Bedrock Runtime 上的谷歌 ADK 旅行计划代理。 AgentCore

注意

这些例子并不完整。它们显示来自真实代理交互的代表性数据，为了便于阅读，省略了一些字段并截断了长值。

例
Invoke agent span

外部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\"}"
        }
      ]
    }
  }
}
Execute tool span

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\": [ ... ]}}"
        }
      ]
    }
  }
}
Inference span

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 旅行计划代理机构。

注意

这些例子并不完整。它们显示来自真实代理交互的代表性数据，为了便于阅读，省略了一些字段并截断了长值。

例
Invoke agent span

该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"
  }
}
Execute tool span

该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"
  }
}
Inference span

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"
  }
}