Google Agent Development Kit (ADK) のエージェント評価を試してみた！

本記事は  <a href='https://www.gao-ai.com/blog'>GAO 公式ブログ</a> からの転載となります。

---
最近話題の Google 製 AI エージェントフレームワーク「Agent Development Kit (ADK)」を触ってみました！ Gemini モデルとの連携がしやすく、柔軟なエージェント開発が可能とのことで、期待が高まります。エージェントが自律的にツールを使うのは凄いですが、ちゃんと意図通り動くか、修正で壊れないかを確認する「評価」も重要ですよね。


そこで今回は、ADK のセットアップからエージェント作成、そしてそのエージェントを「評価」機能でテストするところまで、一通り試してみた記録をまとめます。

- [**公式ドキュメント**](https://google.github.io/adk-docs/):
- [**事前準備の参考記事**](https://zenn.dev/kun432/scraps/644d535a9d7754)：（事前準備はこちらの記事を参考にしました）

### **1. 環境セットアップ**

まずはローカル環境（Mac）でプロジェクトを準備します。パッケージマネージャーには uv を使用しました。

**Bash**
```
# プロジェクトディレクトリ作成と移動 (Python 3.12.9 を指定)
uv init -p 3.12.9 adk-work
cd adk-work

# ADK パッケージのインストール
# (評価機能も使うため、[eval] 付きでインストールする)
uv add "google-adk[eval]" 
```

google-adk[eval] とすることで、評価に必要な追加ライブラリ (pandasなど) も一緒にインストールされます。

### **2. エージェントプロジェクトの作成**

参考記事に沿って、天気 (get_weather) と時刻 (get_current_time) を取得するツールを持つエージェント (multi_tool_agent) を作成します。

**ディレクトリ・ファイル構成:**

**Bash**
``` 
mkdir multi_tool_agent
touch multi_tool_agent/{__init__.py,agent.py,.env}
tree -a multi_tool_agent/ 
```

実行結果：
```
`multi_tool_agent/
├── .env
├── __init__.py
└── agent.py
```

**ファイルの内容:**

- **multi_tool_agent/__init__.py**:

```
from . import agent
```

- **multi_tool_agent/agent.py**のコードを記述します。

```
import datetime

from google.adk.agents import Agent
from zoneinfo import ZoneInfo

def get_weather(city: str) -> dict:
    """特定の都市の現在の天気情報を取得する。

    Args:
        city (str): 天気情報を取得したい都市名。英語で。

    Returns:
        dict: ステータスと結果またはエラーメッセージ。
    """
    if city.lower() == "new york":
        return {
            "status": "success",
            "report": ("ニューヨークの天気は晴れです。" "気温は25度（41°F）です。"),
        }
    else:
        return {
            "status": "error",
            "error_message": f"{city}の天気情報は利用できません。",
        }

def get_current_time(city: str) -> dict:
    """特定の都市の現在時刻を取得する。

    Args:
        city (str): 天気情報を取得したい都市名。英語で。

    Returns:
        dict: ステータスと結果またはエラーメッセージ。
    """

    if city.lower() == "new york":
        tz_identifier = "America/New_York"
    else:
        return {
            "status": "error",
            "error_message": (f"{city}のタイムゾーン情報は利用できません。"),
        }

    tz = ZoneInfo(tz_identifier)
    now = datetime.datetime.now(tz)
    report = f'{city}の現在時刻は {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}です。'
    return {"status": "success", "report": report}

root_agent = Agent(
    name="weather_time_agent",
    model="gemini-2.0-flash-exp",
    description="任意の都市の時刻と天気に関する質問に答えるエージェントです。",
    instruction="私は指定された都市の時刻や天気に関する質問に答えることができます。",
    tools=[get_weather, get_current_time],
)
```

### **3. モデル接続の設定 (.env ファイル)**

LLM (Gemini) への接続情報を .env ファイルに記述します。Google AI Studio か Vertex AI かで設定内容が異なります。

**Google AI Studio:**
```
GOOGLE_GENAI_USE_VERTEXAI="False" GOOGLE_API_KEY="YOUR_API_KEY_HERE"
```

**Vertex AI:**
```
GOOGLE_CLOUD_PROJECT="your-gcp-project-id" GOOGLE_CLOUD_LOCATION="your-region" 
# 例: us-central1 GOOGLE_GENAI_USE_VERTEXAI="True"
```

 (Vertex AI 利用時は事前の API 有効化、gcloud auth login が必要)

今回は **Vertex AI** を使用しました。

### **4. エージェントを実行してみる (Web UIでの基本動作確認)**

まずはエージェントがちゃんと動くか、Web UI で確認します。プロジェクトルート (adk-work) で以下を実行。

**Bash**
```
uv run adk web
```

ブラウザで [http://localhost:8000](http://localhost:8000/) にアクセスし、エージェント multi_tool_agent を選択します。

チャットで「ニューヨークの天気は？」などと尋ねると、エージェントがツールを使って応答してくれるはずです。右側のページで詳細な動作（LLM とのやり取り、ツール実行）も確認できます。これでエージェントが基本動作することは確認できました。

### **5. エージェント評価の必要性**

手動での動作確認も大事ですが、エージェントが複雑になったり、修正を繰り返したりすると、「毎回同じテストを手動でやるのは大変」「意図しないところで動作が変わっていないか心配」となります。ここで ADK の**評価機能**の出番です。

ADK ドキュメントによると、LLM エージェント評価では「最終出力」だけでなく、そこに至る「軌跡（ツールの使い方など）」も重要であり、これを自動でチェックできる仕組みが提供されています。

### **6. 評価シナリオ (評価セット) の準備**

評価のために、「お手本」となるシナリオと期待される動作を定義した**評価セットファイル (.evalset.json)** を用意します。ファイル名は任意（例: multi_tool_agent_test.evalset.json）です。Web UI で対話したセッションを保存して生成することも、手動で作成することも可能です。

以下のファイルでは、期待されるツール使用と参照応答 (reference) を定義しています。

**(ファイル名例: multi_tool_agent_test.evalset.json)**

**JSON**
```
[
  {
    "name": "test",
    "data": [
      {
        "query": "おはよう！",
        "expected_tool_use": [],
        "reference": "おはようございます！お手伝いできることはありますか？"
      },
      {
        "query": "ニューヨークの現在の時間は？",
        "expected_tool_use": [
          {
            "tool_name": "get_current_time",
            "tool_input": { "city": "New York" }
          }
        ],
        "reference": "ニューヨークの現在時刻は...です。..."
      },
      {
        "query": "ニューヨークの天気は？",
        "expected_tool_use": [
          { "tool_name": "get_weather", "tool_input": { "city": "New York" } }
        ],
        "reference": "ニューヨークの天気は晴れです。..."
      }
    ],
    "initial_session": {
      "state": {},
      "app_name": "multi_tool_agent",
      "user_id": "user"
    }
  }
]
```

### **7. 評価の基準 ([ADK ドキュメントより](https://google.github.io/adk-docs/evaluate/#1-adk-web-run-evaluations-via-the-web-ui))**

ADK はエージェントの実際の動作と評価セットの期待値を比較する際、以下の基準（メトリクス）とデフォルトの閾値を使用します。

- **tool_trajectory_avg_score**: ツール使用履歴の一致度。デフォルト閾値 **1.0** (完全一致)。
- **response_match_score**: 最終応答と reference の類似度。デフォルト閾値 **0.8** (ある程度似ていればOK)。
- ちなみに、これらのデフォルト閾値は、必要であれば 以下のようなtest_config.json という設定ファイルを作成して各エージェントディレクトリ配下に置くことでカスタマイズすることも可能です。

```
{
  "criteria": {
    "tool_trajectory_avg_score": 1.0,
    "response_match_score": 0.8
  }
}
```

### **8. Web UI で評価を実行！**

準備ができたので、Web UI で評価を実行します。

1. (もし adk web が停止していれば再起動)
2. Web UI で multi_tool_agent を選択。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4048367/78652a57-eda7-42c7-804b-b24d1e2f55c6.png)


3. 右側の「評価 (Eval)」タブを開く。
4. 「評価セット (Eval Set)」ドロップダウンから、**自分で準備した評価セットファイル**（multi_tool_agent_test）を選択。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4048367/4a01085c-71d4-464d-a6f6-5ac77c911635.png)

5. 評価ケース test が表示されるのでチェックを入れて、「Run Evaluation」ボタンをクリック！
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4048367/a2fbb6b1-f748-42bb-a7f5-842a1203fada.png)

実行後、結果が表示されます。


![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4048367/0bbd6d4c-9fb3-4207-94f5-f58413c836c8.png)
    
今回は無事「PASS」しました！

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/4048367/70fc72ff-6a1a-4ebc-8370-b8cdb6aabc69.png)


また、ターミナルを見てみると詳細が出力されると思います。

（**※注意**：応答一致 (response_match_score): 筆者が実験をしてみると、評価セットの reference に明らかに正しくない応答を設定し、さらに test_config.json で 値を明示的に指定しても、評価全体の結果は1となり「PASS」のままでした。）

## Agent Development Kit の評価まとめ ## 

- 今回は、ADK のセットアップからエージェント作成、そして評価機能を使ったテストまでを一通り体験しました。評価セットによる自動評価は、特にエージェントのツール利用手順（軌跡）が期待通りかを確認する上で有効だと感じました (tool_trajectory_avg_score は意図通り機能しているようです)。これにより、回帰テストの一部は自動化できそうです。

- 一方で、**最終応答のテキスト内容 (reference) との比較 (response_match_score) については、今回試した範囲では、期待通りに最終的な評価結果 (PASS/FAIL) に影響を与えない場面がありました。** 明らかに異なる応答を期待値としても、評価全体が PASS してしまうケースがあり、test_config.json で基準を明示的に設定しても結果は変わりませんでした。この挙動については、さらなる調査や ADK の今後のバージョンでの改善が必要かもしれません。 

- このように、現状では特に**応答内容の自動評価に関しては注意が必要**ですが、ツール利用の正確性を担保する目的など、**部分的には** ADK の評価機能は開発の助けになる可能性はあります。ADK の評価機能を利用する際は、現状の挙動をよく理解・検証した上で、目的に合わせて活用するのが良さそうです。皆さんもぜひ試してみてください！