agent-evals

エージェント評価 — 動作を検証する

エージェントの振る舞いはソースコードの中にはありません。コードが示すのは、何をすることが許されているかだけです。実際に何をしたかを示すのは、実行結果だけです。したがって、テスト対象となる成果物は実行記録であり、評価スイートは2つの時計で動きます。観測可能なものは実装が存在する前にあらかじめ記述され、実行対象となるコーパスは本番環境から拡充されます（§6）。

ここから3つの主張が導かれます。これらこそが、通常のコードのテストとは異なる点です。

• テストするのはコードパスではなく推論です。そのため、1つの粒度だけでは不十分です。
• 自然言語の入力は一つひとつ異なるため、エッジケースをオフラインで列挙することはできません。本番環境は、見落としを見つける場所であるだけでなく、何をテストすべきかを発見する場所でもあります。
• **トレースはテストケースになります。**コーパスは実際に起きたことをもとに拡充されますが、評価の基準は変わりません。

---

トリガー

「trajectory eval」、「checker node」、「エージェントは改善しているか」、「エージェントの評価」、「エージェントの確認方法」。

0.31.3 の説明から移動：「リグレッション用テストスイート」。

1. 3つの基本要素

基本要素	内容	含まれるもの
実行	1回のモデル呼び出し	指示、ツール、コンテキストを含む完全なプロンプトと、返された内容
トレース	1回の完全な実行	すべての実行、引数と結果を含むすべてのツール呼び出し。ステップ間の関係を示すネスト構造
スレッド	1つのセッション内の複数のトレース	順序付けられた複数ターンのコンテキスト、状態の変化（メモリ、ファイル、成果物）、経過時間

スレッドの粒度は、ほとんどのシステムに欠けているものです。そして、欠陥の一群が潜んでいる場所でもあります。6ターン目に不適切なメモリ書き込みがあると、11ターン目に誤った回答として表面化しますが、実行ビューでもトレースビューでも原因を特定できません。

**これらすべての前提条件は、トレースが永続的に保存され、クエリ可能であることです。**ライブイベントストリームは進捗バーを表示して消えてしまいます。先週のスコアが低かった実行を ID で取得できないのであれば、以下で説明することは何も利用できません。§7 を参照してください。

---

2. 3つの粒度

各基本要素には、それぞれ異なる種類のアサーションを適用します。

単一ステップ — 実行を検証する

フィクスチャはシリアライズされた実行です。プロンプト、ツールスキーマ、コンテキストが含まれます。その時点での判断、つまりツール名や引数の形式をアサートします。

find_meeting_times、schedule_meeting、send_email が使用可能な状態で「明日の午前中に Harrison との会議を設定して」と指示された場合、最初に find_meeting_times を呼び出さなければなりません。

最初にというアサーションが正当なのは、この粒度だけです。フィクスチャは単一の判断であるため、順序に関する主張が代理指標ではなく、直接の評価対象になります。軌跡全体にわたる場合は、そうではなくなります。§5 を参照してください。

低コストで、決定論的であり、CI の失敗要因になります。**前提条件は、エージェントのアーキテクチャが安定していることです。**これらはグラフのリファクタリングで失敗し、リファクタリングのたびに失敗するテストスイートは削除されます。

全ターン — トレースを検証する

3つの異なる仕組みを使い、3つの軸を同時にアサートします。

軸	アサートする内容	使用する仕組み
軌跡	してはならないこと、必ず実行しているべきこと、必須の先行関係。厳密な実行順序全体ではない	集合／部分集合マッチャー、禁止する呼び出しのリスト、部分順序（a が b より前）
最終応答	品質、トーン、ポリシー遵守	ルーブリックまたはジャッジ
状態変化	メモリの行が存在すること、ファイルが書き込まれていること、成果物が存在すること	副作用の直接検査

3つ目の軸は、見落とされがちです。**文章だけでなく、副作用もアサートしてください。**好みを保存したと言いながら実際には保存していないエージェントは、3つの軸のうち2つでしか合格していません。

生成が最も簡単な入力と、自動検証が最も難しい出力です。

マルチターン — 会話スレッドを検証する

各ターンの後にチェックポイントを設け、逸脱したら即座に失敗とする、スクリプト化されたターンシーケンスです。これがないと、3ターン目で話が脱線し、4～10ターン目では何も検証されないまま結果だけが報告されます。

1ターン目：「JavaScriptよりPythonのほうが好きです。」3ターン目の出力も、Pythonのままでなければなりません。

うまく実装するのが最も難しいものです。まずは、ターンをまたいだ記憶に本当に関係する動作だけを対象にしてください。

本番用スイートでは3種類すべてを組み合わせます。 あるベンダーの報告によると、そのスイートの約半分は単一ステップのテストです。これはベンダーの所見として記録されたものであり、目標とすべき割合ではありません。

---

3. オフライン、オンライン、アドホック

タイミング	参照情報	リリースをブロックするか	答えられること
オフライン	データセット。正解データは任意	はい — これがリリース判定です	変更によって、これまで動作していたものが壊れていないか
オンライン	なし — 定義上、参照情報は不要	いいえ	本番環境で挙動にずれが生じているか
アドホック	なし	いいえ	実際に何が起きているか

オフライン評価は必要ですが、それだけでは不十分です。 テストスイートがすべて合格すれば、すでに把握しているケースでデグレードが発生していないことは証明できます。しかし、誰も思いつかなかった入力はデータセットに含まれないため、エージェントがそれを適切に処理できるとは証明できません。そのためにオンライン評価の段階があります。

オンライン評価器はトレースの取り込み時に実行され、期待される答えがなくても確認できる項目をチェックします。たとえば、軌跡の異常、ステップ数やレイテンシの傾向、評価器によるスコア、エラー率などです。すべてのトレース、サンプル、またはフィルターを適用したサブセットを対象にできます。サンプリング率はコストの判断であり、正確性を左右するものではありません。

アドホック評価は、保存されたトレースを対象とする探索的分析です。たとえば、事前に定義されていなかった失敗パターンを見つけるためにクラスタリングします。ダッシュボードでは事前に選んだメトリクスを追跡しますが、アドホック分析では、まだ選んでいないメトリクスを見つけます。

---

4. スコアよりルーブリック

汎用的なメトリクス — 有用性、自然さ、完全性 — では、数値は得られても判断材料にはなりません。「有用性」が5点満点中3.4点だと言われても、何を変えるべきかはわかりません。

行動を具体的に絞った合否ルーブリックを作成し、その行動に責任を持つ人たちと一緒に書いてください。 各失敗は、プロンプト、ツールの説明、ワークフローのステップ、または不足している機能のいずれか1つを示すものでなければなりません。

うまく機能するルーブリックの全体例：

エスカレーション。 人間の対応を求められた場合：1回は引き留め、再度求められたらエスカレーションします。 次の場合は失敗です： すぐにエスカレーションする · 2回目の依頼後に拒否する · すでに持っている情報を提供する前にエスカレーションする · 明らかに役立っていない状態で何ターンも続ける。

注目すべき点は、その構成です。1つの行動、明確な合格条件、そして列挙された失敗条件です。これによって、評価器の判定を再現でき、意見の相違を解消できるようになります。

---

5. 評価者

まずは低コストのチェックから。 スキーマ検証、完全一致、形式への適合、ビジネスルールのアサーション、ツール呼び出しの正確性は、すべて決定論的で、モデル呼び出しよりも高速かつ低コストです。コードでは判断できないものだけを評価者に送ります。

軌跡を読み、照合はしないでください。 3 回の誤ったツール呼び出しを経て正解にたどり着くエージェントは、潜在的な障害です。それを検出するために正確な順序をアサーションで指定するのは、明らかに不適切な手段です。Anthropic は、その厳格な形式を否定しています。正確なツール順序のアサーションは「厳格すぎるうえ、過度にもろいテストを招きます。エージェントは、評価設計者が想定していなかった有効な方法を定期的に見つけるからです」。その実例では、エージェントが τ²-bench の予約タスクをポリシーの抜け穴を使って解決しました。評価としては失敗となった一方で、ユーザーにはよりよい対応を提供していました。何が生成され、何が変化したかを評価し、付随的な経路の違いは許容します。

反対側の問題も測定されています。軌跡を見ない評価者は、**安全性違反の 44％と堅牢性の問題の 13％**を見逃します。結果に正解が残っていても、そこに至る過程でポリシー違反があった可能性があるためです。結果だけでは確認できない事項、たとえば禁止された呼び出し、確認の欠落、秘密情報の読み取りには、軌跡を使い、集合と禁止リストとして評価します。

禁止すべきなのは、冗長な完全な全体順序であり、順序そのものではありません。意味上必須となる先行関係もあります。認可はその効果より前に行われること、依存する書き込みの前に最新の読み取りを行うこと、公開する処理の前にトランザクションをコミットすることです。これらは部分順序（a が b より前）としてアサーションし、完全順序にはしません。独立した 2 つの読み取りの順序を入れ替えても合格とし、確認と課金、取得と書き込みの順序を入れ替えた場合は不合格とします。また、否定的な例（課金後に確認する軌跡）を評価基準のそばに置きます。

評価者を信頼する前に、評価者を調整してください。 同じ軌跡に対する人間のラベルを集め、一致度を測定し、一致度が高くなるまで評価者のプロンプトを繰り返し調整します。その後で初めて、無人で採点させます。未調整の評価者は、数値が付いただけの意見にすぎません。それを頼りにリリースするのは、測定する代わりに採点するという失敗そのものです。

評価者ではできないこともあります。 もっともらしいが誤っている専門分野の出力、たとえば捏造された法的引用や、わずかな誤りのある SQL の結合条件は、一般的な評価者には正しいように見えます。こうしたものはその分野の専門家に回し、この段階は人間が担うものとして受け入れてください。

---

5a. チェッカーノード — グラフ内で動作する評価器

ここまでのすべての評価は、実行の後に行われます。実行の最中に動作する評価器が1つあります。多くのシステムに欠けているのがこれです。並列レイヤーと、それを利用するノードの間に配置されるチェッカーノードです。その役割は「使用可能／使用不可」の判定だけであり、収束はブランチではなくチェッカーノードに依存します。そうしなければゲートを迂回できてしまいます。

この分離は、単にこのパックの見解というだけでなく、実践の中で確かめられています。 Anthropicのハーネス設計ガイダンス（anthropic.com/engineering/harness-design-long-running-apps、2026-08-30閲覧）によれば、生成器に自己批判させるより、独立した評価器を懐疑的に調整するほうが実現しやすいとのことです。これは、ブランチに自分自身を評価させるのではなく、別のノードに判定を委ねる理由と同じです。日付と引用を記載することで、読者は、現場の動向と収束した原則と、ここで独自に考案した原則を見分けられます。

ここで重要なのは、これは§5と同じ仕組みを、配置だけ変えて使っているからです：

検出する問題	判定方法
欠落したブランチ — 到着数が、ファンアウトで約束された数に満たない	コードチェック
空またはnullの結果	コードチェック
根拠のない主張 — 読者が再確認できるものが何も添付されていない	コードチェック
利用するノードが解析できない不正な形式	コードチェック
矛盾する兄弟ブランチ。共有する前提を言い換えただけの2つも含む	ジャッジ
誰も尋ねていないことへの的外れな回答	ジャッジ

6項目のうち4項目は無料です。まずそれらを実行します。§5の低コストなチェックを先に行うという原則を、評価スイートではなくグラフ内の位置に適用します。

自信のないブランチはヒントであって、行ではありません。そのブランチ自身の信頼度の数値は任意であり、意図的に6項目には含めていません。 その理由は上記の§5にあります。未較正の情報源によるスコアは単なる意見なので、再試行の順序付けには使えても、ゲートを開くためには使えません。ゲートが求めるのは代わりに3行目、つまりレシートです。これも、このパックがほかの箇所でも信頼度より証拠を重視する理由と同じです。契約の定義と詳しい議論については、agent-orchestrator/references/graph-engineering.md §6を参照してください。

チェッカーもノードである以上、誤る可能性があり、その障害モードは黙って承認することです。 不正な入力を見たことがないモデルチェッカーは、何でも通してしまいます。そして、常に「はい」と答えるチェッカーを備えたグラフは、チェッカーのないグラフより悪いものです。欠けていたチェックポイントが、下流のすべてが信頼する偽のチェックポイントに置き換わっているからです。次の3点がその帰結です。これらはオーケストレーションではなく、評価の作業です。

• 信頼する前に、仕込んだ不正な出力を拒否する様子を確認します。これは、§5が、無人でスコアリングする前にあらゆるジャッジに求めていることと同じです。
• すべての判定を実行に紐づくスコアとして記録し、source: code_checkまたはllm_judgeを指定します（§7）。判定が保存されていないチェッカーには、事後にどの程度の頻度で作動したかを尋ねられません。つまり、較正できません。
• 何も拒否したことのないチェッカーは、安心材料ではなく、発見事項です。拒否率を合格率と同じダッシュボードに表示します。拒否率がゼロなら、上流が完璧なのか、ゲートが壊れているのかのどちらかです。どちらなのかを判断できるのは、保存された判定だけです。

チェッカーをグラフのどこに配置するのか、また、なぜ収束にチェッカーが必要なのかについては、agent-orchestrator/references/graph-engineering.mdを参照してください。

6. 2つの時計 — 先に観測可能なものを、コーパスは本番から

評価と呼ばれるものには2種類あり、作業の両端でそれぞれ作成されます。それぞれ別の名前を付けることで、どちらのルールも、もう一方の例外として読まれるのを防ぎます。

Tier	概要	作成時期	理由
Observable	要件が満たされたことを示す基準 — 合否ルーブリック（§4）、軌跡または状態変化のアサーション（§2）	実装が存在する前	Observable のない要件は未完成です。あとから追加すると、すでにコードを見たうえでテストを考案することになり、何を成功とみなすかを出力が決めてしまうためです。
Corpus	それらの基準を適用する入力 — フィクスチャ、データセット、本番環境で発生した最小化済みの障害	本番環境から取得し、事前には作成しない	自然言語の入力はすべて固有なので、エッジケースをオフラインで列挙することはできません。事前に考案した入力が試すのは、あなたの想像力です。

両者は異なる対象を規定するため、どちらのルールももう一方を緩めるものではありません。 Observable は成功とみなされる条件である基準です。Corpus はたまたま手元にある入力のサンプルです。基準は早期に書いてもコストがかからず、誠実な形で早期に書ける唯一のものです。一方、早期に書いたサンプルは、ユーザーが送ってこない入力に対して合格します。したがって、どちらも全面的に適用されます。Observable のないままリリースされる要件は未完成であり、本番データが一切含まれない Corpus は想像にすぎません。 要件自体は task-pipeline の REQ スパインから ID と完了条件を得ます。このパックが定めるのは Observable の形式であり、それが紐づく登録情報ではありません。

最初のリリースには本番データがありません。そのため、SEED コーパスを使って実行しますが、Observable だけではリリース可能とはみなされません。 入力がなければ基準は能力を何も証明しないため、グリーンフィールドの機能では、少なくとも 正常系、敵対的な入力、失敗／再試行の試行を含む、厳選／合成／手動のコーパスを用意します。各シード入力には由来（curated／synthetic／manual）を付与し、本番トレースで補完しますが、網羅性があるとは決して宣言しません。リリースゲートでは試行の実行済みが必須です。実行対象がない Observable は specification-ready であり、release-ready ではありません。破損したフィクスチャ、入力、ランナーは挙動の合否ではなく、TEST_ERROR です。各ケースは独立しているため、B の結果は A を実行したかどうかに左右されません。

各タスクは、エージェントの評価に使う前に、解けることを実証します。 それぞれに参照解を用意し、すべての採点器に合格する既知の出力を用意してください。多くの試行で合格率が 0％になる場合、「たいていは、エージェントの能力不足ではなく、タスクが壊れている兆候です」 （Anthropic）。解けないタスクは、試行を無駄にするだけではありません。不正を助長します。作成者が対象の約 30～40％は不可能だと見積もったベンチマークでは、「不可能なタスクがあると、エージェントは採点器を欺く方法を広く探し回るようになります」 （METR、どちらも 2026-10-19 に閲覧）。合格する参照解がないタスクは FAIL ではなく、TEST_ERROR です。

スイートを事前に作成してはいけません — つまり、コーパス、すなわち入力です。本番環境で発生した障害や低評価はすべてフィクスチャにします。

1. 障害発生時点の状態を記録します。
2. 再現できる最小の入力まで縮小します。
3. 該当箇所を切り分けられる階層（ステップ、ターン、スレッド）に追加します。
4. スイートに永久に残します。 修正したバグが気づかれないまま再発することを防ぐためのルールです。

レビューからは、次の 2 種類のデータセットが生まれます。

• 正解データ — レビュアーが正しい出力を記述し、スイートは完全一致をアサートします。
• 基準ベース — 自由形式の作業では、厳密な正解ではなく、関連性、完全性、トーンなどの観点をレビュアーがラベル付けします。

アノテーションキューが、どちらのデータセットにもデータを供給します。フィルターによって、トレースの一部を人間のレビュー担当者に振り分けます。対象となるのは、自動スコアが低いもの、低評価、特定の機能領域、クラスターなどです。レビュー担当者には 2 つの役割があり、混在させると両方の時間を無駄にします。ジェネラリストは表面的な品質を判断し、ドメインエキスパートは専門知識がなければ見抜けない正確性を判断します。 入力を生成する場合は、シミュレートされたユーザーを使います。 顧客を演じるモデルは、雄弁で、 辛抱強く協力的なため、あらゆる合格率を押し上げます。実際のユーザーの トランスクリプトでファインチューニングし、敵対的なペルソナ（返金を求める人、 AI に懐疑的な人、すぐに人間の担当者を求める人）を追加してください。 シミュレートされたユーザーの質を下げることで、オフラインの結果が予測に使えるようになります。

---

7. 最初に計測するもの

これらすべてのワイヤーフォーマットは references/otel-genai.md です。最初の スパンを記録する前に読んでおく価値があります。このセクションで必要となるもののうち、 スコアの出所と信頼できるコストの2つは、標準には含まれていないからです。

以下のものがなければ、上記のどれも実行できません。ここが見落とされがちな部分です。

• ID でクエリでき、スコアと時刻でフィルタリングできる、永続的なトレースストア。 ライブ ストリームはその上に表示されるビューであり、記録そのものではありません。
• 実行に紐づく第一級のレコードとしてのスコア：run_id、キー、値、および human | llm_judge | code_check のいずれかの source。出所のないスコアは、補正、 監査を行うことも、周囲のスコアと異なる信頼度で扱うこともできません。
• メッセージだけでなく、プロンプト全体 — 実際に送信された指示、ツールのスキーマ、 コンテキスト。要約からフィクスチャを再生することはできません。また、候補の バージョン、出力、スコアは、古いトレースの横に独立したレコードとして保存します — 保存済みの出力を再評価した場合は「再評価」とラベル付けし、「候補が 合格した」としてはいけません。判断が変わったと言えるのは、凍結されたフィクスチャに対して候補を実行した場合だけです（実際の、 確率的な呼び出しであり、レシートにコストが記録されます）。
• ターンの境界での状態スナップショット。スレッドテストで、引き継がれた状態をアサートできるようにします。

---

チェックリスト

• トレースをストリーミングするだけでなく、永続化し、ID でクエリできる
• スコアが実行に紐づき、それぞれに出所がある
• 変化させてはならない判断に対する、単一ステップのフィクスチャ
• 軌跡 と 最終応答 と 状態変化のすべてをアサートする、全ターンのテスト
• 各ターンの後にチェックポイントを設け、速やかに失敗する複数ターンのスクリプト
• オフラインのテストスイートをリリース判定基準とし、オンライン評価器は参照不要かつノンブロッキングにする
• 失敗条件を列挙した合否ルーブリックを、振る舞いの責任者とともに作成する
• モデルジャッジの前にコードチェックを行う
• ジャッジを信頼する前に、人間のラベルに対して補正する
• 各チェッカーノードが仕込まれた出力を拒否するかを監視し、その判定をスコアとして保存し、 ダッシュボードに拒否率を表示する — 拒否がゼロのチェッカーは、調査結果のひとつです
• 汎用ジャッジでは採点できない出力を、ドメインエキスパートがレビューする
• すべての要件に、実装前に記述された観測可能な指標がある — コーパスは本番を待ちますが、評価基準は待ちません
• 本番環境での失敗をすべて最小化し、恒久的なフィクスチャにする
• エージェントを採点する前に、すべてのタスクに参照解があり、その解が採点器に合格する
• フィルター付きのアノテーションキューを用意し、2つのレビュアーの役割を分けておく
• シミュレートされたユーザーを実際のトランスクリプトで学習させ、敵対的なペルソナを用意する
• 判断を変えるすべての比較で、n、k、リデューサー、ノイズ幅を明記する — references/statistics.md。100件で3ポイントの差はノイズです

---

参考資料

読み込む資料	内容
references/multi-agent.md	役割、共有メモリ、または委任を変更する場合 — チーム全体で、複合的な目的、維持される懸念、ソースの独立性、権限を評価します
references/statistics.md	数値を判断の変更に使おうとしている場合 — 差が実際にあると言えるまでに必要な実行回数、pass@k と pass^k の違い、および試行が独立ではない理由、対応のある比較、ハーネスを変数として扱うこと、特定の証拠が次に何を正当化するか
references/support-quality.md	エージェントが人々に回答する（チャット、メール、レビュー、グループ）場合 — ターンごとの記録、チャネルごとの目標を定めた4つの指標ファミリー、評価基準、評価者、support.quality_daily、週次の所見ループ
references/otel-genai.md	他の人が読めるようにエージェントを計装する場合 — スパン名の数式と固定された操作列挙型、採点者を示すフィールドがない評価イベント、3つのコンテンツ階層と、スパンが破棄された場合も実行されるアップロードフック、11個のトークン属性とコストの結合で両方向に誤りが起こり得る理由、「OpenTelemetry ベース」が単一の用語体系を意味しない理由

---

関連項目

測定対象のエージェントを構築するには、同じプラグインに同梱されている agent-orchestrator スキルを使用します。パッケージャーがどちらかのディレクトリのみを同梱する場合があるため、リンクではなく名前を記載しています。そのコンテキストエンジニアリングの参考資料では、軌跡アサーションがドリフトを最もよく検出するコンテキスト圧力の挙動を説明しています。