Agent 的输出来自多轮模型调用、工具选择、工具结果、上下文压缩和终止判断。最终答案错了，可能是模型不会，也可能是工具没有被调用、搜索结果没进入上下文、压缩时丢了问题，或者运行时间不够。

Agent 评测的对象不能只写成一个模型名，必须包括数据集、grader 和 harness。building_evals、generate_test_cases、tool_evaluation 和 agentic-search benchmark 分别处理数据、评分、工具诊断和运行框架。

先设计能稳定评分的任务

building_evals.ipynb 把评测拆成输入、模型输出、golden answer 和 score。它列出代码、人工和模型三种 grader，并建议只要能用代码判定，就不要先上 model-as-judge。

exact match、数值误差和结构校验的判定规则公开、可重复；模型 grader 会受提示词、模型版本和输出措辞影响。若任务可以要求输出一个数字或固定 JSON，先收紧输出契约，往往比设计复杂 grader 更可靠。

开放任务无法全部改成 exact match。此时 golden answer 不一定是一篇标准答案，也可以是一组判据。示例中的健身计划要求拉类腿部与手臂动作各不少于 50 次，并包含十分钟核心训练；邮件任务要求模型拒绝声称已经发送。grader 只判断这些条件是否满足，不比较文章措辞。

所以评测设计先决定“什么算对”，再决定由谁评分。直接让另一个模型评价“回答好不好”，等于把未定义的问题交给 grader 自行解释。

合成测试扩充的是输入，不是真实分布

generate_test_cases.ipynb 从 prompt template 中提取双花括号包裹的变量名，让模型为每个变量生成完整值。生成器会推测这些值在生产中由谁提供、长度、格式和语气如何；已有示例则用来约束它模仿的分布。

这种方法适合在真实数据不足或不能使用真实数据时快速扩充输入，也能主动生成长文、非正式请求或特殊格式。但它没有自动产生可信的 golden answer。notebook 最后仍建议由人编写标准答案，或先让模型生成再人工修改。

更大的限制是同源偏差。用模型推测生产输入，它通常会生成语义完整、结构规整、意图可辨的案例，而真实流量里常见缺字段、复制残片、错别字、上下文依赖和互相矛盾的要求。给生成器几个示例只能把它拉近已有样本，不能证明覆盖了真实尾部。

合成数据因此适合补洞和做压力测试，不适合单独估计线上准确率。线上失败案例、人工构造的边界案例和合成样本应分开统计，否则大量容易的合成题会稀释少数关键故障。

最终答案通过不代表工具设计正确

tool_evaluation.ipynb 让 Agent 解决八道有标准答案的计算题，同时要求它记录使用了哪些工具、传入什么参数、工具返回什么，并反馈工具名称、描述和错误。报告除了准确率，还统计耗时、调用次数和每个工具的延迟。这比只看答案多了一层，但仍有明显局限。评分代码只是：

score = int(actual_response == expected_response)

只要答案字符串相同就通过。Agent 可以绕过本应使用的工具自行心算，也可以调用错误工具后碰巧得到正确答案；相反，3.610e-19 与 3.61e-19 数值相同，也可能因字符串不同失败。模型自己生成的 <summary> 和 <feedback> 适合调试，不能当作可靠轨迹证据，因为它可能漏报或重新解释实际调用。

工具评测至少要把四件事分开：

1. 是否选择了正确工具；
2. 参数是否正确；
3. 工具是否成功执行；
4. 最终答案是否正确。

还要直接读取真实 tool-use events，而不是要求模型复述自己的过程。否则换了一个描述更差的工具 schema，最终答案可能暂时没变，评测却看不到选择质量已经下降。

这四层也不能一律设为硬约束。若任务只关心答案，Agent 使用另一条等价路径不应失败；若工具调用涉及计费、隐私或副作用，轨迹就是产品要求的一部分。评测必须先说明自己测的是结果，还是规定的执行过程。

长任务的分数属于 model 与 harness 的组合

agentic-search benchmark 是这一组材料里最重要的反例。同一个模型是否能复现公开分数，取决于 PTC、search/fetch 的返回是否进入上下文、thinking effort、总任务预算、compaction 阈值和摘要说明、容器是否跨轮保存、客户端重试次数以及 grader。

其中一个细节足以让整批题失分：compaction 后若摘要没有保留原始问题和 <result> 格式要求，Agent 会忘记自己要回答什么，甚至要求用户重述问题。模型没有变，搜索工具也没有变，分数却因摘要 prompt 改变。

notebook 还区分了两类失败。模型 API 的 429、5xx 可以由 SDK 重试；server tool 的限流可能作为普通 tool-result error 返回，HTTP 请求本身仍是 200。若评测只捕获异常，不检查 transcript，后者会悄悄变成模型能力下降。

因此 benchmark 的可复现对象应写成：

模型版本
+ 工具与调用方式
+ thinking / effort / task budget
+ context management
+ timeout / retry / concurrency
+ 数据集版本
+ grader 版本

只报告“某模型在某数据集上的分数”，遗漏了决定长任务能否跑完的条件。

Grader 自己也需要被校准

agentic-search 示例固定 grader 模型，不随被测模型一起更换。集合答案先让 grader 标记每个 gold item 是否出现，以及回答是否多报内容，再由代码计算 precision、recall 和 F1。BrowseComp 则使用 A/B/C 单标签判定。

固定 grader 保证不同被测模型之间至少使用同一把尺子，但这把尺子仍可能有误差。它可能接受语义相近但事实不同的答案，也可能无法识别别名。上线前需要抽样让人复核 grader 的通过与拒绝，尤其关注假阳性；若 grader 经常放过坏答案，提高被测模型分数只是在优化错误目标。

同样，评测 prompt、解析器和 grader 模型一旦变化，历史分数就不再完全可比。它们应像生产 prompt 一样版本化，而不是作为 notebook 中一段随时修改的辅助代码。

评测应定位失败发生在哪一层

一套有用的 Agent 评测不能只产出总分。至少要保留以下层次：

• 数据层：真实、边界与合成样本分别表现如何；
• 结果层：答案、引用和结构是否正确；
• 轨迹层：工具选择、参数、错误和重试是否符合要求；
• 运行层：token、延迟、工具次数、超时、compaction 和限流；
• 评分层：grader 与人工判断是否一致。

总分用于比较版本，分层记录用于修系统。只有最终准确率下降时，无法判断应该改 prompt、工具描述、上下文策略还是重试配置。Agent 评测的价值不只是宣布“这版更好”，而是把失败定位到一条可以修改的数据流上。