agent-evaluation

エージェント評価

リリース責任者の判断材料となる証拠を構築します。好都合な例を披露したり、安全性を認証したりするためのものではありません。

使用する場面

• エージェントの構築や変更に着手する前に、品質を定義します。
• プロンプト、モデル、ツール、メモリ戦略、オーケストレーションパターンを比較します。
• 本番環境での障害を回帰テストケースに変換します。
• 再現可能なリリースゲートや人間によるレビュー計画を策定します。

入力

エージェントの目的、ユーザー、対応タスク、許容できない結果、現在のベースライン、実行環境、利用可能なトレース、評価予算を収集します。入力を入手できない場合は、前提を明記します。

出力要件

以下を作成します。

1. 対象範囲、リスク、仮説、固定したシステムバージョンを記載した評価ブリーフ。
2. 出所、カテゴリ、分割、汚染防止策を記載したデータセットマニフェスト。
3. ルーブリック、評価者、しきい値、同点時の判定ルールを記載したスコアリング仕様。
4. 再現可能な実行設定、集計結果、不確実性、ベースラインとの差分。
5. 失敗の分類体系、代表的なケース、証拠の限界、説明責任を負うリリース責任者向けの判断メモ。

ワークフロー

1. テスト対象の単位と、評価で裏付けるべき判断を定義します。モデルの品質と、ツール、検索、ポリシー、インフラに起因する障害を分けて扱います。
2. ユーザーの目標とリスクを、観察可能な基準に変換します。関連する場合に限り、タスクの成功、安全性、レイテンシ、コスト、エスカレーションの品質を含めます。
3. 許可されている場合は、実際の分布に基づいて代表的なケースを構築します。境界ケース、ロングテール、不正な入力、ツール障害、敵対的なケースも追加します。プロンプトの反復改善からホールドアウトセットを隔離します。
4. 主観性が最も低く、信頼性の高い評価者を選びます。構造化された事実には決定論的チェック、意味的な品質にはルーブリックに基づくモデル評価者、影響の大きいケースや見解が分かれるケースには、ブラインド形式の人間によるレビューを優先します。評価者やゲートを選ぶ際は、evaluation-patterns.mdを参照してください。
5. プロンプト、モデルのバージョン、ツール、データスナップショット、対応している場合はシード、再試行、タイムアウトを固定します。候補とベースラインを同等の条件で実行し、確率的なケースは繰り返し実行します。
6. 集計結果を信頼する前に、ケースごとの失敗を確認します。サンプル数が十分な場合は、タスク、リスク、言語、ツール、ユーザーコホートごとに結果を分けて分析します。
7. 重大なケースでの最低性能、ベースラインに対する非劣性、運用上の制限を組み合わせてリリースゲートを設定します。検出力が不十分な結果は、結論が出ていないものとして明示します。
8. 個人データを露出させずに、本番環境に近い状況で発生した失敗ケースを回帰テスト用のフィクスチャとして保存します。

python3 scripts/aggregate_results.py results.jsonl --score-min 0 --score-max 1 --require-passedを実行し、識別情報と宣言されたスコア範囲を検証してから、記述的な要約を作成します。レコードでvariantラベルにoldとnewを使用している場合は、--baseline old --candidate newを追加します。--output summary.jsonを指定すると、ファイルへの書き込みがアトミックに行われます。出力先は新しいパスまたは通常のファイルでなければならず、表記、解決結果、シンボリックリンク、ハードリンクのいずれによっても入力と同一のパスを指定できません。このスクリプトは、合格率の分母について、観測済み、欠損、合計の各件数と、おおよその不確実性を明示して報告します。安全性、代表性、統計的有意性、リリース準備完了を認証するものではありません。

安全性と権限

• 許可と承認済みの保持ポリシーがない限り、非公開のプロンプト、顧客データ、認証情報、専有の出力を外部の評価者に送信しないでください。
• 明示的な許可なしに、本番システムを対象とした評価、有料 API 予算の使用、状態を変更するツールの実行を行わないでください。
• 医療、法律、金融、雇用、安全性、アクセス制御に関する判断では、資格を持つ人間によるレビューを必須としてください。
• 評価者のスコアは真実そのものではなく証拠として扱い、モデル評価者の識別情報と利益相反を開示してください。

検証

• すべてのリリース基準が少なくとも1つのケースに対応し、すべての重大なリスクに負のテストがあることを確認します。
• 学習用、開発用、ホールドアウト用のケースが、意味的にもソース識別子の点でも重複していないことを検証します。
• サンプルを手動で再実行し、評価者の判定をルーブリックと照合します。
• ベースラインと候補が同一条件を使用したこと、および報告された分母で、合格ラベルがないもの、失敗、タイムアウトがすべて特定されていることを確認します。すべてのレコードを合格率の分母に含める必要がある場合は、--require-passed を使用します。
• レポートに、重要な主張を再現するために必要なケース単位の証拠が保持されていることを確認します。

失敗への対応

• 代表的なデータが不足している場合は、探索的評価であることを明記して実施し、本番ゲートを設定する前にデータを要求します。
• 評価者の意見が一致しない場合は、ルーブリックを明確化し、比較対象を伏せたうえで、層化サンプルを裁定します。
• 結果が安定しない場合は、反復回数を増やし、非決定的な依存関係を切り分け、信頼区間または範囲を報告します。
• 重大なケースで失敗した場合は、権限を持つ責任者がリスクを受け入れるまで、全体平均にかかわらずリリースをブロックします。

例

「カスタマーサポートエージェントの2つのバージョンを比較する」場合、解決の正確性、引用の忠実性、ポリシー遵守、エスカレーションの判断、レイテンシー、コストを定義します。通常、曖昧、多言語、プロンプトインジェクション、利用できないツールのケースを作成し、バージョンラベルを伏せて両バージョンをそれぞれ3回実行します。ケースカテゴリ別に集計してリグレッションを調査し、証拠とともにリリース、保留、限定ロールアウトのいずれかを決定します。