檢測您的代理程式如何識別跨度如何擷取評估欄位範例跨越事件記錄沒有事件記錄的範例範圍

Google ADK

此頁面說明如何檢測 Google Agent Development Kit (ADK) 代理程式、如何識別範圍，以及如何擷取評估欄位。

主題

檢測您的代理程式
如何識別跨度
如何擷取評估欄位
- 從事件記錄
- 從跨度屬性
範例跨越事件記錄
沒有事件記錄的範例範圍

檢測您的代理程式

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

注意

檢測是設定可觀測性的一個步驟。若要匯出遙測資料進行評估，請完成設定可觀測性中的完整設定。

如何識別跨度

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) 位於跨度。如需詳細資訊，請參閱跨度、事件記錄和遙測訊號。

從事件記錄

分割遙測時，AgentCore Evaluations 會從與每個範圍相關的事件記錄中讀取內容：

使用者提示：從叫用客服人員的事件記錄，在中body.input。AgentCore Evaluations 會取消包裝new_message.parts文字。
客服人員回應：在中調用客服人員範圍的事件記錄body.output。AgentCore Evaluations 會取消包裝content.parts文字。
工具呼叫：執行工具範圍上 tool.name 屬性的工具名稱。工具引數和結果來自 body.input和中的跨度事件記錄body.output。

如需範例，請參閱範例跨越事件記錄。

從跨度屬性

未分割遙測時，相同的內容會保留在跨度上做為屬性：

使用者提示和客服人員回應：調用客服人員範圍output.value上的 input.value和。AgentCore Evaluations 會取消包裝 new_message.parts和 content.parts 文字。
工具呼叫：執行工具範圍output.value上來自的工具名稱tool.name，以及來自和的引數input.value和結果。

如需範例，請參閱沒有事件記錄的範例跨度。

範例跨越事件記錄

分割遙測時，範圍會攜帶識別屬性，而內容會存在於相關事件記錄中。下列範例來自部署在 Amazon Bedrock AgentCore 執行期上的 Google ADK 行程規劃代理程式。

注意

這些範例不是完整的跨度。它們會顯示來自實際客服人員互動的代表性資料，省略一些欄位，並截斷長值以保證可讀性。

範例

Invoke agent span

外部範圍上的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\"}"
        }
      ]
    }
  }
}

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

跨度上的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 旅行規劃代理程式。

注意

這些範例不是完整的跨度。它們會顯示來自實際客服人員互動的代表性資料，省略一些欄位，並截斷長值以保證可讀性。

範例

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

跨度上的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"
  }
}

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

LlamaIndex

Claude 代理程式開發套件