# ADKの便利で実践的な使い方 🧪 エージェントのプロンプトを変更したら、品質が下がっていないか確認していますか？ADKのEvaluation機能を使えば、テストファイル方式とデータセット方式の2つのアプローチでエージェントの品質を体系的に検証できます。CIに組み込めば、プロンプト変更の回帰テストも自動化できます。 📌 タイトル：Evaluation 概要 🔗 URL： 🧩 概要 ADKは、エージェントのパフォーマンスを評価するための2つの主要な方法を提供します。**テストファイル方式**は`.test.json`ファイルに単一セッション（複数ターン可）を記述し、ユニットテストのように高速に反復できます。**Evalset方式**は複数セッション・多数のターンを含む統合テスト向けです。一部の評価基準（レスポンス品質、安全性、マルチターン品質など）はVertex Gen AI Evaluation Service APIを必要とします。評価基準として`tool_trajectory_avg_score`、`response_match_score`、`hallucinations_v1`、`safety_v1`などの組み込みメトリクスが利用可能です。 🛠 使い方 テストファイルには、ユーザークエリ、期待されるツール使用軌跡、期待されるレスポンスを記述します。 評価の実行方法は3つあります。 **Web UI**での対話的な評価： ```bash adk web path/to/agents_dir ``` **pytest**との統合： `AgentEvaluator.evaluate()` を `await` で呼び出し、`agent_module` に評価対象のエージェントモジュール名（例: `"home_automation_agent"`）、`eval_dataset_file_path_or_dir` にテストファイルのパス（例: `"tests/integration/fixture/test.test.json"`）を指定します。 **CLI**での実行： ```bash adk eval --config_file_path= ``` 評価基準のしきい値は`test_config.json`で設定します。 ```json { "criteria": { "tool_trajectory_avg_score": 1.0, "response_match_score": 0.8 } } ``` デフォルトでは、ツール軌跡は100%一致を要求し、レスポンスマッチングは80%の類似度を許容します。 🏗 実践的な使い方 **エージェント更新時の回帰テスト**: プロンプトやツール定義を変更するたびに、既存のテストファイルを使って回帰テストを実行します。`tool_trajectory_avg_score`でツール選択の正確性を、`response_match_score`でレスポンスの品質を定量的に検証できます。品質低下を早期に検出できるため、安心してプロンプトの改善を繰り返せます。 **テストファイル方式で高速イテレーション**: 開発中は`.test.json`ファイルを使ったユニットテスト的なアプローチが最適です。単一セッションの期待値を記述し、pytestで自動実行すれば、コード変更のたびに数秒で品質を確認できます。エッジケースごとにテストファイルを追加していくことで、テストカバレッジを段階的に拡充できます。 **データセット方式でバッチ評価**: 本番に近い複雑なシナリオは、Evalset方式で多数のセッションをまとめて評価します。マルチターンの会話フローや、異なるユーザーパターンを網羅的にテストでき、統合テストとして機能します。 **CIパイプラインへの統合**: `adk eval`コマンドをCIに組み込めば、プロンプト変更のプルリクエストごとに自動で品質チェックが実行されます。しきい値を下回った場合はCIを失敗させることで、品質低下したプロンプトのマージを防げます。 💡 ユースケース 🔄 プロンプト変更時の回帰テスト自動化 ⚡ テストファイル方式での高速な開発イテレーション 📊 データセット方式での網羅的なバッチ評価 🔗 CI/CDパイプラインへの品質ゲート統合 ⚠️ 注意点 - 一部の評価基準（レスポンス品質、安全性、マルチターン品質など）はVertex Gen AI Evaluation Service API（有料のGoogleサービス）が必要です。 - テストファイルのしきい値は厳しすぎると偽陰性が増え、緩すぎると品質低下を見逃します。初期値から段階的に調整してください。 - LLMベースの評価基準（`hallucinations_v1`など）はジャッジモデルの判断にばらつきがあるため、`num_samples`で複数回サンプリングすることを推奨します。 ✨ ADKのEvaluation機能を活用すれば、エージェントの品質管理を「感覚」から「定量的な基準」に変えられます。まずはテストファイル方式で始めて、CI統合へと進めてみてください！ #ADK# #AIAgent#

AIエージェントのテストは、普通のソフトウェアテストとは勝手が違います。同じ入力でも毎回出力が変わり、正解が1つではなく、正しい結果でも手順が「不適切」なこともあるからです。 タイトル: The Most Common Questions About Agent Evals, Answered URL: ❓ 何から始めればいいの? 💡 まず評価したい挙動を1つに絞り(例: 旅行アシスタントが指定の日付・価格帯で予約するか)、実行ログから10〜20件ほどの小さなデータセットを作ります。現在のバージョンでベースラインを取り、本番や開発中に見つかった失敗例を継続的に追加していく段階的なアプローチが推奨されています。 ❓ オフライン評価とオンライン評価はどう違うの? 💡 オフライン評価は出荷前にデータセットに対して実行し、参照出力と比較できるため新しいプロンプトやモデルの検証に向いています。オンライン評価は本番のトレースをリアルタイムで評価するもので、参照出力がない代わりにコードチェックやLLM judgeを使い、予期しない問題の発見に向いています。 ❓ LLM judgeはどうすれば信頼できるの? 💡 人間のスコアと小サンプルで照合し、「すべての乗り継ぎに言及したか」のような狭い質問にすること、そして1〜10のスケールではなく合格/不合格のような二値や少数カテゴリで採点することが推奨されています。安価なjudgeモデルを使えば、Claude Sonnetで28.17ドルかかった評価が0.34ドルまで下がった例も紹介されています。 ❓ マルチターンの対話はどう評価するの? 💡 各ターン単体では妥当に見えても、会話全体では問題が顕在化することがあります。スレッドIDでターンをまとめ、全メッセージとツール呼び出しを順序通り表示した上で、「最終的な予約はユーザーの全変更を反映しているか」のように会話全体を通した質問で評価します。 #AIエージェント# #評価手法#

AIエージェントのテストは、普通のソフトウェアテストとは勝手が違います。同じ入力でも毎回出力が変わり、正解が1つではなく、正しい結果でも手順が「不適切」なこともあるからです。 タイトル: The Most Common Questions About Agent Evals, Answered URL: ❓ 何から始めればいいの? 💡 まず評価したい挙動を1つに絞り(例: 旅行アシスタントが指定の日付・価格帯で予約するか)、実行ログから10〜20件ほどの小さなデータセットを作ります。現在のバージョンでベースラインを取り、本番や開発中に見つかった失敗例を継続的に追加していく段階的なアプローチが推奨されています。 ❓ オフライン評価とオンライン評価はどう違うの? 💡 オフライン評価は出荷前にデータセットに対して実行し、参照出力と比較できるため新しいプロンプトやモデルの検証に向いています。オンライン評価は本番のトレースをリアルタイムで評価するもので、参照出力がない代わりにコードチェックやLLM judgeを使い、予期しない問題の発見に向いています。 ❓ LLM judgeはどうすれば信頼できるの? 💡 人間のスコアと小サンプルで照合し、「すべての乗り継ぎに言及したか」のような狭い質問にすること、そして1〜10のスケールではなく合格/不合格のような二値や少数カテゴリで採点することが推奨されています。安価なjudgeモデルを使えば、Claude Sonnetで28.17ドルかかった評価が0.34ドルまで下がった例も紹介されています。 ❓ マルチターンの対話はどう評価するの? 💡 各ターン単体では妥当に見えても、会話全体では問題が顕在化することがあります。スレッドIDでターンをまとめ、全メッセージとツール呼び出しを順序通り表示した上で、「最終的な予約はユーザーの全変更を反映しているか」のように会話全体を通した質問で評価します。 #AIエージェント# #評価手法#

TL;DR エージェント評価の判定器をLLMからJevという専用モデルに変えるだけで、精度100%・コスト80分の1以下という結果が出たそうです。 タイトル: Jev-as-a-Judge for Agent Evals URL: ポイント ⚖️ コードベース評価は決定論的すぎ、LLM-as-a-Judgeは非決定論的すぎるという板挟みへの解決策として提案されています 🎯 500回繰り返した判定でJevの一致率は100%、比較対象のClaudeは80.0%にとどまりました 📉 品質スコアの分散もJevが最小で、他の判定器は最大913倍もばらつきが大きかったそうです 💰 5リクエストの評価コストはJevが0.34ドル、Claudeは28.17ドルと桁違いの差がありました ⚡ 平均応答時間はわずか0.44秒で、判定の高速性も際立っています 🔍 コードベース評価とLLM-as-a-Judgeに続く「第3の評価形態」として位置づけられています 低コストで判定を繰り返し実行できるようになると、エージェント開発のフィードバックループそのものが変わりそうです。 #AIエージェント評価# #LangChain#

便利だけど知られていないOpenAI APIの機能 📊 モデルの出力品質、人間がいちいち手動でチェックしていませんか？ OpenAIの「Graders（グレーダー）」は、モデルの出力を自動で採点する仕組みです。Evalsでの品質評価や、強化ファインチューニングの報酬設計に使えます。 📌 タイトル：Graders（グレーダー） 🔗 URL： 🧩 概要 モデルの品質改善には「良い出力と悪い出力を定量的に判定する」仕組みが不可欠です。Gradersは出力に対してスコアを自動で付与する採点器で、文字列一致、モデルベースの判定、Pythonコードによるカスタム評価など、複数の採点方式に対応しています。Evalsの品質測定や、強化ファインチューニングの報酬関数として活用できます。 🛠 使い方 採点方式を選び、評価基準を定義します。文字列一致やラベル判定のような単純なものから、別のLLMを使った複雑な品質判定まで設定可能。定義したグレーダーはEvalsのパイプラインに組み込んだり、強化ファインチューニングの報酬として使ったりできます。 🏗 本番システムへの組み込み方 ・継続的品質モニタリング：本番のモデル出力をサンプリングし、グレーダーで自動スコアリング。品質低下を早期検知。 ・Evalsパイプライン：プロンプト変更やモデル更新時に、グレーダーで品質を定量比較。 ・強化ファインチューニング：グレーダーのスコアを報酬にしてモデルを強化学習的に改善。 ・A/Bテストの評価基盤：異なるプロンプトやモデルの出力をグレーダーで比較評価。 💡 ユースケース 📈 モデル出力の継続的品質モニタリング 🧪 Evalsでの定量的品質比較 🎯 強化ファインチューニングの報酬設計 🔬 プロンプト・モデルのA/Bテスト評価 ⚠️ 注意点 グレーダーの品質が評価の信頼性を左右します。特にモデルベースのグレーダーは、評価基準が曖昧だと採点がブレることがあります。明確で具体的な評価基準を定義し、人間の判断と比較してキャリブレーションすることが重要です。 ✨ 品質改善は「測れること」から始まる。まずはEvalsにグレーダーを組み込んで、出力品質の定量化を始めてみてください。 #OpenAI# #LLM#

便利だけど知られていないOpenAI APIの機能 🔄 「OpenAIと他のモデル、どっちが良いの？」を公平に比較したいと思いませんか？ OpenAIの「External models（外部モデル評価）」は、OpenAI以外のモデルもEvals基盤で評価できる機能です。複数モデルを同じ基準で比較したいときに便利です。 📌 タイトル：External models（外部モデル評価） 🔗 URL： 🧩 概要 モデルの選定や切り替えの判断には、同じ評価基準での公平な比較が必要です。External modelsを使えば、OpenAIのモデルだけでなくClaude、Gemini、オープンソースモデルなど外部のモデルもOpenAIのEvals基盤上で同じグレーダー・同じデータセットで評価できます。ベンダーごとに評価ツールを分ける手間がなくなります。 🛠 使い方 外部モデルの接続情報（APIエンドポイントや認証情報）をEvalsに登録し、評価対象として指定します。あとは通常のEvalsと同様に、データセットとグレーダーを使ってテストを実行するだけ。結果は同じダッシュボードで横並びに比較できます。 🏗 本番システムへの組み込み方 ・モデル選定プロセス：新しいモデルが出たときに、既存モデルと同じベンチマークで比較評価。 ・モデル移行の判断：別モデルに切り替える前に、自社タスクでの品質を定量比較。 ・コスト最適化：同等品質の安いモデルがないか、Evalsで定期的にスキャン。 ・マルチモデル戦略：タスクごとに最適なモデルを選ぶための評価フレームワークとして。 💡 ユースケース 🏆 複数モデルのベンチマーク比較 🔀 モデル移行前の品質検証 💰 コスト対品質の最適化 📋 タスク別の最適モデル選定 ⚠️ 注意点 外部モデルのAPIキーや利用料金は別途かかります。また、モデルによってはレスポンス形式やエラーハンドリングが異なるため、評価時に出力の正規化が必要になることもあります。比較は「同じタスク・同じデータ」で行うことが大前提です。 ✨ モデル選定を「なんとなく」から「データドリブン」に。まずは今使っているモデルと気になるモデルをEvalsで並べて比べてみてください。 #OpenAI# #LLM#

# ADK 2.0の便利だけど知られていない機能 🌍 標準メトリクスだけでは測れない、自社独自の評価基準でエージェントを採点できたら理想的だと思いませんか？ ADK 2.0のカスタム評価メトリクス機能は、Python関数として独自の評価ロジックを定義し、エージェントの品質を自由な基準で測定できる仕組みです。 📌 タイトル：カスタム評価メトリクス (Custom Metrics) 🔗 URL： 🧩 概要 カスタム評価メトリクスは、`EvaluationResult` を返すPython関数として定義します。関数には `eval_metric`（評価メトリクスの定義）、`actual_invocations`（実際のエージェントの応答）、`expected_invocations`（期待される応答）、`conversation_scenario`（会話シナリオ）がパラメータとして渡されます。非同期関数もサポートされており、外部サービスとの連携も可能です。 🛠 使い方 カスタムメトリクス関数を作成し、評価設定JSONに登録します。 ```python from google.adk.evaluation.eval_metrics import EvalStatus from google.adk.evaluation.evaluator import EvaluationResult async def response_length_metric( eval_metric, actual_invocations, expected_invocations, conversation_scenario ) -> EvaluationResult: # 応答の長さが適切か評価 last_response = "".join( part.text for part in actual_invocations[-1].final_response.parts ) score = 1.0 if len(last_response) < 500 else 0.5 return EvaluationResult( overall_score=score, overall_eval_status=( EvalStatus.PASSED if score >= eval_metric.criterion.threshold else EvalStatus.FAILED ), ) ``` 評価設定JSONでは、`criteria`（閾値）と `custom_metrics` の `code_config.name`（関数のインポートパス）を指定して登録します。 ```json { "criteria": { "response_length": {"threshold": 0.8} }, "custom_metrics": { "response_length": { "code_config": {"name": "my_metrics.response_length_metric"} } } } ``` 🏗 本番システムへの組み込み方 ・ドメイン固有の品質基準（正確性、トーン、コンプライアンス等）をメトリクスとして実装する ・CI/CDパイプラインでカスタムメトリクスを自動実行し、品質閾値を下回った場合にデプロイをブロックする ・非同期メトリクスを活用して、外部の評価APIやLLM-as-a-Judgeと連携する ・複数のメトリクスを組み合わせて、エージェントの総合的な品質スコアを算出する 💡 ユースケース 📏 応答の簡潔さや情報密度を独自基準で評価する 🏢 業界規制やコンプライアンス要件への準拠を自動チェックする 🎯 特定のツール呼び出しパターンが期待通りか検証する 🗣 応答のトーンや丁寧さをLLM-as-a-Judgeで自動採点する ⚠️ 注意点 カスタムメトリクス関数内で重い処理を行う場合、評価全体の実行時間に影響します。非同期関数を活用し、必要に応じてタイムアウトを設定してください。また、`code_config` のモジュールパスは評価実行環境からインポート可能である必要があります。 ✨ カスタム評価メトリクスにより、標準メトリクスではカバーしきれない独自の品質基準を体系的に運用できます。自社のユースケースに合わせた評価を構築しましょう。 #ADK# #AIAgent#