# Agent Evaluation Design

Builds agent evaluation systems with metrics, graders, regression tasks, and significance checks.

- Repository: https://github.com/bojieli/ai-agent-book (56844 stars)
- Category: Testing
- License: Apache-2.0
- Last updated: 2026-10-08
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add bojieli/ai-agent-book --skill agent-evaluation -g -a claude-code -y`
Codex: `npx skills add bojieli/ai-agent-book --skill agent-evaluation -g -a codex -y`
Cursor: `npx skills add bojieli/ai-agent-book --skill agent-evaluation -g -a cursor -y`
Gemini CLI: `npx skills add bojieli/ai-agent-book --skill agent-evaluation -g -a gemini-cli -y`

## Description

为 Agent 建立或改进评估体系时使用, , 设计评估指标（Pass@k/Pass^k/成本）、搭建可重复运行的评估环境、选择确定性验证器或 LLM-as-a-Judge 及各自适用边界、编写 Rubric、做失败归因与回归任务、评估驱动的模型选型、判断统计显著性、建设可观测性与内部评估基础设施（消融、AB 测试、特性开关、提示词回归）、从 Benchmark 报告走到系统改进。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Agent 评估体系

## 何时使用
- 为 Agent 系统建立第一套评估，或审查现有评估是否可信
- 选模型、换模型前需要数据依据（新模型公开分高，不代表在你的任务上更好，甚至可能回退）
- 评估分数下降，要判断是 Agent 退化还是评测系统本身出了问题
- 需要把"成功率下降"这类笼统结论拆成可着手修复的具体问题
- 为生产 Agent 建设内部评估基础设施：消融实验、AB 测试、特性开关、提示词回归
- 设计可观测性与生产轨迹回流，让评估集随产品持续演化

## 核心原则
- **评估的对象是"模型 + Harness"组合体，不是模型本身。** 同一模型在不同 Harness 下表现悬殊；表现不佳时先怀疑 Harness，再怀疑模型。
- **用模型替换实验（model swap）区分两类问题**：固定 Harness 只换模型，分数不涨 → 瓶颈在 Harness；分数随模型能力大幅波动 → 瓶颈在模型能力。消融实验则是关闭 Harness 组件、定位内部哪个部件重要，两者互补，别混用。
- **先检查评测系统，再动 Agent。** 分数下降先排查：运行环境资源不足导致的随机失败、验证器 bug 把对的判错、用例与生产脱节, , 这些在数字上与模型退化一模一样，只有回放完整轨迹能区分。
- **指标口径由业务场景决定。** 同一个 0.8，对退款客服意味着每五名用户一人拿不到退款，对漏洞挖掘已属可观。报告必须写清 k 的口径：同一任务的 k 次独立采样，还是生产流水线连续 k 个任务。
- **凡是能写成程序化断言的检查就用断言**，LLM 评判只用于确实无法机械判定的维度。确定性验证更便宜、更可复现，适合长期进 CI。
- **分差要超过噪声、在配对分析中成立、并且能够复现，才值得据此切换模型或发布改动。**
- **一轮证据只支持与它规模相称的下一步。** 子集 4/4 不能写成系统整体 100%，完整复测通过前不部署。

## 实践模式

### 1. 指标设计：Pass@k / Best@k / Pass^k
- **Pass@k**（k 次至少一次通过）与 **Best@k**（连续得分取最好）衡量能力上限，适合科研发现、漏洞挖掘、开放式创作, , 人类会从 k 条候选轨迹里挑出最好的那条。
- **Pass^k**（连续 k 次全部通过，且不触发安全、合规、幻觉等一票否决项）衡量业务可靠性，适合支付、退款、权限变更、生产部署。两者关系：Pass@k = 1-(1-p)^k，Pass^k = p^k。
- p=0.6、k=5 时：Pass@5 ≈ 99%，Pass^5 ≈ 7.8%, , 前一个数字回答"能不能偶尔创造奇迹"，后一个才回答"能否稳定交付"。
- 会产生副作用的操作不能"重试直到成功"：应在沙盒或可回滚环境中采样，每一次失败都记入可靠性指标。

### 2. 评估环境五要素
- **数据集**：初始状态、给 Agent 的输入、给模拟器的行为规范与验收标准，打包为一条记录即一个用例。
- **环境状态**：必须可重置（`initialization_actions` 即重置脚本）；真实性（变化符合业务逻辑）与可控性（每次回到同一起点）兼得。
- **工具接口**：两侧工具均为原子操作；抽象层次过高（如一个"解决用户问题"工具）会使评估退化为对单次函数调用的考察，规划与推理被工具本身吸收。
- **评分标准**：分层检查项 + 明确的聚合规则（如 `reward_basis`）。
- **执行协议**：终止信号、轮数上限、模拟用户耐心耗尽主动结束（沟通效率过低本身即计为失败）。
- 按任务形态选环境类型：单轮问答用无状态单轮环境；搜索+综合用多轮工具环境；改数据库验状态用有状态环境；跑代码查输出用沙盒环境。并行采样与轨迹缓存是标配；工具失败应返回清晰错误信息而非单一失败标志，让 Agent 能据此调整策略。

The rest: https://github.com/bojieli/ai-agent-book/blob/HEAD/skills/agent-evaluation/SKILL.md