Agent评测体系从零搭建：Harness、Rubric与LLM-judge实战指南

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 评测体系拆成四层，从下往上分别是：

这四层里，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_factory=list) final_output: str = "" status: str = "pending" duration: float = 0.0 error: str = "" class Harness: def __init__(self, agent, dataset, concurrency=4, timeout=120): self.agent = agent self.dataset = dataset self.concurrency = concurrency self.timeout = timeout async def run_single(self, task): traj = Trajectory(task_id=task["id"], input=task["input"]) start = time.time() try: result = await asyncio.wait_for( self.agent.run(task["input"], on_step=traj.steps.append), timeout=self.timeout ) traj.final_output = result traj.status = "success" except asyncio.TimeoutError: traj.status = "timeout" traj.error = f"exceeded {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，把每个评估维度分成几个明确的档位。比如评估"工具调用正确性"这个维度：

这种分档式 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 轨迹采集的关键字段设计

轨迹数据是分析的基础，采集哪些字段直接决定了你能分析出什么。我一般会采集这些字段：

这些字段采集全了，你就能回答很多问题：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_retries=3): 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 None

5. 常见问题与排查技巧实录

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 常见问题速查表

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 表现不稳定；如果两极分化，说明它在某些场景下很好、某些场景下很差。分布比均值更能说明问题。