# AIエージェントをソフトウェアに組み込むプラクティス # Eval Harness｜評価ハーネス 🎯 プロンプトを変えたら品質が下がっていた、モデルが更新されていつの間にか精度が劣化していた――気づいたのはユーザクレームの後でした。評価ハーネスがあれば、デプロイ前に検知できます。 🔥 解決する課題 AIエージェントは確率的であり、コードの単体テストのように全入力に対して正解が決定論的に定まりません。ハルシネーションは個別の目視確認では検出しきれず、LLMドリフト（プロバイダ側のモデル更新による品質変動）は自チームが何も変更していなくても発生します。評価ハーネスがなければ、品質劣化は本番のユーザクレームとして初めて顕在化します。 💡 提案パターン ゴールデンデータセット（入力と期待出力のペア）と自動評価関数（完全一致・LLM-as-Judge・カスタムメトリクス）を組み合わせた評価パイプラインを構築します。プロンプト・モデル・コードの変更ごとにCIで回帰検知を行い、変更がなくても日次〜週次の定期実行でLLMドリフトを検知します。評価はオフライン（デプロイ前バッチ）、オンライン（本番サンプリング）、シャドウ（A/B比較）の3層で実施します。回帰ゲートの閾値は安全性カテゴリでは劣化0件を推奨します。 ✅ 選定条件 使うとき： - エージェントが本番トラフィックを処理し、プロンプト・モデル・コードを継続的に変更する - 品質変化を定量的に示す必要がある（SLA遵守・規制報告等） - ゴールデンデータを作成・維持できるドメイン知識がある 使わないとき： - プロトタイプ段階でプロンプトが日単位で大幅に変わる - 出力がクリエイティブ生成（小説・詩）で正解の定義が困難 - 後段に決定論的検証ロジックがあり誤りが自動修正される ⚠️ 落とし穴 - ゴールデンデータは腐敗します。仕様変更に伴い期待出力が古くなると正しい出力が「回帰」と判定されます。オーナーと最終更新日を付与し定期棚卸ししてください - LLM-as-Judgeも確率的です。温度0でも判定が揺れる場合があるため、重要ケースでは3回実行の多数決を検討してください - ベースラインスコアの更新タイミングを明示的に定めておかないと、劣化が見えなくなります 🔧 実装方針 - ゴールデンデータセット（入力と期待出力のペア）にカテゴリ・評価関数名・期待キーワードを構造化して定義し、カテゴリ別に集計・回帰判定します - 評価パイプラインはオフライン（CI上でのデプロイ前バッチ）、オンライン（本番サンプリング）、シャドウ（新旧A/B比較）の3層で運用します - 回帰ゲートはベースラインとの相対比較で判定し、安全性カテゴリでは劣化0件、一般カテゴリでは概ね2%以内の劣化を閾値とします - シャドウ実行では副作用を持つツール実行をドライランにし、カナリアデプロイではsticky sessionで同一ユーザーを同一バージョンに固定します - ゴールデンデータにオーナーと最終更新日を付与し、仕様変更に伴う腐敗を定期棚卸しで防止します #AIエージェント# #ソフトウェアアーキテクチャ#

学習データにgoldサンプルのラベルつけていくevalは本当に面倒 ラベラーのUIがいけてないせいでミスラベリングが普通に起きるから、かなり知識もあって執念深い人にUIを磨かせないとゴミデータになる AIといってもその技術の根幹にあるのは心理学と根性だったという

# ADKの便利で実践的な使い方 📏 エージェントの品質を「何で」測るかは、評価の成否を分けます。ADKのEvaluation Criteriaは、ツール軌跡の正確性からハルシネーション検出、安全性評価まで、多角的な評価基準を組み込みで提供します。 📌 タイトル：Evaluation Criteria 🔗 URL： 🧩 概要 ADKは複数の組み込み評価基準を提供し、すべて0.0〜1.0のスコアで評価結果を返します。**tool_trajectory_avg_score**はエージェントのツール呼び出し順序を検証し、**response_match_score**はROUGE-1でレスポンスの一致度を測定します。**hallucinations_v1**はコンテキストに対する回答の根拠を検証し、**safety_v1**は有害コンテンツの有無を評価します。**multi_turn_task_success_v1**は複数ターンの会話でタスク達成度を測定します。 🛠 使い方 各評価基準はJSON設定ファイルで定義します。 **tool_trajectory_avg_score** — 3つのマッチタイプを選択できます。 ```json { "criteria": { "tool_trajectory_avg_score": { "threshold": 1.0, "match_type": "EXACT" } } } ``` - `EXACT`: 期待されるツール呼び出しと完全一致（余分な呼び出しも不足も不可） - `IN_ORDER`: 期待されるツールが順序通りに出現（間に他の呼び出しがあってもOK） - `ANY_ORDER`: 期待されるツールがすべて存在（順序は問わない） **response_match_score** — ROUGE-1によるユニグラム一致度です。 ```json { "criteria": { "response_match_score": 0.8 } } ``` **hallucinations_v1** — レスポンスの各文をコンテキストに対して検証します。 ```json { "criteria": { "hallucinations_v1": { "threshold": 0.8, "judge_model_options": { "judge_model": "gemini-flash-latest" }, "evaluate_intermediate_nl_responses": true } } } ``` 各文には「supported（支持）」「unsupported（不支持）」「contradictory（矛盾）」「disputed（議論あり）」「not_applicable（該当なし）」のラベルが付与されます。スコアはsupportedとnot_applicableの割合で計算されます。 **safety_v1** — ヘイトスピーチ、ハラスメント、危険な情報の有無を評価します。 ```json { "criteria": { "safety_v1": 0.8 } } ``` **multi_turn_task_success_v1** — 会話全体を通じたタスク達成度を評価します。 ```json { "criteria": { "multi_turn_task_success_v1": 0.8 } } ``` 🏗 実践的な使い方 **ツール軌跡の厳密な検証**: 金融取引や医療情報など、ツールの呼び出し順序が重要なドメインでは`EXACT`マッチタイプを使用します。例えば「まず認証→次に残高確認→最後に送金」という順序が厳守されるべきケースで、エージェントが正しい手順を踏んでいるかを検証できます。 **柔軟なツール検証**: 探索的なタスクでは`ANY_ORDER`を使い、必要なツールがすべて呼ばれたかだけを確認します。`IN_ORDER`は、主要なステップの順序は保証したいが、間に補助的なツール呼び出しを許容するケースに適しています。 **ハルシネーション検出の実践**: RAGベースのエージェントで`hallucinations_v1`を使用し、検索結果に基づかない情報をエージェントが生成していないかを自動検出します。`evaluate_intermediate_nl_responses`を有効にすれば、最終回答だけでなく中間的な回答も含めて検証できます。 **安全性とタスク達成の両立**: `safety_v1`と`multi_turn_task_success_v1`を組み合わせることで、「安全だがタスクを達成できないエージェント」や「タスクは達成するが不適切な内容を含むエージェント」を検出できます。 💡 ユースケース 🎯 金融・医療エージェントでのツール呼び出し順序の厳密な検証 🔍 RAGエージェントのハルシネーション自動検出 🛡 カスタマーサポートエージェントの安全性評価 📈 マルチターン対話でのタスク達成率の定量測定 ⚠️ 注意点 - `safety_v1`、`multi_turn_task_success_v1`、`multi_turn_trajectory_quality_v1`、`multi_turn_tool_use_quality_v1`はGoogle Cloudプロジェクトの設定（`GOOGLE_CLOUD_PROJECT`、`GOOGLE_CLOUD_LOCATION`環境変数）が必要です。 - LLMベースの評価基準はジャッジモデルの判断にばらつきがあります。`num_samples`を設定して複数回サンプリングし、多数決で結果を安定させることを推奨します。 - `response_match_score`はROUGE-1（単語の重なり）のみで意味的な同等性は評価しません。意味的な評価には`final_response_match_v2`を検討してください。 ✨ 適切な評価基準の選択は、エージェントの品質管理の基盤です。ドメインの特性に合わせてEXACT/IN_ORDER/ANY_ORDERを使い分け、ハルシネーション検出と安全性評価を組み合わせて多角的に品質を担保しましょう！ #ADK# #AIAgent#

# 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エージェントをエンタープライズシステムに組み込むプラクティス 【プロンプト・サプライチェーン管理】 💡 プロンプトを「こっそり変更」して本番の挙動が変わった経験はありませんか？ プロンプトをコード成果物として扱い、バージョン管理・レビュー・署名・evalを経てデプロイするパターンです。 🔥 解決する課題 - プロンプト変更の追跡・レビューができず、品質劣化の原因が特定できない - 外部入力がプロンプトテンプレートに注入され、意図しない動作を引き起こす - どのバージョンのプロンプトで生成された結果か追跡できず、再現性が失われる 🏗️ 提案パターン プロンプトをGitとレジストリで管理し、変更にはPR・コードレビューを必須とします。変更時はeval gateの通過を必須にし、ゴールデンデータセットに対する品質チェックを自動実行します。本番デプロイされたプロンプトには署名を付与して改竄検知を行い、テンプレート変数への外部入力には区切り・サニタイズ・最小権限化によるインジェクション対策を施します。ソフトウェアのCI/CDと同等の品質管理プロセスをプロンプトに適用する考え方です。 ✅ 選定条件 - 向き：本番運用で複数人が開発に関わるエージェント - 不向き：使い捨ての実験やPoC（統制のオーバーヘッドが見合わない） ⚠️ 落とし穴 - プロンプトの変更をコードと同等に扱う文化が根付かないと形骸化します - 署名・改竄検知を導入しないと、悪意ある変更や事故的な変更を検出できません - eval gateのゴールデンデータセットを更新し続けないと、新しい問題パターンを検出できなくなります 🛠️ 実装方針 1. プロンプト・システム指示・テンプレートをGitリポジトリで管理し、変更には必ずPR・コードレビューを必須とします 2. CI/CDパイプラインにeval gateを組み込み、変更のたびにゴールデンデータセットに対する品質チェックを自動実行します 3. 本番デプロイされたプロンプトにHMAC等の署名を付与し、デプロイ時に改竄されていないことを検証します 4. テンプレート変数への外部入力に対して、区切り文字（delimiter）・サニタイズ・最小権限化によるインジェクション対策を実装します 5. プロンプトレジストリでバージョンと本番適用履歴を一元管理し、問題発生時に即座にロールバックできる仕組みを整備します #AIエージェント# #エンタープライズアーキテクチャ#

💻 最強クラスのコーディングAIでも、非プログラマー相手だとスコアが半分以下に落ちる…そんな現実を突いたベンチマークが登場しました。 タイトル: SWE-Journey: Towards More Realistic Evaluation of Coding Assistants through Long-Horizon, Multi-Turn Interaction URL: ❓ 何が課題だったの？ 既存のコーディング評価ベンチマークは、タスクが短く、かつ要件を最初から全部提示してしまうものが多く、実際のユーザーが段階的に要望を出していく現実の使われ方を反映できていませんでした。 ❓ SWE-Journeyは何が違うの？ 平均10.2ファイル・768行規模の長期タスクを自動合成し、Claudeの実対話ログから抽出した「非プログラマー」「プロダクトマネージャー」「新人開発者」「ソフトウェアアーキテクト」という4つのペルソナがAIと何十ターンもやり取りしながら評価します。 ❓ 結果はどうだったの？ 最高性能のモデルでもFinal F2P（最終的な機能実装成功率）は52.22%にとどまりました。しかもソフトウェアアーキテクト相手では78.50%出せるのに、非プログラマー相手だと23.00%まで落ち込み、差は55.50ポイントにも及びます。 ❓ なぜそんな差が出るの? 弱いモデルは曖昧な要求を聞き返さず、見当違いの箇所に過信して固執し、根拠なく「修正完了」と報告してしまう傾向が確認されています。相手に応じて質問の仕方や確認の仕方を変える力が、実力の差になっていました。 #AIコーディング# #LLM評価#

「このタスクに合うベンチマークってどれだっけ」を毎回散らばった情報源から探すの、地味に時間を食いますよね。 タイトル: Benchmark Radar: A Living Database and Search Engine for AI Benchmarks and Evaluation URL: ❓ Benchmark Radarって何？ 💡 arXiv・Hugging Face・GitHubなど37ソースを日次で巡回し、ベンチマークの論文・データセット・リポジトリ・スコア履歴を1つの検索エンジンにまとめたツールです。CLIでオフラインクエリもできます。 ❓ どれくらいの規模のデータを扱っているの？ 💡 4つのカタログから1,283件のソースレコード、790ベンチマークにまたがる12,916件の数値スコアを収録。日次収集だけで6,546アーティファクトから11,068件の観測を記録しています。 ❓ なぜ単純にスコアを比較できないの？ 💡 スコア付きレコードのうち0〜100の検証済みパーセンテージスケールを使っているのはわずか82件。残りは異なるスケールや未検証のスケールで、公開日も約半数が不明なため、単純比較は危険なんです。 ❓ だからどうするの？ 💡 無理に比較可能にするのではなく、出典と引用を保持して読者自身が評価条件を検査できるようにする、という設計を取っています。 #LLM評価# #ベンチマーク#