ADKのWeb UIによる評価とデバッグ – G-gen Tech Blog

G-gen の min です。Agent Development Kit（ADK）の Web UI による評価とデバッグの方法を解説します。

ADK とは

Agent Development Kit（ADK）とは、AI エージェントを開発するためのフレームワークです。Google により開発され、2025年10月現在、Python 用と Java 用のライブラリが公開されています。特定のモデルやデプロイ環境に依存せず、他のフレームワークとの互換性も考慮されています。

AI エージェントの開発から Web UI を用いた動作検証までの流れについては、以下の記事もご参照ください。

blog.g-gen.co.jp

本記事では、ADK に組み込まれた Web UI を用いて、AI エージェントのデバッグと評価を行うサイクルを解説します。

評価とデバッグ

AI エージェントは、その挙動が非決定的であるため、品質を担保し、意図しない振る舞いを修正する「評価」と「デバッグ」のプロセスが重要です。

ADK は、開発者がコード内にテストを記述する従来の方法に加え、開発サイクルの中でインタラクティブにエージェントの挙動をテストし、その品質を定量的に評価するための機能をフレームワーク自体に組み込んでいます。この機能は Web UI を通じて利用できます。

この機能は、次に説明する「Event」というコアコンセプトに基づいています。

Event とは

Event とは、ADK における情報伝達の基本単位です。ユーザーの最初の入力からエージェントの最終応答まで、その間に発生したすべての重要な出来事を記録した「不変のレコード」と考えることができます。

具体的には、以下のような情報がすべて Event として扱われます。

• ユーザーからのメッセージ（author: 'user'）
• エージェントによる思考や応答テキスト
• LLMに対するツール使用の要求（functionCall）
• ツールの実行結果（functionResponse）
• 状態の変化やエラー通知

これらの Event が時系列に連なることで、エージェントとのインタラクションの全容が記録されます。ADK の Web UI が提供するデバッグ・評価機能は、この Event のストリームを可視化し、分析するためのツールです。

必要な依存関係

Web UI で評価機能を利用するには、追加の依存関係をインストールする必要があります。

pip install "google-adk[eval]"

インストール後、以下のコマンドで Web UI を起動できます。 の部分には、エージェントの定義ファイルが格納されているフォルダへのパスを指定してください。

adk web <path_to_your_agents_folder>

ブラウザで http://127.0.0.1:8000 にアクセスすると、Web UI が表示されます。

概要

ADK の Web UI は、Event のストリームを分析するための2つの主要なビューを提供します。

これらを使うことで、エージェントの内部的な動作を詳細に追跡できます。

Events ビュー

Events ビューは、発生したすべての Event を時系列に沿ってリストアップするビューです。Event の全体像や、個々の Event の中身を確認したい場合に役立ちます。

例えば、LLM が生成したツール呼び出しの引数（functionCall の args）や、ツールの実行結果（functionResponse の response）などを確認できます。

Trace ビュー

Trace ビューは、Event の流れを「誰が誰を呼び出したか」という親子関係で再構成し、処理の全体像を階層的に把握しやすくしたビューです。

LLM による思考からツール実行、最終応答の生成といった一連の流れや、各ステップの処理時間を直感的に理解できるため、処理フローの把握やボトルネックの特定に有効です。各トレース行をクリックすると、関連する Event の詳細をパネルで確認できます。

概要

デバッグによって個々の挙動を分析できるようになったら、次は評価（Evaluate）機能を使って、エージェントの品質を体系的に測定し、改善サイクルを回します。

評価機能は、「期待される対話（テストケース）」と「実際の対話」を比較し、その品質をスコアで定量化するためのインタラクティブな機能です。評価は、主に「テストケース作成」「評価の実行」「結果の分析」という3つのステップで構成されます。

1. テストケースの作成

まず、評価の基準となる「正解」の対話シナリオをテストケースとして作成します。

Web UI 上でエージェントと対話し、期待に近い応答が得られたセッションを作成します。その後、画面右側の Eval タブで評価セットを作成または選択し、Add current session ボタンで現在の会話をテストケースとして保存します。

保存したテストケースは、編集アイコンから応答テキストを修正するなど、より理想的なシナリオに編集することも可能です。

2. 評価の実行

次に、準備したテストケースを使ってエージェントの性能を評価します。

評価セットから実行したいテストケースを選択し、Run Evaluation ボタンをクリックします。評価時には、以下のメトリクスに対する合格閾値を設定します。

• Tool trajectory avg score : 期待されるツールの使用順序や引数と、実際のものとの一致度。
• Response match score : 期待される最終応答と、実際の応答との意味的な類似度。

Start をクリックすると評価が実行されます。

3. 結果の分析

評価が完了したら、結果を分析して次の改善アクションに繋げます。

結果一覧に Fail がある場合、 Fail にカーソルを合わせると、Actual（実際の出力）と Expected（期待される出力）の比較や、どのスコアが閾値を下回ったかが表示され、失敗の原因を把握できます。

評価で失敗したケースは、デバッグの対象です。Trace ビューや Events ビューを使い、なぜ期待と異なる挙動になったのかを詳細に調査しましょう。

実践例

次に、公式のクイックスタートエージェントを例に、実際のデバッグと評価のサイクルを紹介します。

1. 正常系の動作確認

まず、adk web でUIを起動し、multi_tool_agent に「What is the weather in New York?」と質問します。

Trace ビューを開くと、call_llm（思考）→ execute_tool[get_weather]（ツール実行）→ call_llm（最終応答）という一連のEventの流れが可視化され、エージェントが正しく動作していることを確認できます。

2. 異常系のデバッグ

次に、エージェントが対応していない「What is the weather in Okinawa?」と質問してみます。

Events ビューに切り替えて Event リストを確認します。ツール呼び出し時の応答 functionResponse を調査します。

Event 詳細ビューで Event > response を見ると、エージェントからの応答（response）を確認できます。

これにより、エージェントはツールを呼び出そうとしたものの、ツール自体が「Okinawa」に対応していないためエラーになった、という事実を特定できます。

3. プロンプトの調査と改善

では、なぜエージェントは対応していない都市でもツールを呼び出そうとしたのでしょうか。Events ビューの、ツール呼び出し後の text を調査します。

Event 詳細ビューで Request > system_instruction を見ると、エージェントへの指示書（プロンプト）を確認できます。この指示書に「New York にしか対応していない」という情報が不足していれば、エージェントが他の都市でもツールを呼び出そうとするのは自然な挙動です。

このように、エージェントの意図しない挙動は、プロンプトやツールの説明文（docstring）をより明確に記述することで修正できる場合が多くあります。

4. 回帰テストの作成

ステップ1で確認した「正常系の動作」の対話セッションを、テストケースとして保存します。

これは、将来的にコードを変更した際に、この正しい挙動が壊れていないか、つまり回帰（リグレッション）していないかをチェックするために重要です。このようなチェックを回帰テスト（リグレッションテスト）といいます。

期待に近い結果をテストケースとして保存しておけば、将来の回帰テストに利用できます。またテストケース内のやりとりを修正してより期待に近づけ、プロンプトチューニングの際の評価に利用することもできます。