对你的代理进行仪器如何识别跨度如何提取评估字段包含事件记录的示例没有事件记录的示例跨度

谷歌 ADK

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

主题

对你的代理进行仪器
如何识别跨度
如何提取评估字段
- 来自事件记录
- 来自跨度属性
包含事件记录的示例
没有事件记录的示例跨度

对你的代理进行仪器

您可以使用仪器库 (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",
]

注意

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

如何识别跨度

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) 都在跨度上。有关更多信息，请参阅跨度、事件记录和遥测信号。

来自事件记录

拆分遥测时， 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 上的 Google 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

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 差旅计划代理。

注意

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

例

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

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

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

LlamaIndex

克劳德特工 SDK