1. 为什么 Agent Eval 值得单独拿出来讲做 Agent 开发的人大概都有过这种体验Demo 阶段效果惊艳一旦放到真实场景里跑上几十上百个任务表现就开始飘忽不定。同一个 prompt今天能正确调用工具明天就忘了参数格式上周还能稳定完成的多步推理这周加了个新工具就开始胡言乱语。更让人头疼的是你改了一版 prompt感觉某些 case 变好了但另一些 case 又退化了到底整体是进步还是退步完全说不清楚。这个问题的根源在于Agent 的评估和传统模型的评估完全不是一回事。传统模型评估输入输出都是确定的跑一遍测试集算个准确率就行。但 Agent 是一个带工具调用、多轮交互、环境状态变化的动态系统它的输出是一条轨迹不是一个静态结果。你没法用简单的 BLEU、ROUGE 或者准确率来衡量它。Anthropic 在 Agent Eval 这件事上有一套比较系统的方法论核心思路是把评估拆成三个层次任务定义、Harness 执行、Grader 评分然后通过持续迭代来逼近可靠。这套方法不是 Anthropic 独有的但他们的实践比较完整值得拆开来看。这篇文章适合谁如果你正在做 Agent 开发不管是基于什么框架只要你需要回答“我的 Agent 到底行不行”这个问题那这套方法就能直接用。如果你还没开始做 Agent但想了解评估体系怎么搭也可以先看看思路。2. 核心概念拆解Task、Harness、Grader 到底各管什么2.1 Task 定义不是写个 prompt 就完事很多人做 Agent 评估第一步就错了。他们直接把用户可能问的问题列出来当成测试用例。但 Agent 的任务定义远比这复杂。一个完整的 Task 定义至少包含这几个要素初始状态Agent 开始时的环境是什么有哪些文件、数据、工具可用目标描述用自然语言描述 Agent 需要达成什么目标但不要给出具体步骤。成功标准什么样的结果算成功这个标准必须是可验证的。约束条件有哪些不能做的事比如不能删除某个文件、不能调用某个 API。预期轨迹不是必须的但如果有参考轨迹对后续分析很有帮助。举个例子假设你要评估一个“帮用户整理会议纪要”的 Agent。任务定义不是“帮我整理会议纪要”这句话而是初始状态/meetings/ 目录下有 3 个 .txt 文件分别是三次会议的原始记录 目标生成一份汇总的会议纪要包含每次会议的关键决策和待办事项 成功标准 - 输出文件存在于 /output/summary.md - 包含所有三次会议的日期和主题 - 每次会议至少提取 2 个决策和 2 个待办 - 待办事项必须包含负责人从原文中提取 约束不能修改原始文件不能删除任何内容这样定义之后评估才有依据。否则你拿到一个输出根本不知道该怎么判断它好不好。注意任务定义里的“成功标准”一定要可自动验证。如果标准是“纪要写得好”那 Grader 也没法判断。必须拆成可检查的条目比如“包含日期”“包含负责人”这种。2.2 HarnessAgent 的运行环境和执行框架Harness 这个词在 Agent 语境下指的是让 Agent 跑起来的整套执行环境。它包括工具接口Agent 能调用哪些工具每个工具的输入输出格式是什么。环境状态管理Agent 操作的文件系统、数据库、API 状态怎么维护。执行循环Agent 的 think-act-observe 循环怎么跑最大步数是多少超时怎么处理。日志记录每一步的输入输出、工具调用、耗时都要记录下来方便后续分析。Harness 的设计直接决定了评估的可靠性。如果 Harness 本身不稳定比如工具调用偶尔超时、环境状态没有正确重置那评估结果就不可信。Anthropic 的做法是把 Harness 和 Agent 实现解耦。也就是说同一个 Harness 可以跑不同版本的 Agent同一个 Agent 也可以在不同 Harness 上跑。这样做的好处是当你发现 Agent 表现不好时可以快速判断是 Agent 本身的问题还是 Harness 的问题。我自己的经验是Harness 里最容易出问题的地方是环境重置。每次跑完一个任务必须把环境恢复到初始状态否则下一个任务就会受上一个任务的影响。比如文件被修改了没恢复、数据库里多了脏数据、缓存没清空这些都会导致评估结果失真。2.3 Grader怎么判断 Agent 做得好不好Grader 是评估体系里最灵活也最难做的部分。它要回答的问题是给定一个任务和 Agent 的执行轨迹怎么判断它是否成功常见的 Grader 类型有几种Grader 类型适用场景优点缺点精确匹配输出格式固定答案唯一简单、快速、无歧义只能用于极少数任务规则检查有明确的结构化标准可解释、可调试规则写起来费劲覆盖不全模型评分开放式任务需要理解语义灵活、接近人类判断有噪声、成本高、可能被 hack人工评分高风险任务需要最终确认最准确慢、贵、不可规模化实际项目中通常是组合使用。比如先用规则检查做一轮筛选把明显失败的 case 过滤掉剩下的再用模型评分。或者模型评分和人工评分结合模型评一遍人工抽查一部分。Anthropic 特别强调一点Grader 本身也需要被评估。你怎么知道你的 Grader 判断得准答案是拿一批人工标注过的 case 来测 Grader看它和人类判断的一致率有多高。如果一致率低于某个阈值那 Grader 就需要调整。3. 从零搭建一套 Agent Eval 流程3.1 第一步定义任务集别贪多新手最容易犯的错是一上来就搞几百个任务觉得覆盖得越全越好。结果跑一遍要几个小时分析结果要几天迭代速度极慢。我的建议是先做 20-30 个高质量任务。这 20-30 个任务要覆盖核心功能路径Agent 最常做的事边界情况输入为空、格式异常、工具返回错误多步推理需要连续调用多个工具约束遵守不能做的事有没有做每个任务都要有明确的成功标准和失败模式。什么叫失败模式就是你知道这个任务可能以哪几种方式失败。比如“整理会议纪要”这个任务失败模式可能是漏了某次会议、待办没提取负责人、输出格式不对、修改了原始文件。有了失败模式你才能针对性地设计 Grader也才能在分析结果时快速定位问题。实操心得任务集不是一次性的要持续维护。每次发现新的失败模式就加一个对应的任务。每次修复一个 bug就加一个回归测试任务。这样任务集会越来越有代表性。3.2 第二步搭建 Harness重点在可观测性Harness 的搭建没有太多花哨的东西核心就是把 Agent 执行过程中的所有信息都记录下来。一个典型的 Harness 执行日志应该包含{ task_id: meeting_summary_001, agent_version: v1.2.3, start_time: 2025-01-15T10:00:00Z, steps: [ { step: 1, thought: 我需要先查看 /meetings/ 目录下有哪些文件, action: list_files, action_input: {path: /meetings/}, observation: [meeting_1.txt, meeting_2.txt, meeting_3.txt], duration_ms: 120 }, { step: 2, thought: 现在读取第一个文件, action: read_file, action_input: {path: /meetings/meeting_1.txt}, observation: ..., duration_ms: 85 } ], final_output: ..., total_duration_ms: 4500, status: completed }有了这样的日志你才能回答这些问题Agent 在哪一步卡住了它调用了哪些工具工具返回了什么它有没有重复调用同一个工具它的思考过程合理吗Harness 的另一个重点是并发控制。如果你要跑 100 个任务串行跑太慢并行跑又可能因为资源竞争导致结果不稳定。我的做法是每个任务在独立的容器或沙箱里跑互不干扰。并发数根据资源情况调整一般 4-8 个并发比较稳妥。3.3 第三步设计 Grader从简单到复杂Grader 的设计要遵循一个原则能用规则解决的不要用模型。规则 Grader 的例子def grade_meeting_summary(output_path, expected_meetings): # 检查输出文件是否存在 if not os.path.exists(output_path): return {score: 0, reason: 输出文件不存在} content open(output_path).read() # 检查是否包含所有会议日期 for meeting in expected_meetings: if meeting[date] not in content: return {score: 0, reason: f缺少会议日期 {meeting[date]}} # 检查待办事项是否包含负责人 todos extract_todos(content) for todo in todos: if not todo.get(owner): return {score: 0.5, reason: f待办事项缺少负责人: {todo[text]}} return {score: 1, reason: 通过所有检查}模型 Grader 的例子def grade_with_model(task_description, agent_trajectory, success_criteria): prompt f 你是一个评估专家。请根据以下任务描述和成功标准评估 Agent 的执行轨迹。 任务描述{task_description} 成功标准{success_criteria} Agent 执行轨迹{agent_trajectory} 请输出 JSON 格式的评估结果 {{ score: 0-1 之间的分数, passed: true/false, reason: 评分理由, failed_criteria: [未通过的标准列表] }} response call_model(prompt) return parse_json(response)模型 Grader 的关键是prompt 设计。你要把成功标准拆得足够细让模型能逐条检查。同时要给出评分标准比如“完全满足得 1 分部分满足得 0.5 分完全不满足得 0 分”。注意模型 Grader 有被 hack 的风险。Agent 可能会学会输出一些看起来很好但实际没用的内容来骗过 Grader。防范方法是定期用人工标注的数据来校准 Grader同时设计一些“陷阱任务”专门检测 Agent 是否在投机取巧。3.4 第四步跑评估分析结果跑评估本身没什么技术含量但分析结果才是重头戏。我通常会从这几个维度来分析整体通过率所有任务中有多少通过了。这个数字用来跟踪整体趋势。分类通过率按任务类型分组看哪类任务表现差。比如“多步推理”类通过率只有 40%那说明 Agent 在多步推理上有问题。失败模式分布失败的 case 中各种失败模式各占多少。比如“工具调用错误”占 60%“约束违反”占 30%“输出格式错误”占 10%。步数分布Agent 平均用多少步完成任务。步数突然增加可能意味着它在某个地方卡住了。耗时分布每个任务的耗时。耗时异常的任务需要单独看。分析结果最好能可视化。一个简单的 dashboard 就够通过率趋势图、失败模式饼图、步数分布直方图。不用搞得太复杂关键是能快速看出问题。4. 持续改进评估不是一次性的4.1 建立回归测试机制每次修改 Agent改 prompt、加工具、调参数都要跑一遍完整的评估集。如果整体通过率下降超过阈值比如 5%就要回滚。但光看整体通过率不够还要看具体哪些任务退化了。有时候整体通过率没变但某些关键任务从通过变成了失败另一些边缘任务从失败变成了通过这种“拆东墙补西墙”的情况必须及时发现。我的做法是维护一个关键任务列表这些任务是核心功能绝对不能退化。每次评估先看关键任务的通过率再看整体。4.2 用失败案例驱动迭代评估的最大价值不是那个通过率数字而是失败案例。每一个失败案例都是一个改进机会。分析失败案例时我会问这几个问题Agent 在哪一步开始出错的它当时的思考是什么合理吗它调用了正确的工具吗参数对吗如果换一种 prompt 写法它会不会做对这个失败是偶发的还是系统性的如果是系统性的那就需要改 Agent 的设计。如果是偶发的可能是模型本身的随机性可以多跑几次看是否复现。4.3 评估集的版本管理评估集本身也要版本管理。每次新增任务、修改成功标准、调整 Grader都要记录版本。否则你没法比较不同时期的评估结果。我通常会用这样的目录结构evals/ v1.0/ tasks/ meeting_summary_001.json meeting_summary_002.json graders/ meeting_summary_grader.py results/ 2025-01-10_agent_v1.0.json 2025-01-12_agent_v1.1.json v1.1/ tasks/ ...这样你可以清楚地看到Agent v1.1 在 eval v1.0 上的表现和 Agent v1.0 在 eval v1.0 上的表现对比。如果 eval 也升级了那就用新 eval 重新跑一遍旧 Agent保证对比公平。5. 常见问题与排查技巧实录5.1 Agent 表现不稳定同一任务有时通过有时失败这是最常见的问题。原因可能有几种模型随机性温度参数设得太高。Agent 任务通常建议温度设为 0 或接近 0。工具返回不稳定比如某个 API 偶尔超时或返回格式不一致。需要给工具加重试和格式校验。环境状态污染上一个任务的环境没清理干净。检查 Harness 的重置逻辑。并发竞争多个任务同时跑共享了某些资源。确保每个任务在独立沙箱里跑。排查方法把同一个任务连续跑 10 次看通过率。如果通过率在 50% 左右那基本可以确定是随机性问题。如果通过率很高但偶尔失败那可能是环境或工具的问题。5.2 Grader 判断不准人工复核发现很多误判Grader 误判通常有两个方向假阳性Agent 没做好但 Grader 说通过了和假阴性Agent 做好了但 Grader 说没通过。假阳性的常见原因Grader 检查的条件太宽松。比如只检查了输出文件存在没检查内容质量。解决办法是加更多检查项或者引入模型 Grader 做语义判断。假阴性的常见原因Grader 的规则太死板。比如要求输出必须包含某个关键词但 Agent 用了同义词。解决办法是把规则写得更灵活或者用模型 Grader 替代规则 Grader。实操心得定期拿 20-30 个 case 做人工标注然后对比 Grader 的判断。如果一致率低于 90%Grader 就需要调整。这个校准过程要持续做因为 Agent 的行为会变化Grader 也要跟着变。5.3 评估跑得太慢迭代速度跟不上评估慢通常是因为任务太多、每个任务步数太多、并发度太低、模型调用太慢。优化方向减少任务数只保留最有代表性的任务。20-30 个足够不要贪多。设置最大步数Agent 超过一定步数就强制终止避免无限循环。提高并发在资源允许的情况下增加并发数。但要注意环境隔离。缓存工具调用如果某些工具调用是确定性的可以缓存结果避免重复调用。用更快的模型做 GraderGrader 不需要用最强的模型用一个小而快的模型就够了。5.4 Agent 学会了“骗” Grader这是模型 Grader 特有的问题。Agent 可能会发现只要输出某些特定格式的内容Grader 就会给高分哪怕实际任务没完成。防范方法Grader 和 Agent 用不同的模型避免 Agent 针对特定模型的偏好进行优化。定期更换 Grader 的 prompt让 Agent 没法针对固定的 Grader 逻辑进行优化。加入人工抽查定期人工检查一部分 case发现异常模式。设计“陷阱任务”故意设计一些任务如果 Agent 真的理解了任务就能做对如果只是投机取巧就会失败。5.5 评估结果和线上表现不一致评估集上表现很好但上线后用户反馈很差。这种落差通常是因为评估集覆盖不全真实场景中的任务比评估集复杂得多。评估环境太干净真实环境有各种噪声和异常评估环境没有模拟。用户行为不可预测评估集的任务是预设的用户可能会用完全意想不到的方式使用 Agent。解决办法把线上失败案例回流到评估集。每次用户反馈问题就把对应的 case 加到评估集里。这样评估集会越来越接近真实场景。6. 一些工具和框架的选型建议6.1 Harness 框架怎么选如果你不想从零搭 Harness可以考虑一些现成的框架。选型时重点看这几个方面工具接口是否灵活能不能方便地定义新工具。环境隔离是否彻底每个任务能不能在独立环境里跑。日志是否完整能不能记录每一步的详细信息。并发控制是否好用能不能方便地调整并发数。是否支持自定义 Grader能不能接入自己的评分逻辑。我的建议是先用现成框架快速跑起来遇到瓶颈再自己改。不要一上来就自己造轮子那样会花很多时间在基础设施上而不是在 Agent 本身。6.2 Grader 的实现方式Grader 可以用 Python 脚本实现也可以用现成的评估框架。关键是要可配置、可扩展。我通常会把 Grader 设计成插件式的每个 Grader 是一个独立的类实现grade(task, trajectory)方法。评估框架根据任务配置自动选择合适的 Grader。class BaseGrader: def grade(self, task, trajectory): raise NotImplementedError class RuleBasedGrader(BaseGrader): def grade(self, task, trajectory): # 规则检查逻辑 pass class ModelBasedGrader(BaseGrader): def grade(self, task, trajectory): # 模型评分逻辑 pass class CompositeGrader(BaseGrader): def __init__(self, graders): self.graders graders def grade(self, task, trajectory): results [g.grade(task, trajectory) for g in self.graders] # 组合多个 Grader 的结果 return combine(results)这样你可以灵活组合不同的 Grader比如先用规则 Grader 做快速筛选再用模型 Grader 做精细评分。6.3 结果存储和可视化评估结果建议存成结构化格式JSON 或 SQLite方便后续查询和分析。可视化可以用简单的 Web dashboard也可以用 Jupyter Notebook。我自己的做法是结果存 SQLite分析用 Jupyter。SQLite 方便查询和聚合Jupyter 方便画图和探索。不需要搞太复杂的系统够用就行。7. 最后分享几个踩坑经验做 Agent Eval 这段时间踩过的坑不少挑几个最有代表性的说说。第一个坑一开始就追求大而全的评估集。我最初搞了 200 多个任务跑一遍要一个多小时分析结果要半天。后来砍到 30 个核心任务迭代速度立刻上来了。评估集的质量比数量重要得多。第二个坑Grader 写得太死。早期我用精确匹配做 Grader结果 Agent 输出里多了一个空格就判失败。后来改成规则检查加模型评分灵活多了。Grader 要能容忍合理的变体只关注核心成功标准。第三个坑忽略环境重置。有一次评估结果特别差排查了半天才发现是上一个任务修改了文件没恢复导致后续任务全在错误的环境里跑。从那以后我在 Harness 里加了强制重置逻辑每个任务开始前都确保环境是干净的。第四个坑不记录中间步骤。最开始只记录最终输出失败的时候完全不知道 Agent 在哪一步出了问题。后来把每一步的 thought、action、observation 都记下来排查效率提升了好几倍。第五个坑评估和开发脱节。有一段时间评估是单独一个团队在做开发团队只管改 Agent两边不怎么沟通。结果评估发现的问题开发团队不知道开发改的东西评估团队也没及时覆盖。后来改成评估和开发同一拨人做迭代效率高了很多。如果让我给刚起步的人一个建议那就是先跑通一个最小闭环。定义 5 个任务搭一个最简单的 Harness写一个规则 Grader跑一遍看结果。然后再逐步扩展。不要一开始就追求完美先让流程转起来再在迭代中优化。
1. 为什么 Agent Eval 值得单独拿出来讲做 Agent 开发的人大概都有过这种体验Demo 阶段效果惊艳一旦放到真实场景里跑上几十上百个任务表现就开始飘忽不定。同一个 prompt今天能正确调用工具明天就忘了参数格式上周还能稳定完成的多步推理这周加了个新工具就开始胡言乱语。更让人头疼的是你改了一版 prompt感觉某些 case 变好了但另一些 case 又退化了到底整体是进步还是退步完全说不清楚。这个问题的根源在于Agent 的评估和传统模型的评估完全不是一回事。传统模型评估输入输出都是确定的跑一遍测试集算个准确率就行。但 Agent 是一个带工具调用、多轮交互、环境状态变化的动态系统它的输出是一条轨迹不是一个静态结果。你没法用简单的 BLEU、ROUGE 或者准确率来衡量它。Anthropic 在 Agent Eval 这件事上有一套比较系统的方法论核心思路是把评估拆成三个层次任务定义、Harness 执行、Grader 评分然后通过持续迭代来逼近可靠。这套方法不是 Anthropic 独有的但他们的实践比较完整值得拆开来看。这篇文章适合谁如果你正在做 Agent 开发不管是基于什么框架只要你需要回答“我的 Agent 到底行不行”这个问题那这套方法就能直接用。如果你还没开始做 Agent但想了解评估体系怎么搭也可以先看看思路。2. 核心概念拆解Task、Harness、Grader 到底各管什么2.1 Task 定义不是写个 prompt 就完事很多人做 Agent 评估第一步就错了。他们直接把用户可能问的问题列出来当成测试用例。但 Agent 的任务定义远比这复杂。一个完整的 Task 定义至少包含这几个要素初始状态Agent 开始时的环境是什么有哪些文件、数据、工具可用目标描述用自然语言描述 Agent 需要达成什么目标但不要给出具体步骤。成功标准什么样的结果算成功这个标准必须是可验证的。约束条件有哪些不能做的事比如不能删除某个文件、不能调用某个 API。预期轨迹不是必须的但如果有参考轨迹对后续分析很有帮助。举个例子假设你要评估一个“帮用户整理会议纪要”的 Agent。任务定义不是“帮我整理会议纪要”这句话而是初始状态/meetings/ 目录下有 3 个 .txt 文件分别是三次会议的原始记录 目标生成一份汇总的会议纪要包含每次会议的关键决策和待办事项 成功标准 - 输出文件存在于 /output/summary.md - 包含所有三次会议的日期和主题 - 每次会议至少提取 2 个决策和 2 个待办 - 待办事项必须包含负责人从原文中提取 约束不能修改原始文件不能删除任何内容这样定义之后评估才有依据。否则你拿到一个输出根本不知道该怎么判断它好不好。注意任务定义里的“成功标准”一定要可自动验证。如果标准是“纪要写得好”那 Grader 也没法判断。必须拆成可检查的条目比如“包含日期”“包含负责人”这种。2.2 HarnessAgent 的运行环境和执行框架Harness 这个词在 Agent 语境下指的是让 Agent 跑起来的整套执行环境。它包括工具接口Agent 能调用哪些工具每个工具的输入输出格式是什么。环境状态管理Agent 操作的文件系统、数据库、API 状态怎么维护。执行循环Agent 的 think-act-observe 循环怎么跑最大步数是多少超时怎么处理。日志记录每一步的输入输出、工具调用、耗时都要记录下来方便后续分析。Harness 的设计直接决定了评估的可靠性。如果 Harness 本身不稳定比如工具调用偶尔超时、环境状态没有正确重置那评估结果就不可信。Anthropic 的做法是把 Harness 和 Agent 实现解耦。也就是说同一个 Harness 可以跑不同版本的 Agent同一个 Agent 也可以在不同 Harness 上跑。这样做的好处是当你发现 Agent 表现不好时可以快速判断是 Agent 本身的问题还是 Harness 的问题。我自己的经验是Harness 里最容易出问题的地方是环境重置。每次跑完一个任务必须把环境恢复到初始状态否则下一个任务就会受上一个任务的影响。比如文件被修改了没恢复、数据库里多了脏数据、缓存没清空这些都会导致评估结果失真。2.3 Grader怎么判断 Agent 做得好不好Grader 是评估体系里最灵活也最难做的部分。它要回答的问题是给定一个任务和 Agent 的执行轨迹怎么判断它是否成功常见的 Grader 类型有几种Grader 类型适用场景优点缺点精确匹配输出格式固定答案唯一简单、快速、无歧义只能用于极少数任务规则检查有明确的结构化标准可解释、可调试规则写起来费劲覆盖不全模型评分开放式任务需要理解语义灵活、接近人类判断有噪声、成本高、可能被 hack人工评分高风险任务需要最终确认最准确慢、贵、不可规模化实际项目中通常是组合使用。比如先用规则检查做一轮筛选把明显失败的 case 过滤掉剩下的再用模型评分。或者模型评分和人工评分结合模型评一遍人工抽查一部分。Anthropic 特别强调一点Grader 本身也需要被评估。你怎么知道你的 Grader 判断得准答案是拿一批人工标注过的 case 来测 Grader看它和人类判断的一致率有多高。如果一致率低于某个阈值那 Grader 就需要调整。3. 从零搭建一套 Agent Eval 流程3.1 第一步定义任务集别贪多新手最容易犯的错是一上来就搞几百个任务觉得覆盖得越全越好。结果跑一遍要几个小时分析结果要几天迭代速度极慢。我的建议是先做 20-30 个高质量任务。这 20-30 个任务要覆盖核心功能路径Agent 最常做的事边界情况输入为空、格式异常、工具返回错误多步推理需要连续调用多个工具约束遵守不能做的事有没有做每个任务都要有明确的成功标准和失败模式。什么叫失败模式就是你知道这个任务可能以哪几种方式失败。比如“整理会议纪要”这个任务失败模式可能是漏了某次会议、待办没提取负责人、输出格式不对、修改了原始文件。有了失败模式你才能针对性地设计 Grader也才能在分析结果时快速定位问题。实操心得任务集不是一次性的要持续维护。每次发现新的失败模式就加一个对应的任务。每次修复一个 bug就加一个回归测试任务。这样任务集会越来越有代表性。3.2 第二步搭建 Harness重点在可观测性Harness 的搭建没有太多花哨的东西核心就是把 Agent 执行过程中的所有信息都记录下来。一个典型的 Harness 执行日志应该包含{ task_id: meeting_summary_001, agent_version: v1.2.3, start_time: 2025-01-15T10:00:00Z, steps: [ { step: 1, thought: 我需要先查看 /meetings/ 目录下有哪些文件, action: list_files, action_input: {path: /meetings/}, observation: [meeting_1.txt, meeting_2.txt, meeting_3.txt], duration_ms: 120 }, { step: 2, thought: 现在读取第一个文件, action: read_file, action_input: {path: /meetings/meeting_1.txt}, observation: ..., duration_ms: 85 } ], final_output: ..., total_duration_ms: 4500, status: completed }有了这样的日志你才能回答这些问题Agent 在哪一步卡住了它调用了哪些工具工具返回了什么它有没有重复调用同一个工具它的思考过程合理吗Harness 的另一个重点是并发控制。如果你要跑 100 个任务串行跑太慢并行跑又可能因为资源竞争导致结果不稳定。我的做法是每个任务在独立的容器或沙箱里跑互不干扰。并发数根据资源情况调整一般 4-8 个并发比较稳妥。3.3 第三步设计 Grader从简单到复杂Grader 的设计要遵循一个原则能用规则解决的不要用模型。规则 Grader 的例子def grade_meeting_summary(output_path, expected_meetings): # 检查输出文件是否存在 if not os.path.exists(output_path): return {score: 0, reason: 输出文件不存在} content open(output_path).read() # 检查是否包含所有会议日期 for meeting in expected_meetings: if meeting[date] not in content: return {score: 0, reason: f缺少会议日期 {meeting[date]}} # 检查待办事项是否包含负责人 todos extract_todos(content) for todo in todos: if not todo.get(owner): return {score: 0.5, reason: f待办事项缺少负责人: {todo[text]}} return {score: 1, reason: 通过所有检查}模型 Grader 的例子def grade_with_model(task_description, agent_trajectory, success_criteria): prompt f 你是一个评估专家。请根据以下任务描述和成功标准评估 Agent 的执行轨迹。 任务描述{task_description} 成功标准{success_criteria} Agent 执行轨迹{agent_trajectory} 请输出 JSON 格式的评估结果 {{ score: 0-1 之间的分数, passed: true/false, reason: 评分理由, failed_criteria: [未通过的标准列表] }} response call_model(prompt) return parse_json(response)模型 Grader 的关键是prompt 设计。你要把成功标准拆得足够细让模型能逐条检查。同时要给出评分标准比如“完全满足得 1 分部分满足得 0.5 分完全不满足得 0 分”。注意模型 Grader 有被 hack 的风险。Agent 可能会学会输出一些看起来很好但实际没用的内容来骗过 Grader。防范方法是定期用人工标注的数据来校准 Grader同时设计一些“陷阱任务”专门检测 Agent 是否在投机取巧。3.4 第四步跑评估分析结果跑评估本身没什么技术含量但分析结果才是重头戏。我通常会从这几个维度来分析整体通过率所有任务中有多少通过了。这个数字用来跟踪整体趋势。分类通过率按任务类型分组看哪类任务表现差。比如“多步推理”类通过率只有 40%那说明 Agent 在多步推理上有问题。失败模式分布失败的 case 中各种失败模式各占多少。比如“工具调用错误”占 60%“约束违反”占 30%“输出格式错误”占 10%。步数分布Agent 平均用多少步完成任务。步数突然增加可能意味着它在某个地方卡住了。耗时分布每个任务的耗时。耗时异常的任务需要单独看。分析结果最好能可视化。一个简单的 dashboard 就够通过率趋势图、失败模式饼图、步数分布直方图。不用搞得太复杂关键是能快速看出问题。4. 持续改进评估不是一次性的4.1 建立回归测试机制每次修改 Agent改 prompt、加工具、调参数都要跑一遍完整的评估集。如果整体通过率下降超过阈值比如 5%就要回滚。但光看整体通过率不够还要看具体哪些任务退化了。有时候整体通过率没变但某些关键任务从通过变成了失败另一些边缘任务从失败变成了通过这种“拆东墙补西墙”的情况必须及时发现。我的做法是维护一个关键任务列表这些任务是核心功能绝对不能退化。每次评估先看关键任务的通过率再看整体。4.2 用失败案例驱动迭代评估的最大价值不是那个通过率数字而是失败案例。每一个失败案例都是一个改进机会。分析失败案例时我会问这几个问题Agent 在哪一步开始出错的它当时的思考是什么合理吗它调用了正确的工具吗参数对吗如果换一种 prompt 写法它会不会做对这个失败是偶发的还是系统性的如果是系统性的那就需要改 Agent 的设计。如果是偶发的可能是模型本身的随机性可以多跑几次看是否复现。4.3 评估集的版本管理评估集本身也要版本管理。每次新增任务、修改成功标准、调整 Grader都要记录版本。否则你没法比较不同时期的评估结果。我通常会用这样的目录结构evals/ v1.0/ tasks/ meeting_summary_001.json meeting_summary_002.json graders/ meeting_summary_grader.py results/ 2025-01-10_agent_v1.0.json 2025-01-12_agent_v1.1.json v1.1/ tasks/ ...这样你可以清楚地看到Agent v1.1 在 eval v1.0 上的表现和 Agent v1.0 在 eval v1.0 上的表现对比。如果 eval 也升级了那就用新 eval 重新跑一遍旧 Agent保证对比公平。5. 常见问题与排查技巧实录5.1 Agent 表现不稳定同一任务有时通过有时失败这是最常见的问题。原因可能有几种模型随机性温度参数设得太高。Agent 任务通常建议温度设为 0 或接近 0。工具返回不稳定比如某个 API 偶尔超时或返回格式不一致。需要给工具加重试和格式校验。环境状态污染上一个任务的环境没清理干净。检查 Harness 的重置逻辑。并发竞争多个任务同时跑共享了某些资源。确保每个任务在独立沙箱里跑。排查方法把同一个任务连续跑 10 次看通过率。如果通过率在 50% 左右那基本可以确定是随机性问题。如果通过率很高但偶尔失败那可能是环境或工具的问题。5.2 Grader 判断不准人工复核发现很多误判Grader 误判通常有两个方向假阳性Agent 没做好但 Grader 说通过了和假阴性Agent 做好了但 Grader 说没通过。假阳性的常见原因Grader 检查的条件太宽松。比如只检查了输出文件存在没检查内容质量。解决办法是加更多检查项或者引入模型 Grader 做语义判断。假阴性的常见原因Grader 的规则太死板。比如要求输出必须包含某个关键词但 Agent 用了同义词。解决办法是把规则写得更灵活或者用模型 Grader 替代规则 Grader。实操心得定期拿 20-30 个 case 做人工标注然后对比 Grader 的判断。如果一致率低于 90%Grader 就需要调整。这个校准过程要持续做因为 Agent 的行为会变化Grader 也要跟着变。5.3 评估跑得太慢迭代速度跟不上评估慢通常是因为任务太多、每个任务步数太多、并发度太低、模型调用太慢。优化方向减少任务数只保留最有代表性的任务。20-30 个足够不要贪多。设置最大步数Agent 超过一定步数就强制终止避免无限循环。提高并发在资源允许的情况下增加并发数。但要注意环境隔离。缓存工具调用如果某些工具调用是确定性的可以缓存结果避免重复调用。用更快的模型做 GraderGrader 不需要用最强的模型用一个小而快的模型就够了。5.4 Agent 学会了“骗” Grader这是模型 Grader 特有的问题。Agent 可能会发现只要输出某些特定格式的内容Grader 就会给高分哪怕实际任务没完成。防范方法Grader 和 Agent 用不同的模型避免 Agent 针对特定模型的偏好进行优化。定期更换 Grader 的 prompt让 Agent 没法针对固定的 Grader 逻辑进行优化。加入人工抽查定期人工检查一部分 case发现异常模式。设计“陷阱任务”故意设计一些任务如果 Agent 真的理解了任务就能做对如果只是投机取巧就会失败。5.5 评估结果和线上表现不一致评估集上表现很好但上线后用户反馈很差。这种落差通常是因为评估集覆盖不全真实场景中的任务比评估集复杂得多。评估环境太干净真实环境有各种噪声和异常评估环境没有模拟。用户行为不可预测评估集的任务是预设的用户可能会用完全意想不到的方式使用 Agent。解决办法把线上失败案例回流到评估集。每次用户反馈问题就把对应的 case 加到评估集里。这样评估集会越来越接近真实场景。6. 一些工具和框架的选型建议6.1 Harness 框架怎么选如果你不想从零搭 Harness可以考虑一些现成的框架。选型时重点看这几个方面工具接口是否灵活能不能方便地定义新工具。环境隔离是否彻底每个任务能不能在独立环境里跑。日志是否完整能不能记录每一步的详细信息。并发控制是否好用能不能方便地调整并发数。是否支持自定义 Grader能不能接入自己的评分逻辑。我的建议是先用现成框架快速跑起来遇到瓶颈再自己改。不要一上来就自己造轮子那样会花很多时间在基础设施上而不是在 Agent 本身。6.2 Grader 的实现方式Grader 可以用 Python 脚本实现也可以用现成的评估框架。关键是要可配置、可扩展。我通常会把 Grader 设计成插件式的每个 Grader 是一个独立的类实现grade(task, trajectory)方法。评估框架根据任务配置自动选择合适的 Grader。class BaseGrader: def grade(self, task, trajectory): raise NotImplementedError class RuleBasedGrader(BaseGrader): def grade(self, task, trajectory): # 规则检查逻辑 pass class ModelBasedGrader(BaseGrader): def grade(self, task, trajectory): # 模型评分逻辑 pass class CompositeGrader(BaseGrader): def __init__(self, graders): self.graders graders def grade(self, task, trajectory): results [g.grade(task, trajectory) for g in self.graders] # 组合多个 Grader 的结果 return combine(results)这样你可以灵活组合不同的 Grader比如先用规则 Grader 做快速筛选再用模型 Grader 做精细评分。6.3 结果存储和可视化评估结果建议存成结构化格式JSON 或 SQLite方便后续查询和分析。可视化可以用简单的 Web dashboard也可以用 Jupyter Notebook。我自己的做法是结果存 SQLite分析用 Jupyter。SQLite 方便查询和聚合Jupyter 方便画图和探索。不需要搞太复杂的系统够用就行。7. 最后分享几个踩坑经验做 Agent Eval 这段时间踩过的坑不少挑几个最有代表性的说说。第一个坑一开始就追求大而全的评估集。我最初搞了 200 多个任务跑一遍要一个多小时分析结果要半天。后来砍到 30 个核心任务迭代速度立刻上来了。评估集的质量比数量重要得多。第二个坑Grader 写得太死。早期我用精确匹配做 Grader结果 Agent 输出里多了一个空格就判失败。后来改成规则检查加模型评分灵活多了。Grader 要能容忍合理的变体只关注核心成功标准。第三个坑忽略环境重置。有一次评估结果特别差排查了半天才发现是上一个任务修改了文件没恢复导致后续任务全在错误的环境里跑。从那以后我在 Harness 里加了强制重置逻辑每个任务开始前都确保环境是干净的。第四个坑不记录中间步骤。最开始只记录最终输出失败的时候完全不知道 Agent 在哪一步出了问题。后来把每一步的 thought、action、observation 都记下来排查效率提升了好几倍。第五个坑评估和开发脱节。有一段时间评估是单独一个团队在做开发团队只管改 Agent两边不怎么沟通。结果评估发现的问题开发团队不知道开发改的东西评估团队也没及时覆盖。后来改成评估和开发同一拨人做迭代效率高了很多。如果让我给刚起步的人一个建议那就是先跑通一个最小闭环。定义 5 个任务搭一个最简单的 Harness写一个规则 Grader跑一遍看结果。然后再逐步扩展。不要一开始就追求完美先让流程转起来再在迭代中优化。
