エージェンティック・ハーネス設計ガイド — Part 6
検証・評価
できたと、誰が確かめるか。
自分が作ったものの評価を求められると、エージェントは自信をもって称賛します。だから「できました」は、それ自体では何の情報も持ちません。確かめる側を、作った側の外に置く必要があります。
Part 1の7層でいう L6 検証・可観測性 を扱います。ここが弱いと、「できたつもり」が通ってしまう——表面上は正常に完了し、結論だけが間違っている状態が生まれます。
この記事は、原理原則12箇条のうち 09「検証はエージェント自身以外に行わせ、環境の状態を採点する」 の各論にあたります。
1.応答文ではなく、環境の状態を採点する
評価設計で最初に決めるのは、何を読んで合否を出すかです。ここを間違えると、以降の作り込みがすべて無駄になります。
合格条件は、機械が判定できる形にします。テストが通るか、ビルドが成功するか、データベースに行があるか、ファイルが期待どおりの内容になっているか。エージェントに「自分で走らせて確かめられるもの」を渡せると、見張らなくてよいセッションになります。
逆に言えば
合格条件を検証できる形で書けないタスクは、まだエージェント化しないほうが安全です。採点できないものは、改善もできません。この判断はPart 7の Stage 00 で扱います。
2.1回できた と 毎回できる は、別の指標
デモが通ったのに本番で落ちる、という現象の多くは指標の取り違えで説明できます。
この違いが効くのは、回帰テストの設計です。変更のたびに1回だけ走らせて合否を出す運用は、ほぼ意味を持ちません。同じ変更を複数回試行し、統計的に判定する必要があります。合否と一緒に、その試行にかかったコストも見ておくと、後で「どこまで厳しくするか」を議論できます。
3.評価セットは、失敗から育てる
「まず評価セットを作りましょう」と言われて、机上で理想的なタスクを並べても、実際に起きる失敗とはずれます。順序が逆です。
- 分類は<b>自由記述で書いてから、まとめて名前を付ける</b>。先にカテゴリを決めると、そこに当てはめてしまう。
- 新しいカテゴリが<b>20件連続で出なくなったら</b>、分類作りは止める。以降は週10〜20件を見る。
- 評点は<b>5段階ではなく二値</b>にする。「まあまあ」は、後から何も判断できない。
- 評価に割く時間を惜しまない。実務家の間では、<b>開発時間の6〜8割をエラー分析に充てる</b>という水準が語られている。
スコアが 0% のときに疑うもの
多くの場合、モデルではなくタスクのほうが壊れています。採点の硬直（数値の丸め方の違いを不一致と判定するなど）や仕様の曖昧さを直しただけで、スコアが大幅に改善した例が報告されています。0% は「モデルが無能である証拠」ではなく「タスクを見直す合図」です。
4.審査員そのものを、先に検証する
採点をモデルに任せる（LLM-as-judge）のは実用的な手ですが、検証していない審査員は測定器ではありません。もう一つの意見が増えただけです。
とくに注意が要るのが、「完了したと主張しているが、実際には状態が伴っていない」という失敗の検知です。この型は応答文が正常に見えるため、審査員にとっても難しい部類になります。ここは審査員に頼りきらず、環境の状態を直接読む採点と併用するのが安全です。
5.評価環境は、エージェントにとって敵対的である
見落とされがちですが、エージェントは「採点される」という状況にも適応します。タスクを解かずに満点を取る経路が実際に報告されています。
自社の評価環境でも同じ確認が要ります。「期待値」がエージェントから到達できる場所にないか。設定ファイル、テストの固定値、ログ、環境変数——どれも経路になり得ます。評価を作ったら、まずここを見てください。
6.実行環境の設定だけで、スコアは動く
もうひとつ、スコアを読むときの前提です。スコアはモデル単体の性質ではありません。
報告されている例では、実行環境の設定を変えただけでスコアが6ポイント動きました（統計的に有意）。一方、控えめな範囲での増減は誤差の範囲でした。運用ルールとしては、3ポイント未満の差を有意と扱わないこと、そして測定時の設定をスコアと一緒に記録・公開することになります。
この話はPart 7の「ベンチマーク値は自社に移植されない」につながります。
7.後から辿れるログを、先に設計する
評価が「合否」を出すものだとすれば、可観測性は「なぜそうなったか」を出すものです。後から足すのが最も難しい部類なので、最初に決めます。
共通の語彙としては、生成AI向けのトレース規約が整備されつつあります。ただし仕様はまだ開発中の位置づけなので、採用する場合はバージョンを固定し、変更に追随する前提で扱ってください。
入出力の本文をどこまで残すかは、別に決めます。既定では残さず、必要な範囲だけ明示的に有効化する。個人情報の問題と、単純に量の問題の両方があるためです。
8.失敗を、評価へ戻す
ここまでを一本の輪にすると、こうなります。
評価セットは資産です。増え方が止まったら、直ったのではなく拾えていない可能性を疑います。本番で起きている失敗が評価に反映されていない状態は、静かに悪化していきます。
9.アンチパターン早見表
ここまでの内容を、実装で見かける形にして並べます。
| よくある実装 | 何が問題か | どうするか |
|---|---|---|
| 生成した本人に採点させる | 自分の成果を、自信をもって称賛する | 生成と評価を分け、環境の状態を直接調べる |
| 応答文（トランスクリプト）を採点する | 「締めの一文の流暢さ」を測っているに等しい | 実行後の環境の状態で合否を出す |
| CI で1回だけ実行して合格判定 | 毎回成功する確率は、1回成功する確率よりずっと低い | 複数回試行し、統計的に判定する |
| 評価セットを机上で作る | 実際に起きる失敗と、ずれる | 本番の失敗トレースから育てる |
| 審査員（LLM judge）を検証せずに使う | 測定器ではなく「もう一つの意見」にすぎない | 保留した人手ラベルで、見逃しと誤検知を測る |
| 1人の審査員に複数の観点を聞く | 観点が混ざり、どれで落ちたか分からない | 1観点につき1審査員。「不明」を許す |
| 採点器をエージェントと同じ環境に置く | タスクを解かずに正解を読んで満点を取れる | ファイルシステムもプロセスも分離する |
| ベンチマーク値をモデルの性能として扱う | スコアは モデル×ハーネス×実行環境×採点器 の関数 | 自社ハーネスで測り直し、設定も一緒に記録する |
| 書き込みだけをログに残す | 状態遷移が無く、後から再現も原因特定もできない | 状態遷移とメモリ操作も記録する |
Summary
この記事の要点
- 1自分が作ったものを採点させると、エージェントは自信をもって称賛する。確かめる側を、作った側の外に置く。
- 2応答文ではなく、実行後の環境の状態を採点する。合格条件は機械が判定できる形にする。
- 3「1回できた」と「毎回できる」は別の指標。無人で回す本番の信頼性は、k回すべて成功で見る。
- 4単発実行での回帰ゲートはほぼ意味がない。複数回試行して統計的に判定する。
- 5評価セットは机上で作らず、本番の失敗から育てる。分類は新カテゴリが20件連続で出なくなったら止める。
- 6評点は二値にする。「まあまあ」は後から何も判断できない。
- 7スコア 0% は、モデルではなくタスクが壊れている合図であることが多い。
- 8審査員（LLM judge）は、保留した人手ラベルで検証してから使う。1観点1審査員、「不明」を許す。
- 9採点器はエージェントから到達できない場所に置く。評価環境は敵対的である。
- 10スコアは モデル×ハーネス×実行環境×採点器 の関数。実行環境の設定だけで6ポイント動く。3ポイント未満は誤差。
- 11ログは状態遷移まで残す。これが後の再現と原因特定を可能にする。本文は既定で残さない。
- 12本番の失敗を評価セットへ戻す輪を閉じる。増え方が止まったら、拾えていないだけの可能性を疑う。
Deeper
実装の視点で、さらに深く
この記事は製品に依存しない設計論として書いています。実装としてどう組んだかは、homula.ai の技術解説で扱っています。
Sources
出典・参考文献
本記事は、以下の一次資料をもとに整理しています。数値・仕様は各出典の公開時点のものです。
- Anthropic — Effective harnesses for long-running agents（成果採点・pass^k・評価セットの作り方）
- Anthropic — Harness design for long-running application development（生成と評価の分離）
- Anthropic — Writing effective tools for agents
- OpenTelemetry — Semantic conventions for generative AI（可観測性の共通語彙。仕様は開発中）
- Hamel Husain & Shreya Shankar — エラー分析と LLM-as-judge の実務
本記事では、追試が確立していない数値の引用を避けています。機序（なぜそうなるか）は設計判断に使えますが、2026年の知見にはプレプリントやベンダーの自己申告が多く含まれるためです。
FAQ
よくある質問
応答文ではなく、実行後の環境の状態を採点します。「返金を処理しました」という文面は、実際には何も処理されていなくても流暢に書けます。返金レコードが実際に存在するか、金額と対象が合っているかを、環境から直接読んで判定します。エージェント自身の申告を根拠にしないのが原則です。
自分が生み出した成果物の評価を求められると、自信をもって称賛する傾向が報告されています。生成する側と評価する側を分けることが、評価設計で最も効くレバーのひとつです。可能なら、評価は静的なレビューではなく、実際に動かして環境の状態を確かめる形にします。
pass@1 は「1回でも成功すれば合格」、pass^k は「k回すべて成功して合格」です。前者は人がその場で選び直せるコーディング補助の指標で、後者は無人で回す本番の信頼性の指標です。同じタスクを8回走らせて6回成功なら、前者では合格ですが後者では不合格です。単発実行での回帰ゲートはほぼ意味を持ちません。
机上で作るのではなく、実際の失敗から育てます。本番や試用のトレースを100件以上集めて分類を立て、再現できる評価タスクを20〜50件作るところから始めます。分類作りは新しいカテゴリが20件連続で出なくなったら止め、以降は週10〜20件を見ます。評点は5段階ではなく二値にします。「まあまあ」は後から何も判断できないためです。
多くの場合、タスクのほうが壊れています。採点の硬直（数値の丸め方の違いを不一致と判定するなど）や仕様の曖昧さを直しただけで、スコアが大幅に改善した例が報告されています。0% は「モデルが無能である証拠」ではなく「タスクを見直す合図」として扱ってください。
そのままは使えません。スコアはモデル単体ではなく、モデル × ハーネス × 実行環境 × 採点器の関数です。実行環境のリソース設定を変えただけでスコアが6ポイント動いた報告があり、3ポイント未満の差は誤差として扱うのが妥当とされています。自社のハーネスで測り直し、測定時の設定をスコアと一緒に記録してください。
実行基盤を、自社で持ちたい方へ
homulaは、AIエージェント実行基盤の要件定義から設計・構築・運用までを支援しています。評価と受入条件の設計は、開発に入る前に定めておくべき領域です。