agent-evaluation

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

# 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 能据此调整策略。

### 3. 验证方式谱系与自动化评估
- 横轴是**可机械验证程度**：确定性断言 → 检查项清单 → Rubric + LLM-as-a-Judge → 配对比较。向右移动不意味着放弃左侧。
- 确定性验证只能判对错、不给原因；生产系统最需要的恰恰是"错在哪、下一步改什么"。开放式任务（报告、投诉、创意）无唯一终态、人工评估不可规模化，才上 LLM 评判。
- **Rubric 四准则**：基于专家指导（捕捉核心事实与推理步骤，而非语言流畅度）；全面覆盖（事实、逻辑、完整性、安全性，且明确 Pitfall）；按重要性加权（必要/重要/可选/陷阱，支持一票否决，如幻觉出现总分归零）；评价标准自包含（禁"展示深刻理解"，改为"引用了至少两个权威理论并准确解释"）。
- 每个维度给客观可验证的评分档次、具体示例与边界案例；显式防范奖励作弊（幻觉、讨好用户、关键词堆砌、回避棘手问题）。
- **长度偏差**防范：Rubric 显式惩罚冗长、规定同类任务长度上限；配对比较前把候选长度控制到相近；定期审计评分与长度的相关性——高分几乎总伴随长回答即已被带偏。
- **同源模型问题**：Agent 与评判模型同家族时，Agent 会学会利用评判模型的偏好与盲点（古德哈特定律：度量成为优化目标后就不再是好度量）。换不同家族模型评判，并让 Rubric 随分歧持续迭代。

### 4. 失败归因：把 0 分变成可修复的问题
- 归因对象是轨迹中**首个**导致任务偏离的错误；后续错误多是连锁反应，不能把最后一条报错当根因。
- 问题案例三来源：用户明确纠正、用户点踩/负面反馈、事后状态检查/规则验证器/LLM 评审发现 Agent 做了不该做的事。
- **静默失败**（无任何工具报错、Agent 自行宣布完成）的两把定位工具：事实锚点比对（把 Agent 陈述与工具返回值逐步对齐，取首次背离）；轨迹前缀二分（截到第 k 步交人接手，能救回说明错误在 k 之后）。不能用搜报错关键字代替。
- 归因记录结构化（JSON/YAML）：含任务名、首错步号、错误类别、责任方、原文证据、置信度，区分主因与后果（三次重试是后果，不是三个根因）；多类别并存时按"最早且能解释后续失败"选主因。
- **规则先筛、LLM 再定位**比全量喂 LLM 更便宜也更准：完成声明与实际执行命令的交叉核对、diff 是否触及测试断言与 skip 标记、diff 是否改公开 API/schema 而无迁移，这三类可先用规则筛出嫌疑轨迹。
- 警惕"做对了但说错了"：工具调用和环境状态全对，告知用户的信息却错。只检查终态的评估会整体掩盖它（τ²-bench 基线中约三分之一失败属此类）。根因归属要判到层：观察通道缺失不是"模型不会 OCR"。
- 保存归因记录时，连同任务目标、环境状态、Agent 版本、工具集版本和完整轨迹一起存，供回归测试使用。

### 5. 两层回归任务
- **端到端回归**：从初始状态跑到终态，验最终状态、必要输出、安全条件。最接近生产结果，但难以定位失败步骤。
- **轨迹前缀回归**：冻结首错之前的上下文、对话、工具返回与环境状态，只要求下一步或下几步可观察动作。成本低、能隔离单个策略问题；对高可靠生产 Agent，其重要性往往超过端到端口径。
- 前缀回归答案定义为**可接受动作集合**（"先读仓库规则""先询问用户""拒绝危险操作"）+ 禁止动作，而不是唯一标准答案。
- 按错误类别生成回归任务：流程缺失 → 带计划文档与测试验收条件的端到端任务；工具调用错误 → 截断出错前缀编辑成边界任务；信息反馈类 → 对答复内容本身设断言，而非只查环境状态。

### 6. 评估驱动的模型选型
- 延迟分两阶段：Prefill 决定首字延迟（TTFT = 排队 + 预填充），Decode 决定出字速度与思考时长（50 tokens/s 生成 2000 思考 token 要 40 秒）。看 p95 尾部延迟而非均值。
- 在自己工作负载上实测各模型的思考 token 用量与对应收益，不凭公开榜单推断。
- 成本算**每个任务的平均成本**与成本-性能比：便宜但成功率低的模型因频繁重试可能更贵；输入/输出/缓存 token 分开计价。
- 指标按场景取：日常 Pass@1，关键操作 Pass^k，探索性任务 Pass@k / Best@k。
- **预算—能力曲线**：除成功率，报告性能随墙钟时间、token、工具调用次数或算力预算变化的曲线；短预算领先不能外推长时运行能力（RE-Bench：2 小时预算最佳 Agent 约为人类专家 4 倍，8 小时人类反超）。
- **行为策略也是选型维度**：同一中性 Harness 下测"行动阈值"（首次修改前的工具调用数与阅读文件数）。换模型行为改变、同模型跨 Harness 保持倾向 → 支持模型效应，反之支持 Harness 效应；工具步数、并行调用、模型延迟必须分开看。工具步数不是质量分。
- 异构模型组合（轻量模型管简单、强模型管复杂）必须用评估验证整体效益超过所增复杂度，并检查特定场景是否回退。
- 成本优化（KV Cache 稳定前缀、上下文压缩、分层选模型）每项独立开关，且**合用时在完整任务中一起实测**——各自节省比例不能相加（28.3% 与 17.5% 合用只有 30%）。
- 建实时成本监控：按任务类型/模型/用户维度追踪 token 与费用，设单任务成本上限，Agent 陷入循环时自动终止。

### 7. 统计显著性
- 标准误 SE(p) ≈ √(p(1-p)/n)：100 个用例、成功率 70% 时 95% 置信区间约 ±9 个百分点，"新模型 73% 对旧模型 70%"不足以支持切换。
- 同一批任务比较两个配置用**配对分析**：逐题记录谁胜出，McNemar 检验或配对 bootstrap，不要相减两个独立成功率。
- 每个配置跑 3–5 个随机种子，报告均值与波动范围；单次运行只能用来筛选方向。
- 预期收益只有 2–3 个百分点而评估集只有几十题：先扩大样本，标准误按 1/√n 缩小。
- 并行验证多个假设时考虑**多重比较**：收紧显著性阈值，或对正向结果做独立复跑。

### 8. 可观测性
- 数据基础是 **trace/span 树**：一次任务执行一条 trace，每个 LLM 调用、工具调用、检索是一个 span（记录输入输出、起止时间、token 消耗、错误），父子关系构成执行树。
- 采用标准协议（OpenTelemetry + OpenInference 等语义约定）保持采集与分析解耦，避免被单一平台锁定；采集异步批量进行，不拖累响应延迟。
- 追踪的四大价值：问题诊断（回放而非猜测）、持续优化（定位低成功率工具与空结果检索）、成本管理（识别异常高成本案例）、后训练数据基础。
- 最有价值的去向是**回流**：生产轨迹筛失败与可疑案例 → 脱敏（去隐私、密钥）→ 沉淀为评估集新用例与回归测试。评估集是随产品演化的活资产，不是一次性静态集合。

### 9. 内部评估基础设施（生产级）
- **消融**：每个主要特性可独立关闭，定期（如每次大版本发布前）跑消融，发现"特性债务"——曾经有效但随模型进化已不再必要的特性。消融开关要在启动路径极早期注入，事后加装不了。
- **AB 测试**：多臂而非二元（揭示剂量-效应关系，找到最优点）；**区分机制指标与目标指标**（缩短计划文件长度是机制，降低会话级成本才是目标，别把机制当目标，计划过短可能引发更多编辑-检查循环反而更贵）；设护栏指标（满意度、操作次数、错误率不能变差）；记录基线统计（样本量、百分位数、相关性），否则无法判断显著性。
- **双层特性开关**：编译时开关（代码物理移除，本身即干净的消融机制）+ 运行时开关（服务端下发、本地缓存、宁可稍旧也不能阻塞启动；每个特性曝光事件每会话最多记一次）。特性开关是一等架构组件，服务实验、渐进发布与紧急熔断。
- **提示词敏感性**：系统提示要能确定性渲染（相同配置输入永远产出相同文本）；建立版本化快照；每次提示词变更在评估集上跑回归，像代码过 CI 一样。
- **隐私感知分析**：分析接口只接受特殊类型包装的值，类型名即审计线索；隐私约束从第一天设计进去。分析系统无法安全收集数据，评估就无从谈起。

### 10. 从 Benchmark 报告到系统改进的闭环节奏
- 读报告先找失败集中在哪些任务与能力上，再回放轨迹分清问题出在**看、想、做、验**哪一环；别只盯总分（88% 总分很容易埋掉一个集中的失败簇）。
- 每轮只改一个变量，形成假设链：加提示词无效 → 换输入通道有效但太贵 → 精简输入保住成功率且降成本。提示写得再详细也补不回 Agent 没看到的信息；输入也不是越多越好。
- 小范围通过只获得扩大测试的资格：标准环境、全任务 × 多种子，同时查成功率不降、token 不超阈值、延迟不超上限，才能讨论部署。

## 常见陷阱
- 看到分数下降就改 Agent 代码，不先排查评测系统（资源不足、验证器 bug、用例脱节都会伪装成模型退化）。
- 用公开基准分数直接做产品决策——GAIA 上提升两个百分点与退款成功率没有必然关系。
- 把最后一条报错当根因；或把根因归错层（观察通道缺失被记成"模型不会 OCR"，于是去换模型、做 OCR 训练）。
- 只检查环境终态，漏掉"做对了但说错了"。
- Rubric 写"展示深刻理解"这类不可验证的抽象标准；没有一票否决项，被关键词堆砌式奖励作弊刷分。
- 评分从未审计长度相关性，评判已被长度偏差带偏而不自知。
- 同源模型既当运动员又当裁判，Goodhart 之后评分虚高。
- 把多项上下文优化的节省比例直接相加；或凭单次运行的结果做选型决策。
- 配对比较不交换候选顺序，位置偏差让先出现者系统性占优。
- 子集小样本通过后直接当整体水平汇报，结论超出证据规模。

## 配套代码
- `chapter7/tau2-bench-eval/` — τ²-bench telecom 五任务双控环境评估：环境 reset、轨迹保存、二元奖励与失败任务（错选线路漏做充值）分析
- `chapter7/android-world/` — T3A 运行记录、失败归因笔记，以及 diagnose→hypothesize→experiment→decide→iterate 的五阶段改进闭环
- `chapter7/public-health-reporting-eval/` — 合成数据上的确定性六点评分：工具选择、参数、答案、证据行、无依据声明处罚
- `chapter7/agent-cost-analysis/` — 八轮退款任务全链路成本拆解，KV-cache 友好与上下文压缩的 2×2 A/B 量化
- `chapter7/model-benchmark/` — 多维度模型基准 campaign：吞吐/TTFT/尾延迟、168 小时可用性、限流爬坡、同模型不同供应商对照
- `chapter7/model-action-threshold/` — 固定 Coding Harness 下测量不同模型的行动阈值（首次修改前的工具调用与文件阅读）
- `chapter7/elo-leaderboard/` — 从 Chatbot Arena 真实投票实现 Elo/Bradley-Terry 配对排名与历史快照

## 深度阅读
- `book/chapter7.md`「评估指标：成功的定义」
- `book/chapter7.md`「评估环境」
- `book/chapter7.md`「自动化评估方法」
- `book/chapter7.md`「评估驱动的模型选型」
- `book/chapter7.md`「评估结果的统计显著性」
- `book/chapter7.md`「Agent 的可观测性」
- `book/chapter7.md`「从 Benchmark 报告到系统改进」
- `book/chapter7.md`「从外部评估到内部评估：生产级 Agent 的评估基础设施」

More agent context in bojieli/ai-agent-book

21 other files this repository gives its agents.