Datawhale干货

在讨论Agent评测时，我们常常会提到一个关键点：评估一个Agent，不能只看它给出的最终答案，更要看它为了得出这个答案，具体调用了哪些工具、获取了什么中间结果、以及是否严格遵循了任务要求。那么，如何系统、稳定地记录下这些过程呢？答案就是构建一个“harness”。

业界有一种观点认为，Agent等于模型（model）加上运行框架（harness）。我们可以把harness理解为一个将Agent模型置于其中，使其能够运行、记录并接受评估的小型环境。它不必一开始就设计得极其复杂，只要能清晰地将任务、工具、执行过程和评分结果串联起来，就已经具备了巨大的实用价值。

接下来，我们将围绕四个核心问题展开梳理：一个最简化的harness究竟要解决什么问题？它至少需要包含哪些模块？一个具体的评估用例该如何编写？以及，公开资料中有哪些值得参考的实践？

一个最简化的Harness解决什么问题

如果仅仅依靠手动测试Agent，我们很容易只关注到最终输出的那一句话。例如，用户提问“请判断这个项目是否支持插件系统”，Agent回答“当前README没有插件系统相关说明，不能确认支持”。

这个回答听起来似乎合理，但背后隐藏着许多疑问：它真的去读取README文件了吗？有没有读错文件？是否调用了无关的工具？有没有将工具返回结果中并不存在的信息，臆断地写入了答案？

一个最小化的harness，正是为了解决上述问题而生的。

它的核心思路，是将任务置于一个固定的、可控的环境之中，让Agent只能使用预设的工具集来完成任务。与此同时，harness会完整记录下每一步的执行轨迹，最后通过一个评分器来客观判断任务的成功与否。

这样一来，我们看到的就不再是一句孤立的回答，而是一条完整的“证据链”：任务是什么、环境中有什么资源、Agent每一步调用了什么工具、工具返回了什么结果、以及最终为何被判定为成功或失败。这为后续的分析和优化提供了坚实的数据基础。

最小化Harness需要哪些模块

一个可运行的最小化harness结构，可以拆解为五个核心模块：

任务（Task）：定义需要Agent完成的输入和目标。
环境（Environment）：提供任务执行的可操作空间，例如一个代码仓库或一组文档文件。
工具（Tools）：Agent被允许调用的接口，比如读取文件、列出目录、运行测试等。
轨迹（Trace）：按顺序记录Agent每一步的执行详情，包括使用的工具、传入的参数、返回的结果。
评分器（Grader）：根据预设规则或脚本，对Agent的最终输出和执行过程进行评判。

具体来说，Task就是任务本身，比如“根据README判断是否支持插件系统”。Environment是任务发生的场景，对于代码Agent可能是一个Git仓库，对于文档Agent可能是一组文本文件。Tools限定了Agent的能力边界。Trace确保了过程的可追溯性。而第一版的Grader，完全可以基于简单规则或测试脚本来实现，例如检查是否读取了指定文件、答案是否包含了不应出现的信息等。

这五个模块组合起来，就构成了一个最小可行、但功能完整的Agent评估框架。

一个评估用例可以怎么写

编写一个最小化的评估用例，关键在于任务、环境和评分规则都必须明确、无歧义。一个简单的示例如下：

{
  "id": "case_001",
  "task": "判断项目是否支持插件系统",
  "environment": {
    "files": {
      "README.md": "本项目支持本地启动、基础登录和配置管理。",
      "config.md": "配置项包括 port、theme、log_level。"
    }
  },
  "tools": ["list_files", "read_file"],
  "grader": {
    "must_read": ["README.md"],
    "answer_should_include": "不能确认支持插件系统",
    "answer_should_not_include": "支持插件系统"
  }
}

这个用例涵盖了几个基本要素：目标明确、环境内容固定、可用工具清晰、评分规则可自动化检查。它非常适合用来测试Agent是否会严格基于给定的文件内容进行回答，而不是凭借“经验”或“猜测”来补充结论。

用例执行完毕后，harness至少应该生成如下格式的轨迹记录：

{
  "case_id": "case_001",
  "trace": [
    {
      "tool": "list_files",
      "arguments": {"path": "."},
      "result": ["README.md", "config.md"]
    },
    {
      "tool": "read_file",
      "arguments": {"path": "README.md"},
      "result": "本项目支持本地启动、基础登录和配置管理。"
    }
  ],
  "answer": "当前README没有插件系统相关说明，不能确认支持插件系统。",
  "grade": {
    "success": true,
    "reason": "读取了README，回答没有超出文件内容。"
  }
}

这类结构化记录的价值在于精准定位问题。如果Agent根本没有调用read_file，说明其工具使用策略有问题；如果读取了README却仍然回答“支持插件系统”，说明它对工具返回结果的利用有问题；如果反复读取无关文件，则说明其执行轨迹存在冗余，效率低下。手动测试往往只能留下模糊的主观印象，而harness留下的，是可量化、可分析的过程数据。

公开资料里有哪些参考

在构建自己的harness时，参考业界的成熟实践能事半功倍。以下几份公开资料提供了很好的思路：

Anthropic的Agent Evals 这篇文章非常值得一读，它清晰地区分了“评估框架（eval harness）”和“袋里框架（agent harness）”。前者负责运行评测、记录步骤、评分和汇总结果；后者则负责让模型以Agent的方式工作，例如处理输入、编排工具调用、返回最终结果。文章还强调了一个重要观点：评估Agent时，我们评估的其实是“模型”和“框架”协同工作的整体效果。

SWE-agent 的重点在于提出了“Agent-Computer Interface”的概念。它指出，一个代码Agent的表现好坏，不仅取决于底层模型的能力，也高度依赖于外部接口的设计。例如，如何查看文件、如何编辑代码、如何运行测试、如何将错误信息有效地反馈给模型，这些设计细节都会深刻影响最终效果。

Terminal-Bench 的任务结构设计得很清晰，通常包含任务指令、隔离环境和验证脚本三部分。其harness负责将模型接入一个终端环境，让它执行命令、安装依赖、调试错误，最后用预设的测试脚本来验证任务是否被正确完成。

SWE-bench 则展示了评估代码Agent的典型流程：给定一个真实的GitHub issue，让模型生成修复补丁（patch），然后将这个补丁应用到准备好的环境中并运行测试。这里的harness负责准备原始代码环境、应用补丁、执行测试套件并汇总通过情况。

综合来看，这些实践共同揭示了harness的核心价值：它将Agent原本“黑盒”般的运行过程，转变为一个可以复现、可以记录、可以客观评分的标准化实验。