# Google ADK
このページでは、[Google Agent Development Kit (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-with)
+ [イベントレコードのないスパンの例](#google-adk-examples-without)
## エージェントを計測する
**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 つのステップです。評価のためにテレメトリをエクスポートするには、[「オブザーバビリティの設定](supported-frameworks.md#supported-frameworks-setup)」で完全なセットアップを完了します。
## スパンの識別方法
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`) はスパン上にあります。詳細については、[「スパン、イベントレコード、テレメトリシグナル](supported-frameworks-telemetry.md)」を参照してください。
### イベントレコードから
テレメトリが分割されると、AgentCore Evaluations は各スパンに相関するイベントレコードからコンテンツを読み取ります。
+ **ユーザープロンプト**: でエージェントスパンのイベントレコードを呼び出します`body.input`。AgentCore Evaluations は`new_message.parts`テキストをラップ解除します。
+ **エージェントレスポンス**: でエージェントスパンのイベントレコードを呼び出します`body.output`。AgentCore Evaluations は`content.parts`テキストをラップ解除します。
+ **ツール呼び出し**: 実行ツールスパンの `tool.name` 属性からのツール名。ツールの引数と結果は、 `body.input`と のスパンのイベントレコードから取得されます`body.output`。
例については、[「イベントレコードを含むスパンの例](#google-adk-examples-with)」を参照してください。
### スパン属性から
テレメトリが分割されていない場合、同じコンテンツは属性と同じスパンに残ります。
+ **ユーザープロンプト**と**エージェントのレスポンス**: `input.value` `output.value` 呼び出しエージェントのスパンとの間で。AgentCore Evaluations は、 `new_message.parts` および `content.parts`テキストをラップ解除します。
+ **ツール呼び出し**: 実行ツールスパン`output.value`の からのツール名`tool.name`、および `input.value`と からの引数と結果。
例については、[「イベントレコードのないスパンの例](#google-adk-examples-without)」を参照してください。
## イベントレコードを含むスパンの例
テレメトリが分割されると、スパンは識別属性を保持し、コンテンツは相関イベントレコードに存在します。次の例は、Amazon Bedrock AgentCore ランタイムにデプロイされた Google ADK の旅行計画エージェントからのものです。
**注記**
これらの例は完全なスパンではありません。実際のエージェントインタラクションからの代表的なデータが表示され、読みやすいように一部のフィールドは省略され、長い値は切り捨てられます。
**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"
}
}
```
## イベントレコードのないスパンの例
テレメトリが分割されていない場合、同じコンテンツはスパン属性に残り、個別のイベントレコードは生成されません。次の例は、Google 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"
}
}
```