---
title: "从零搭建 Mini Agent Harness"
author: "陈思州 (Datawhale)"
source: "微信公众号 Datawhale干货"
date: "2026-05"
url: "https://mp.weixin.qq.com/s/yVFQej3dFk9KHv6J2u6Lew"
type: "article"
---

# 从零搭建 Mini Agent Harness

**作者**：陈思州，Datawhale 成员  
**来源**：Datawhale干货（微信公众号）

## 全文

前面讲 Agent 评测时，我提到：评测 Agent 不能只看最终答案，还要看它用了什么工具、拿到了什么结果、有没有按任务要求完成。那这些东西要怎么稳定记录下来？这就需要一个 harness。

现在有一个观点是 **Agent = model + harness**；

我会把 harness 理解成：把 Agentic model 放进一个可运行、可记录、可评分的小环境里。它不一定一开始就很复杂，只要能把任务、工具、执行过程和评分结果串起来，就已经很有价值。

这篇按 4 个问题梳理：
1. 一个最 mini 的 harness 解决什么问题？
2. 它最少需要哪些模块？
3. 一个 eval case 可以怎么写？
4. 公开资料里有哪些参考？

### 一个最 mini 的 harness 解决什么问题

如果只是手动测试 Agent，很容易只看到最后回答。比如用户问"请判断这个项目是否支持插件系统"，Agent 回答"当前 README 没有插件系统相关说明，不能确认支持"。

这句话看起来合理，但我们还需要知道：它有没有真的读取 README？有没有读错文件？有没有调用无关工具？有没有把工具结果里没有的信息写进答案？

mini harness 要解决的就是这个问题。

它把任务放进一个固定环境里，让 Agent 使用指定工具完成任务，同时记录执行过程，最后用评分器判断结果。

这样我们看到的就不只是一句回答，而是一条完整记录：任务是什么，环境里有什么，Agent 调用了什么工具，工具返回了什么，最后为什么被判成功或失败。

### mini harness 最少需要哪些模块

最小结构拆成 5 个模块：

- **Task**（任务输入）：任务本身
- **Environment**（可操作环境）：代码仓库、文件组等
- **Tools**（工具接口）：read_file、list_files、run_tests 等
- **Trace**（执行记录）：每步的工具调用、参数、返回
- **Grader**（评分器）：规则或测试脚本判断结果

### 一个 eval case 可以怎么写

```json
{
  "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": "支持插件系统"
  }
}
```

跑完后记录 trace：

```json
{
  "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，回答没有超出文件内容。"}
}
```

### 公开资料参考

- **Anthropic Agent Evals**：区分 eval harness 和 agent harness，强调评估的是模型+harness 的整体效果
- **SWE-agent**：提出 Agent-Computer Interface（ACI），说明外部接口设计对 Agent 表现的影响
- **Terminal-Bench**：任务结构包含 instruction、隔离环境、测试脚本
- **SWE-bench**：典型评测流程——真实 issue → patch → 环境测试

### 核心观点

一个 mini Agent harness 不需要一开始做成完整平台。第一版只要能串起任务、环境、工具、执行记录和评分器，就已经能帮我们观察 Agent 到底哪里出问题。有了这套结构，我们就不只是"试一下 Agent 好不好用"，而是能分析问题出在任务理解、工具选择、参数填写、结果读取、步骤冗余，还是评分规则本身不清楚。
