エージェントを計測するスパンの識別方法評価フィールドの抽出方法イベントレコードを含むスパンの例イベントレコードのないスパンの例

Google ADK

このページでは、Google Agent Development Kit (ADK) エージェントを計測する方法、スパンの特定方法、評価フィールドの抽出方法について説明します。

トピック

エージェントを計測する
スパンの識別方法
評価フィールドの抽出方法
- イベントレコードから
- スパン属性から
イベントレコードを含むスパンの例
イベントレコードのないスパンの例

エージェントを計測する

OpenInference 計測ライブラリ () を使用して Google ADK エージェントを計測できますopeninference-instrumentation-google-adk。このライブラリはopeninference.instrumentation.google_adk、Amazon Bedrock AgentCore Evaluations が読み取るスコープ名でテレメトリを出力します。

Amazon Bedrock AgentCore ランタイムなど、エージェントが AWS Distro for OpenTelemetry (ADOT) で実行されている場合、明示的な計測コードを追加する必要はありません。計測ライブラリをプロジェクトの依存関係に追加するだけで十分です。ADOT は起動時に検出し、自動的にアクティブ化します。

計測ライブラリを依存関係に追加します。

注記

バージョン 0.1.13 以降を使用します。これは、評価サービスでテストされた最も古いバージョンです。

requirements.txt:


openinference-instrumentation-google-adk>=0.1.13

pyproject.toml:


[project]
dependencies = [
    "openinference-instrumentation-google-adk>=0.1.13",
]

注記

計測は、オブザーバビリティを設定する 1 つのステップです。評価のためにテレメトリをエクスポートするには、「オブザーバビリティの設定」で完全なセットアップを完了します。

スパンの識別方法

Google ADK は OpenInference 規則で計測されるため、AgentCore Evaluations は 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 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。

例については、「イベントレコードを含むスパンの例」を参照してください。

スパン属性から

テレメトリが分割されていない場合、同じコンテンツは属性と同じスパンに残ります。

ユーザープロンプトとエージェントのレスポンス: input.value output.value 呼び出しエージェントのスパンとの間で。AgentCore Evaluations は、 new_message.parts および content.partsテキストをラップ解除します。
ツール呼び出し: 実行ツールスパンoutput.valueのからのツール名tool.name、および input.valueとからの引数と結果。

例については、「イベントレコードのないスパンの例」を参照してください。

イベントレコードを含むスパンの例

テレメトリが分割されると、スパンは識別属性を保持し、コンテンツは相関イベントレコードに存在します。次の例は、Amazon Bedrock AgentCore ランタイムにデプロイされた Google ADK の旅行計画エージェントからのものです。

注記

これらの例は完全なスパンではありません。実際のエージェントインタラクションからの代表的なデータが表示され、読みやすいように一部のフィールドは省略され、長い値は切り捨てられます。

例

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

イベントレコードのないスパンの例

テレメトリが分割されていない場合、同じコンテンツはスパン属性に残り、個別のイベントレコードは生成されません。次の例は、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

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

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

LlamaIndex

Claude エージェント SDK