1. 为什么 Agent 评测这件事值得单独拎出来讲做 Agent 开发的人大概都经历过这样一个阶段Demo 跑通了流程能走完工具调用看起来也没问题于是信心满满地准备上线。结果一放到真实场景里各种幺蛾子全出来了——该调工具的时候不调不该调的时候乱调多轮对话到第三轮就开始胡言乱语任务完成率忽高忽低同一个输入跑两次结果能差出十万八千里。这时候你才意识到一个问题Agent 的评测和传统软件的测试完全不是一回事。传统软件测试有明确的输入输出断言写死就行。但 Agent 是一个概率系统它的输出是自然语言它的行为路径依赖上下文它的正确往往没有唯一答案。你没法用assert result expected这种思路去测它。这就是为什么最近一年Agent 评测体系这个词被反复提起harness、rubric、LLM-judge 这些概念也开始频繁出现在各种技术讨论里。我自己在过去一段时间里从零搭过几套 Agent 评测流程踩过的坑可以说相当丰富。有的评测集设计得太理想化跑出来的分数很好看但和线上真实表现完全对不上有的用 LLM 当裁判结果裁判自己都不稳定同一份回答打分能飘出两三个档位还有的 harness 框架装了半天装不上插件加载失败报一堆错最后发现是版本对不上。这篇内容我想把 Agent 评测体系这件事从头到尾讲清楚。它适合正在做 Agent 开发、准备把 Agent 推向生产环境的工程师也适合刚接触 Agent、想搞清楚怎么判断一个 Agent 好不好的初学者。我会讲清楚评测体系的核心组成、harness 到底是个什么东西、rubric 怎么写才靠谱、LLM-judge 怎么用才不翻车以及整套流程怎么落地。全程都是实操视角能抄作业的地方我尽量给到具体方案。2. Agent 评测体系的整体设计与核心思路拆解2.1 为什么传统测试方法在 Agent 上失效先说清楚问题的本质。传统软件的行为是确定性的给定输入 A必然得到输出 B。测试的核心是覆盖各种输入分支验证输出是否符合预期。但 Agent 的行为链条是这样的接收任务 → 理解意图 → 规划步骤 → 调用工具 → 观察结果 → 调整策略 → 生成回复。这条链上每一环都可能有多种走法而且很多走法都能到终点只是效率和质量不同。举个具体例子。你让 Agent 帮我查一下明天北京的天气如果下雨就提醒我带伞。一个合格的 Agent 可能这样走调用天气工具 → 拿到结果 → 判断是否下雨 → 生成回复。但另一个 Agent 可能先调用了一次天气工具发现返回格式不对又重新调了一次最后也给出了正确答案。从结果看两者都对但从过程看第二个 Agent 多花了一次工具调用这在成本敏感的场景里就是问题。所以 Agent 评测必须同时关注两个维度结果对不对和过程好不好。只看结果你会漏掉效率问题、稳定性问题只看过程你又可能把走了弯路但最终解决的 Agent 误判为差。这个双维度思路是整套评测体系设计的起点。2.2 评测体系的四层结构我把一套完整的 Agent 评测体系拆成四层从下往上分别是层级名称核心职责典型产出L1数据集层提供标准化的测试输入和参考答案评测集、黄金答案、边界用例L2执行层harness驱动 Agent 跑完任务采集全过程数据轨迹日志、工具调用记录、耗时L3评判层rubric judge对结果和过程打分分数、评级、失败原因L4分析层汇总指标定位问题驱动迭代报表、回归对比、badcase 清单这四层里L2 的 harness 和 L3 的 rubric、LLM-judge 是最容易被低估、也最容易出问题的部分。很多人一上来就想着我要写多少条测试用例却忽略了 harness 能不能稳定地把 Agent 跑起来、能不能完整地记录轨迹。结果就是数据集写得再漂亮跑出来的数据也是残缺的根本没法分析。2.3 方案选型的几个关键取舍在动手之前有几个选型问题必须先想清楚因为它们直接决定了后面所有工作的形态。第一个取舍用现成 harness 还是自己写。现成的 harness 框架比如一些开源的 Agent 评测工具好处是开箱即用内置了轨迹采集、并发调度、结果汇总这些基础设施。但坏处是它对你的 Agent 框架有假设如果你的 Agent 是用自研框架搭的接入成本可能比自己写还高。我的经验是如果你的 Agent 是标准框架比如基于主流 Agent 框架搭的优先用现成 harness如果是深度自研自己写一个轻量 harness 反而更快。第二个取舍用 LLM 当裁判还是用规则。规则裁判比如检查输出里是否包含某个关键词、工具调用次数是否超标稳定、便宜、可复现但只能覆盖能形式化的部分。LLM 裁判能处理开放式回答的质量评估但成本高、有波动。合理的做法是混合能用规则判的用规则规则判不了的交给 LLM而且 LLM 裁判的结果要经过校准。第三个取舍评测集规模。很多人觉得评测集越大越好动辄几百上千条。但实际上一个精心设计的 50 条评测集价值可能超过 500 条随手写的。因为评测的目的是定位问题不是刷分。50 条覆盖了核心场景和典型边界你就能快速发现 Agent 的短板在哪。规模大反而会让分析变得困难跑一次要半天迭代速度就下来了。3. 核心细节解析与实操要点3.1 Harness 到底是什么为什么它这么重要Harness 这个词直译是马具挽具在软件测试领域它指的是驱动被测对象运行并采集数据的那套脚手架。放到 Agent 场景里harness 要做的事情包括把评测集里的任务喂给 Agent、等待 Agent 执行完成、记录整个执行过程中的所有事件思考、工具调用、中间结果、最终输出、处理超时和异常、最后把轨迹数据交给评判层。为什么 harness 这么关键因为没有可靠的 harness就没有可信的评测数据。我见过太多团队评测集写得很认真但 harness 是临时拼凑的结果跑出来的数据缺胳膊少腿有的任务超时了没记录、有的工具调用参数没采集到、有的并发跑的时候日志串了。拿着这样的数据去分析得出的结论全是错的。一个合格的 harness 至少要满足这几个要求可复现同一个任务同样的 Agent 配置跑两次的输入完全一致包括随机种子、温度参数这些。可观测Agent 执行过程中的每一步都能被记录下来包括它想了什么如果有思维链、调了什么工具、拿到了什么结果。可隔离每个任务在独立的环境里跑互不干扰。特别是涉及文件操作、数据库写入的任务隔离做不好会互相污染。可并发能同时跑多个任务否则评测集一大跑一轮要等半天。可容错单个任务失败不能拖垮整轮评测超时、异常都要有兜底。3.2 自己写一个轻量 harness 的核心结构如果你的 Agent 是自研的我建议自己写一个轻量 harness。核心结构其实不复杂主要就是三个模块任务调度器、执行器、轨迹采集器。任务调度器负责从评测集里取任务分发给执行器控制并发数收集结果。执行器负责真正调用 Agent跑完一个任务处理超时和异常。轨迹采集器负责在执行过程中把关键事件记录下来。下面是一个简化的 Python 结构展示核心逻辑import asyncio import time from dataclasses import dataclass, field from typing import Any dataclass class Trajectory: task_id: str input: str steps: list field(default_factorylist) final_output: str status: str pending duration: float 0.0 error: str class Harness: def __init__(self, agent, dataset, concurrency4, timeout120): self.agent agent self.dataset dataset self.concurrency concurrency self.timeout timeout async def run_single(self, task): traj Trajectory(task_idtask[id], inputtask[input]) start time.time() try: result await asyncio.wait_for( self.agent.run(task[input], on_steptraj.steps.append), timeoutself.timeout ) traj.final_output result traj.status success except asyncio.TimeoutError: traj.status timeout traj.error fexceeded {self.timeout}s except Exception as e: traj.status error traj.error str(e) traj.duration time.time() - start return traj async def run_all(self): sem asyncio.Semaphore(self.concurrency) async def guarded(task): async with sem: return await self.run_single(task) return await asyncio.gather(*[guarded(t) for t in self.dataset])这段代码的关键点在于on_step回调让 Agent 在执行过程中把每一步推给轨迹采集器这样即使任务超时或报错已经产生的步骤也不会丢。并发用信号量控制避免一次性打满资源。超时用asyncio.wait_for兜底保证单个任务不会无限挂起。注意并发数不是越大越好。如果你的 Agent 会调用外部 API并发太高会触发限流反而拖慢整体速度。一般从 4 开始试观察 API 的错误率和响应时间再调整。3.3 Rubric 怎么写才不沦为摆设Rubric 是评分标准它定义了什么样的回答算好什么样的算差。很多人写 rubric 就是列几条模糊的标准比如回答要准确、完整、有帮助这种 rubric 等于没写因为 LLM 裁判拿到它也没法稳定打分。好的 rubric 有几个特征。第一是可操作每条标准都要能对应到回答里的具体特征。第二是有区分度不同档位之间的差异要清晰不能模棱两可。第三是有优先级哪些是硬性要求不满足直接判失败哪些是加分项要分清楚。我一般用分档式 rubric把每个评估维度分成几个明确的档位。比如评估工具调用正确性这个维度档位描述判定依据优秀工具选择正确参数完整无冗余调用调用序列与预期一致无多余步骤良好工具选择正确参数基本完整有少量冗余结果正确但多调了 1-2 次及格最终结果正确但过程有明显弯路经过多次试错才拿到正确结果不及格结果错误或调用了不该调的工具最终输出与预期不符这种分档式 rubric 的好处是LLM 裁判拿到之后只需要判断这个回答落在哪个档位而不是从零开始打分。判断落档比打分容易得多稳定性也高得多。3.4 LLM-judge 的正确打开方式LLM-judge 就是用大模型来当裁判评估 Agent 的输出质量。它的优势是能处理开放式问题劣势是不稳定。同一个回答你换个时间、换个措辞问裁判分数可能就不一样。要让 LLM-judge 靠谱有几个实操要点。要点一给裁判明确的评分流程。不要让裁判直接给分而是让它先分析、再判断、最后给分。比如先让它列出回答里满足和不满足 rubric 的点再根据这些点判断落在哪个档位。这种先推理后结论的方式比直接要分数稳定得多。要点二用结构化输出。让裁判以 JSON 格式返回结果包含档位、理由、关键证据。这样既方便程序解析也逼着裁判把理由说清楚。JUDGE_PROMPT 你是一个 Agent 输出质量评估专家。请根据以下评分标准评估 Agent 的回答。 评分标准 {rubric} 任务输入{task_input} Agent 回答{agent_output} Agent 执行轨迹{trajectory} 请按以下步骤评估 1. 逐条对照评分标准列出 Agent 回答满足和不满足的点 2. 根据这些点判断回答落在哪个档位 3. 给出你的判断理由 以 JSON 格式返回 {{ analysis: 逐条对照的分析, level: 优秀/良好/及格/不及格, reason: 判断理由, evidence: [关键证据1, 关键证据2] }} 要点三做裁判校准。在正式用 LLM-judge 之前先拿一批人工标注过的样本让裁判跑一遍看它和人工判断的一致率。如果一致率低于 80%说明 rubric 或 prompt 有问题要调整。这个校准步骤很多人跳过结果就是拿着不可信的分数做决策。要点四控制裁判的随机性。把温度参数调到 0 或接近 0减少随机波动。如果条件允许同一个样本让裁判跑 3 次取多数结果进一步降低波动。3.5 评测集设计的几个反直觉经验评测集不是越多越好也不是越难越好。我踩过的坑里有几个特别值得说。坑一用例太理想化。一开始我写的用例都是标准场景输入清晰、意图明确。结果 Agent 在这些用例上表现很好一上线就崩。后来才明白真实用户的输入是模糊的、有歧义的、甚至是有错误的。评测集里必须包含这类脏输入否则测出来的分数是虚高的。坑二只测成功路径。很多评测集只测任务能完成的情况不测任务无法完成时 Agent 怎么反应。但实际场景里Agent 遇到无法完成的任务时是老实说我做不到还是硬编一个答案这个差别很大。所以评测集里要有应该拒绝或应该求助的用例。坑三忽略多轮场景。单轮任务好测多轮对话难测。但 Agent 的价值恰恰在多轮交互里体现。评测集里要有需要多轮澄清、多轮修正的用例才能测出 Agent 的上下文保持能力。4. 实操过程与核心环节实现4.1 从零搭一套评测流程的完整步骤假设你现在有一个 Agent想给它搭一套评测体系。我按实际操作顺序把步骤拆开讲。第一步明确评测目标。先问自己我这次评测到底想回答什么问题是Agent 能不能完成核心任务还是Agent 在边界情况下表现如何还是新版本比旧版本有没有退步。目标不同评测集的设计、rubric 的侧重、指标的选择都不一样。这一步最容易被跳过但恰恰最重要。第二步设计评测集。根据目标设计 30-50 条用例。每条用例包含任务输入、预期结果可以是参考答案也可以是判定标准、难度标签、场景标签。难度标签用来分层分析场景标签用来定位问题。我一般会保证评测集里核心场景占 60%边界场景占 25%异常场景占 15%。第三步搭建 harness。按前面讲的结构把任务调度、执行、轨迹采集搭起来。如果 Agent 是标准框架先试试现成的 harness如果是自研用前面给的轻量结构改。这一步的关键是先跑通一条用例确认轨迹能完整采集再扩展到全量。第四步写 rubric 和 judge prompt。针对每个评估维度写分档式 rubric然后写 judge prompt。写完先拿几条样本试跑看裁判的输出是否符合预期。第五步校准裁判。人工标注 20-30 条样本让裁判跑一遍算一致率。不一致的地方逐条分析是 rubric 不清楚还是 prompt 有歧义改到一致率达标。第六步跑全量评测。用 harness 跑完整评测集采集所有轨迹和分数。这一步要注意观察超时率和错误率如果太高说明 harness 或 Agent 有问题要先解决。第七步分析结果。按难度、场景、维度分层看分数找出低分集中的区域。低分用例要逐条看轨迹定位是 Agent 的哪个环节出了问题。第八步迭代。根据分析结果改 Agent改完再跑一轮对比分数变化。这个循环要持续做评测体系的价值就在于支撑这个迭代循环。4.2 轨迹采集的关键字段设计轨迹数据是分析的基础采集哪些字段直接决定了你能分析出什么。我一般会采集这些字段字段说明用途step_index步骤序号还原执行顺序step_type步骤类型思考/工具调用/回复分析行为分布content步骤内容查看具体行为tool_name工具名称如果是工具调用分析工具使用tool_args工具参数检查参数正确性tool_result工具返回结果检查结果处理timestamp时间戳分析耗时分布token_counttoken 消耗分析成本这些字段采集全了你就能回答很多问题Agent 平均几步完成任务哪类任务步骤最多工具调用失败率高不高token 消耗集中在哪个环节这些问题靠肉眼看输出是看不出来的必须靠轨迹数据。4.3 一个真实的评测案例拆解说个具体的例子。我之前评测一个客服 Agent任务是处理用户的退换货请求。评测集里有一条用例是这样的用户输入我上周买的那个蓝色的杯子收到的时候有个小缺口我想换一个。预期行为Agent 应该先确认订单信息需要用户提供订单号或手机号然后判断是否符合换货条件最后给出换货流程。实际跑下来Agent 的表现是这样的它直接说好的我帮您安排换货请提供您的订单号。看起来没问题但仔细看轨迹发现它没有先确认商品是否在换货期内也没有确认缺口是否属于质量问题。如果这个商品已经过了换货期或者缺口是用户自己造成的这个回复就是错的。这条用例暴露的问题是Agent 的规划能力不足跳过了必要的确认步骤。这个问题在单看输出时很难发现因为输出本身很像样。只有看了轨迹才发现它漏了关键环节。这就是为什么我一直强调轨迹比输出更重要。输出是结果轨迹是过程而 Agent 的问题往往藏在过程里。4.4 并发评测的坑与处理评测集一大就必须并发跑。但并发会带来一堆问题我踩过的有这些问题一资源竞争。如果 Agent 会操作文件或数据库并发跑的时候会互相干扰。解决办法是给每个任务分配独立的工作目录或独立的数据库 schema。问题二API 限流。并发太高会触发外部 API 的限流导致大量任务失败。解决办法是控制并发数并加上重试和退避逻辑。问题三日志串扰。多个任务的日志混在一起排查问题时根本分不清哪条日志属于哪个任务。解决办法是给每个任务分配唯一的 trace_id所有日志都带上这个 id。问题四内存泄漏。长时间跑大量任务如果轨迹数据一直堆在内存里会把内存吃满。解决办法是边跑边落盘或者分批处理。# 带重试和退避的执行逻辑 async def run_with_retry(self, task, max_retries3): for attempt in range(max_retries): try: return await self.run_single(task) except RateLimitError: wait 2 ** attempt # 指数退避 await asyncio.sleep(wait) except Exception as e: if attempt max_retries - 1: raise return None5. 常见问题与排查技巧实录5.1 Harness 相关的典型问题问题harness 插件加载失败。这是很多人装现成 harness 时遇到的第一个坑。报错通常是failed to load plugins或者entries did not activate。原因一般是版本不匹配或者依赖没装全。排查思路先看 harness 的版本和你的 Agent 框架版本是否兼容再看插件依赖是否都装了。如果还不行看日志里具体是哪个插件加载失败单独排查那个插件。问题任务执行到一半卡住。表现是 harness 跑了很久没动静也不报错。原因可能是 Agent 在等一个永远不会返回的工具调用或者陷入了死循环。解决办法是给每个任务设超时超时后强制中断并记录当前轨迹。超时时间根据任务复杂度设一般 60-180 秒。问题轨迹数据不完整。表现是分析时发现某些步骤缺失。原因可能是采集逻辑有遗漏或者 Agent 的某些行为没有触发回调。排查思路先确认 Agent 的所有行为路径都会触发on_step回调再看采集逻辑是否覆盖了所有步骤类型。5.2 LLM-judge 相关的典型问题问题裁判分数波动大。同一个回答跑两次分数不一样。解决办法温度调到 0多次采样取多数或者用更明确的 rubric 减少判断空间。问题裁判被话术骗了。Agent 输出一段看起来很专业但实际错误的内容裁判给了高分。这是 LLM-judge 的经典问题。解决办法是在 prompt 里明确要求裁判关注事实正确性不要被表达方式影响并且提供参考答案让裁判对照。问题裁判对某些维度不敏感。比如裁判总是给工具调用正确性打高分即使 Agent 明显调错了工具。解决办法是把这类维度从 LLM 裁判里拿出来改用规则裁判因为工具调用是否正确是可以形式化判断的。5.3 评测集相关的典型问题问题评测集和线上表现对不上。评测分数很高线上却一堆问题。原因通常是评测集太理想化没有覆盖真实场景的复杂性。解决办法是定期从线上 badcase 里补充评测用例让评测集活起来。问题评测集过拟合。团队为了让分数好看针对评测集调优结果模型在评测集上表现很好换个场景就崩。解决办法是保留一部分隐藏评测集不参与日常迭代只在关键节点用来验证。问题评测集维护成本高。随着 Agent 功能变化评测集里的用例会过时。解决办法是给每条用例打上最后验证时间标签定期清理过时用例补充新用例。5.4 常见问题速查表问题现象可能原因排查方向解决思路插件加载失败版本不匹配/依赖缺失查版本兼容性、查依赖对齐版本、补装依赖任务卡住不返回死循环/工具挂起看最后一步轨迹加超时、加中断轨迹数据缺失回调未覆盖检查采集逻辑补全回调、加兜底裁判分数波动温度高/rubric 模糊看多次采样差异降温、细化 rubric裁判被话术骗prompt 未强调事实看裁判理由加事实核查要求评测与线上不符评测集太理想对比线上 badcase补充真实用例评测集过拟合针对评测调优看隐藏集表现保留隐藏评测集5.5 几个独家避坑技巧技巧一先跑通一条再跑全量。很多人一上来就跑全量评测结果 harness 有问题跑了一小时全是废数据。正确做法是先拿一条用例跑通确认轨迹完整、分数合理再扩展到全量。技巧二给评测集打标签。每条用例打上难度、场景、类型标签分析时就能按标签分层看。比如多轮对话类用例平均分明显低于单轮这个发现比一个笼统的总分有价值得多。技巧三保留原始轨迹。分数只是结论轨迹才是证据。分析问题时一定要能回看原始轨迹。我一般会把轨迹存成 JSON 文件按任务 id 命名方便随时调取。技巧四定期做裁判校准。LLM-judge 会随着模型更新而漂移今天校准好的裁判过一个月可能就不准了。建议每次大版本迭代前都重新校准一次。技巧五评测要跑在和生产一致的环境里。如果生产用的是某个特定版本的模型、特定的工具配置评测也要用同样的配置。否则测出来的分数没有参考价值。6. 评测体系的持续运营与扩展方向6.1 把评测变成日常流程评测体系搭起来只是开始真正的价值在于持续运营。我的做法是把评测接入 CI 流程每次 Agent 有代码变更自动跑一轮核心评测集分数下降超过阈值就阻断合并。这样能防止改了一个地方悄悄弄坏了另一个地方。核心评测集要小而精跑得快适合频繁执行。全量评测集可以大一些但只在发版前跑。两套评测集配合使用兼顾速度和覆盖度。6.2 从评测到可观测的延伸评测是离线的可观测是在线的。两者结合才能形成完整闭环。线上运行时把关键指标任务完成率、工具调用成功率、平均耗时、token 消耗实时采集起来和离线评测的分数对照看。如果线上指标突然下降可以快速定位是不是某个变更导致的。更进一步可以把线上低分样本自动回流到评测集里让评测集持续进化。这样评测体系就不是一个静态的工具而是一个能自我更新的系统。6.3 多 Agent 协作场景的评测挑战单 Agent 评测已经够复杂了多 Agent 协作的评测更难。因为这时候不仅要评每个 Agent 的表现还要评它们之间的协作质量信息传递是否准确、任务分配是否合理、冲突解决是否有效。这块我目前也在摸索。初步的思路是把协作过程也纳入轨迹采集然后针对协作这个维度单独写 rubric。比如评估信息传递准确性就看下游 Agent 拿到的信息是否完整、是否被正确理解。这个方向还在演进但可以确定的是随着 Agent 系统越来越复杂评测体系也必须跟着升级。6.4 一些个人体会做 Agent 评测这段时间我最大的体会是评测体系的价值不在于给出一个分数而在于帮你理解 Agent 的行为。一个漂亮的分数如果没有配套的轨迹分析就是自欺欺人。反过来哪怕分数不高只要你能从轨迹里看出问题在哪这个评测就是有价值的。另一个体会是评测体系要够用就好不要追求一步到位。一开始可以很简单几十条用例、一个轻量 harness、一个基础 rubric先跑起来。跑起来之后你会自然发现哪里不够用再逐步补。最怕的是一直在设计从来没跑过那样永远不知道真实的问题在哪。最后分享一个小技巧每次评测完不要只看总分一定要看分数分布。如果分数集中在中间档说明 Agent 表现不稳定如果两极分化说明它在某些场景下很好、某些场景下很差。分布比均值更能说明问题。