耐点
博客

研究、选择和以及如何构建自己的 Agent Harness

约 28 分钟29 次阅读

Agent Harness 研究、开源项目与行业实践

Agent Harness 是把语言模型变成可用 Agent 的脚手架：它组装提示词、暴露工具、管理环境并记录执行轨迹。本指南涵盖最新研究、主流开源项目、各家前沿实验室的 Harness 工程实践。

两个 Agent 即使使用完全相同的模型，在同一个基准测试上也可能跑出截然不同的结果。OpenAI 曾直接测量过这种差异：在 SWE-bench Lite 上，同样使用 GPT-4，一套 Harness 的解题率只有 2.7%，另一套则达到 28.3%，相差超过 10 倍。模型没有变，真正拉开差距的是围绕模型构建的 Agent Harness。当行业关注的问题从“哪个模型更聪明”逐渐转向“哪个 Agent 能真正把任务完成”，Harness 也从幕后工程细节，变成了决定 Agent 能力上限与执行可靠性的关键一层。阅读本文，了解什么是 Agent Harness、最新论文和基准测试揭示了哪些 Harness 设计原则、哪些开源 Harness 值得关注，以及各大 AI 实验室如何构建自己的 Harness。

什么是 Agent Harness？

Agent Harness（智能体运行脚手架，下文统一用英文简称 Harness）是让大语言模型在真实环境中作为 Agent 运行的外围基础设施。模型只负责生成文本，其余一切都由 Harness 完成：它在每一步组装提示词、定义有哪些工具以及如何调用、在沙箱或终端中执行动作、把观察结果回传给模型、强制限制步数和成本，并记录完整执行轨迹用于评估或调试。

这个术语来自评测领域——在软硬件测试里，test harness（测试脚手架）指的是在受控条件下驱动被测系统运行的装置。在 Agentic AI 中，同一个概念被延伸到了生产环境：Harness 既是用来衡量 Agent 的装置（如 SWE-bench 或 Terminal-Bench），也是用来运行 Agent 的脚手架（如 SWE-agent、OpenHands 或 Claude Code）。

Anthropic 自己的 SWE-bench 研究说得很直白：该基准“评估的不是孤立状态下的 AI 模型，而是一整个‘Agent’系统”，这里的 Agent 指的是“AI 模型与其外围软件脚手架的组合”。他们升级后的 Claude 3.5 Sonnet 在 SWE-bench Verified 上达到 49%，靠的不是复杂框架，而是一套极简 Harness：一段提示词加两个通用工具（一个 Bash 工具和一个编辑工具）。

一个好用的思维模型：模型 × Harness = Agent 表现。前沿实验室现在报告基准分数时都会附上所用的 Harness，因为同一个模型在不同 Harness 下可能相差几十个百分点。

为什么 Harness 和模型一样重要

多年来，榜单上的进步都被归因于模型规模，而最近的研究从两个方向打破了这个假设。

第一个方向是“少即是多”。2025 年 7 月，SWE-bench 团队发布了 mini-SWE-agent，一套约 100 行 Python 的 Harness，除了 bash 没有任何工具，消息历史完全线性，每个动作都通过独立的 subprocess.run 调用执行。它跑出的基准分数与远比它复杂的框架相当（具体见下文研究章节）。它揭示了一个重要趋势：随着模型能力增强，Harness 未必需要不断堆叠工具和复杂机制；更简单、可预测的设计，反而可能让模型能力得到更充分的发挥。如今，mini-SWE-agent 已被 Meta、NVIDIA、IBM、Princeton 和 Stanford 等机构采用。

第二个方向是“多即是少”。一套糟糕的 Harness——嘈杂的工具输出、失控的循环、糟糕的错误恢复——足以让前沿模型表现得十分平庸。OpenAI 发现，仅仅清理 SWE-bench 中存在缺陷的任务（详见下文 OpenAI 章节），测得的模型表现就能提升一倍多。

这就是为什么 Harness 工程本身已经成为一门学科。Harness 决定了：

  • 模型看到什么： 提示词结构、工具 schema、多少环境状态和历史被放进上下文窗口。

  • 模型能做什么： 有哪些工具可用（shell、文件编辑器、浏览器、搜索），以及动作在执行前如何被解析和校验。

  • 失败如何处理： 重试、超时、上下文填满时的压缩，以及任务无法继续时如何安全结束。

  • 工作如何衡量： 轨迹记录、评分和成本核算。

Agent Harness 的解剖结构

无论是研究用的基准装置还是生产级的编码助手，几乎每套 Agent Harness 都实现同一个核心循环：

  1. 任务接入： 读取问题单、指令或目标，并启动一个隔离环境（通常是 Docker 容器或虚拟机快照）。

  2. 提示词组装： 把系统提示词、工具定义、任务描述以及不断累积的动作与观察历史组合起来。

  3. 动作解析： 识别模型想执行的操作，并将其转换成实际的工具调用，比如运行一条 bash 命令、编辑文件或发送 API 请求；如果输出格式有误，则拒绝执行。

  4. 执行与观察： 在环境中运行动作，捕获 stdout/stderr 或 UI 状态，并将其截断以适配上下文预算。

  5. 控制流： 强制限制步数、成本和停止条件；决定何时询问人类或结束这一轮。

  6. 记录与评分： 保存完整轨迹并评估最终状态，比如在 SWE-bench 中运行仓库的测试套件。

每一步的设计选择都会层层叠加。仅截断策略一项就能显著影响长程任务的分数，这就是为什么认真的团队把 Harness 当作有版本管理、可测试的软件，而不是只把模型和工具串起来的辅助代码。

最新研究：论文到底说了什么

关于 Agent Harness 的学术文献已经收敛出几条来之不易的结论。这一节不回逐个罗列基准，而是会追溯迫使整个行业认真对待 Harness 的那些研究问题。

Benchmark 入门：是什么、怎么测、怎么读

在进入论文之前，先补一点背景。基准测试（benchmark） 是一套固定的任务集加一条评分规则，目的是让不同系统能在完全相同的条件下被比较。在 Agent 评测中，一个基准有三个活动部件：任务集（真实 GitHub 问题单、终端命令、网页任务）、执行环境（Docker 容器、浏览器、终端），以及评分器（测试套件、状态检查、人工审查）。Harness 位于模型与这三者之间：正是这个变量决定了模型的能力能否体现在分数上。

分数到底是怎么测出来的，比头条数字更重要。在 SWE-bench 中，Agent 产出一个代码补丁；基准随后运行两套测试：FAIL_TO_PASS（修复前失败、现在必须通过的测试）和 PASS_TO_PASS（原本正常、不能被改坏的测试）。只有两者都通过，任务才算被解决。这就是为什么测试执行和补丁生成这类 Harness 特性不是可选加分项——它们就是得分或失分的地方。

读懂任何基准分数的三条规则：

  1. 问分数掩盖了什么。 在公开 GitHub 数据上训练过的模型，可能早就见过它被测试的那些问题单——数据污染可以在没有真实能力提升的情况下抬高分数。可复现的环境和预留任务集是解药。

  2. 警惕古德哈特定律： 当一项度量成为目标，它就不再是好的度量。为刷榜而调的 Harness 学到的可能是针对特定基准的技巧，而不是通用能力。这就是为什么认真的团队会在不止一套基准上评估。

  3. 看 Harness，而不只看模型。 正如本节其余部分所示，同一个模型在不同脚手架下可以得到 2.7% 或 28.3%。一个没有附上 Harness 名称的分数只是轶事，不是测量结果。

SWE-bench：暴露 Harness 问题的基准

SWE-bench 原始论文（《Can Language Models Resolve Real-World GitHub Issues?》）提出了如今已成为标准的评测方式：给模型一个真实的 GitHub issue 和完整仓库，评分标准是它的补丁能否让原本失败的测试通过。它最常被引用的结果经常被误读：当时最强的模型 Claude 2 只解决了 1.96% 的任务。论文作者自己的表述是，该基准测试的是“远超传统代码生成任务的复杂推理”，但后续工作表明，差距的很大一部分并不是推理能力，而是缺少一套能浏览仓库、运行测试并迭代修复的 Harness。换句话说，SWE-bench 不只是在衡量模型；它揭示了模型外围的 Harness 才是缺失的那一块。

SWE-agent：为 Harness 命名的论文

SWE-agent 论文（《Agent-Computer Interfaces Enable Automated Software Engineering》）是 Harness 设计领域的奠基文献。它的核心论点是接口设计是一阶变量：作者提出了 Agent-Computer Interface（ACI，智能体-计算机接口）这一术语，并展示了一套专门构建的接口，包括带语法检查防护的文件编辑器、简洁的 shell 反馈、对格式错误命令的护栏，从而把 SWE-bench 上的 pass@1 从低个位数提升到 12.5%，在当时创下最佳纪录。这篇论文最长久的贡献是这样一个论断：“语言模型 Agent 代表了一类新的终端用户”，它们需要为它们而造的软件，就像人类需要 IDE 一样。此后每一篇 Harness 论文都引用这个结果。

OSWorld 与 WebArena：Harness 走出终端

2024 年的两篇论文把 Harness 研究从代码仓库扩展到整台计算机。OSWorld 构建了首个跨 Ubuntu、Windows 和 macOS 的可扩展真实计算机环境，包含 369 个覆盖网页和桌面应用的任务。值得注意的是，人类能完成 72.36% 的任务，而最强模型只有 12.24%，这表明 GUI grounding（把模型输出翻译成正确的点击和按键）是主要的失败模式，这是 Harness 问题，而不是知识问题。WebArena 则走了另一条路：一个自托管、完全可复现的网页环境（电商、论坛、GitLab、CMS），GPT-4 的端到端任务成功率只有 14.41%，而人类是 78.24%。两篇论文都确立了：Harness 评估必须基于执行（检查环境的最终状态），而不是对模型输出做模式匹配。

τ-bench：用户也是 Harness 的一部分

Sierra 的 τ-bench（《A Benchmark for Tool-Agent-User Interaction in Real-World Domains》）提出了一个更微妙的观点：在生产环境中，Harness 不只包裹模型和环境——它还中介着用户。该基准模拟了由语言模型扮演的用户与配备领域 API 和策略指南的 Agent 之间的动态对话，然后对数据库的最终状态评分。它的关键指标 pass^k（k 次独立试验的成功率）暴露了 Agent 的不一致性：GPT-4o 单次通过的任务不到 50%，零售场景下 pass^8 更是跌破 25%。对 Harness 构建者的教训是：可靠性是一个分布属性，而不是单次运行属性——只能跑通一次的 Harness 不算能用的 Harness。

METR：Harness 必须随模型一起进化

METR 的《Measuring AI Ability to Complete Long Software Tasks》提出了 50% 任务完成时间跨度（50%-task-completion time horizon）：模型能以 50% 可靠性完成的任务长度（以人类完成所需时间衡量）。2019 到 2025 年间，前沿模型从几分钟进步到大约一小时，大约每七个月翻一倍。对 Harness 工程来说，这是十年来最重要的发现：约束 2024 年模型的 Harness，对 2026 年的模型来说就是累赘。Anthropic 的表述是：Harness 中的每个组件都编码了一个关于“模型做不到什么”的假设——而这些假设会随着模型进步而过时。

SWE-bench 家族现状

这个原始基准已经发展成一个把上述教训落地的生态：

  • SWE-bench Verified（与 OpenAI 合作，2024）：经人工筛选的 500 个实例子集，剔除了描述不清或评分不公的任务——原始任务池的 68.3% 被过滤掉，测得分数因此翻了一倍多。

  • SWE-smith（2025）：生成合成训练任务的流水线，让模型可以为 Agentic Harness 而训练，而不只是被评测。

  • mini-SWE-agent（2025）：约 100 行的 Harness，如今在 SWE-bench Verified 上超过 74%，证明模型足够强时，一个只有 bash、线性历史的极简循环就够了——正在成为社区默认基线。

  • Terminal-Bench（斯坦福 × Laude，2025）：基于 Harbor 框架的终端任务评测，把 Harness 从代码编辑推向系统管理。

  • CodeClash（2025）和 ProgramBench（2026）：目标导向和从零构建软件的评测，把 Harness 从单 issue 修复推向开放式开发。

所有这些工作的共同主线是一致的：Harness 不是管道工，它就是研究对象本身。报告分数时附上 Harness，保持环境可复现，对任何脚手架无法被检查的结果保持怀疑。

大厂如何打造 Agent Harness

前沿实验室把 Harness 工程当作核心知识产权，其中几家还罕见地公开了他们的思路。

Anthropic

Anthropic 公开了最完整的 Harness 工程记录，其架构可以解读为三个同心层。

执行层刻意保持极简：一个运行命令的 Bash 工具和一个查看、修改文件的编辑工具。设计精力都花在了让工具防错上——要求绝对路径、截断超长输出、只在唯一匹配时应用编辑——这样模型就很少需要从本可避免的工具故障中恢复。

会话层是位于模型上下文窗口之外的持久、只追加事件日志。每个动作和观察都记录在那里；模型的上下文是该日志的投影，而不是日志本身。正是这种分离，让崩溃的 Harness 进程可以重启并在任务中途恢复，让 Harness 成为一次性的“牲畜”而不是需要呵护的“宠物”。

编排层——Anthropic 称之为 “meta-harness”——通过显式接口把“大脑”（模型及其循环）与“双手”（沙箱和工具）解耦。因为大脑不再住在执行容器里，沙箱可以按需创建，凭证可以放在沙箱永远接触不到的保险库里。他们报告的收益是结构性的而非表面的：p50 首 token 延迟下降约 60%，p95 下降超过 90%，因为会话不再需要等待可能永远用不到的容器。

三份文档记录了这条演进路线：《Building Effective Agents》（2024）、SWE-bench Harness 文章（2024），以及《Managed Agents》（2026）。

OpenAI

OpenAI 与 SWE-bench 团队合作创建了经人工验证的 Verified 子集，正是因为 Harness 需要干净的任务：他们的标注活动（93 名开发者、1,699 个样本）发现原始基准中 68.3% 的任务存在问题，剔除后测得的表现翻了一倍多。同一篇文章还指出，仅 Harness 选择一项就让 GPT-4 在 SWE-bench Lite 上从 2.7% 提升到 28.3%——他们引用这个差距来论证：评估必须计入社区构建的 Harness 的进步。

在开源方面，Codex CLI 作为一套完整的参考 Harness 发布。其架构以与本节其他系统相呼应的方式分层：核心 Agent 循环负责规划和工具调用；沙箱层按任务配置策略隔离执行；会话层持久化对话，使其可以恢复、分叉或压缩；工具层同时暴露本地 shell 访问和基于 MCP 的外部工具。同一引擎不硬编码单一界面，而是通过三种界面暴露——用于交互工作的终端 UI、供 VS Code 等富客户端使用的 JSON-RPC 应用服务器，以及用于云沙箱的远程代码执行服务——因此 Harness 既能本地运行，也能以编程方式驱动。这些设计做出了研究文献推荐的同样的取舍：极简循环、强沙箱、显式上下文管理，以及模型与外部世界之间的清晰边界。

Google

通过 Agent Development Kit（ADK）和 Agent2Agent（A2A）协议——于 2025 年 4 月与 Atlassian、Salesforce、SAP、ServiceNow 等 50 多家技术伙伴共同发布——Google 正在把 Harness 层本身产品化。A2A 标准化了 Agent 宣告能力（通过 JSON “Agent Card”）、管理长程任务、交换产物和协商 UI 格式的方式，让 Harness 成为可互操作的基础设施，而不是定制的胶水代码。它被明确设计为与 Anthropic 的 Model Context Protocol（MCP）互补，后者标准化的是 Harness 的工具一侧。

微软及其他

微软的 AutoGen 和 Magentic-One 提供的 Harness 中，编排 Agent 维护一本记录事实与进展的台账——这是为防止困扰朴素 Harness 的失控循环而公开的设计。Meta 和 Hugging Face 的 GAIA 创建了一个通用助手基准，其 Harness 为需要网页导航和文件处理的真实问题评分；Hugging Face 的 Open Agent Leaderboard 则继续推动可比较、Harness 感知的排名。

DeepSeek

DeepSeek Harness（dsh）把 meta-harness 理念做成了可组合的架构。它构建于 Cordis 框架之上，核心主张是Harness 的每个部分都是可替换插件——包括模型适配器、工具注册表、会话日志和 Agent 循环本身。

其设计基于三个原语。第一，持久会话日志：模型所见内容的唯一事实来源；任何到达模型的内容都必须能从日志重建，并以运行时不变量强制保证。第二，能力接缝（capability seam）：Agent 与外部世界之间的可替换提供者接口，把文件系统和子进程提供者指向远程沙箱，Bash、终端和语言服务就随之迁移，无需分叉 Harness。第三，显式的 turn/step 生命周期：带命名扩展事件（agent/pre-step、tools/execute、agent/turn-stopping），让插件无需修改核心代码即可拦截或改写循环。

其结果是 Anthropic meta-harness 最接近的开源实现：一套结构不是固定框架、而是可从配置中替换的插件组合。发布数月即突破 17 万 GitHub star，它标志着 Agent Harness 正在成为一个独立的产品品类。

这些系统的共同模式是：保持循环简单，把一切放进沙箱，记录每一步，并且永远不相信没有附上产出它的 Harness 的分数。

如何选择或构建自己的 Agent Harness

无论你是在评估模型还是交付产品，同一份清单都适用：

  1. 从任务出发，而不是从框架出发。 如果你的 Agent 编辑代码，SWE-agent 的 ACI 这类 bash 加编辑器的 Harness 是被验证过的。如果它们操作 GUI 或真实网页，你需要真实会话的观察和点击级动作。

  2. 让环境可复现。 Docker 镜像、锁定的依赖和固定的数据种子，是基准与轶事之间的分界线。

  3. 刻意规划上下文预算。 观察截断、历史摘要和压缩是直接影响分数和成本的 Harness 特性——也是长上下文模型能减少 Harness 丢弃量的原因。

  4. 强制硬性限制。 步数上限、墙钟超时和每轮美元预算保证 Agent 安全，也让评估可比。

  5. 从第一天起记录完整轨迹。 每一个认真的改进闭环——人工审查、失败聚类、微调——都要消耗轨迹数据。Anthropic 的 Managed Agents 和 DeepSeek Harness 更进一步：把会话日志放在 Harness 循环之外作为只追加事件流，让 Harness 本身成为可弃的，模型的上下文永远可重建。

  6. 在不止一套 Harness 上评估。 如果你的 Agent 只在一套 Harness 里有效，你构建的是特定于 Harness 的行为，而不是能力。

  7. 让凭证远离沙箱——或者干脆远离云端。 把 Agent 的执行环境当作不可信的；把 token 放在保险库中通过代理注入，或者让整个会话在本地运行，让凭证和页面内容永不离开设备。

2025–2026 年研究浪潮的经验法则：如果一次 Harness 改动和一次模型升级带来相近的分数提升，优先选 Harness 改动——它更便宜、迭代更快，并且能迁移到未来的模型上。行业正在形成的共识是：每次模型进步都重新审视 Harness，因为昨天的 Harness 假设会过时。

结语

Agent Harness 已悄然成为 Agentic 技术栈中最重要的一层。来自 SWE-bench、mini-SWE-agent、Terminal-Bench 和 METR 的研究表明，Harness 设计的影响力可以与模型升级相媲美；DeepSeek Harness、OpenHands、SWE-agent 和 Aider 等开源项目让生产级 Harness 触手可及；Anthropic、OpenAI、Google、微软等也都已把 Harness 工程当作一等公民来对待。

但更深层的变化是概念上的。第一代 Harness 解决的是 Agent × Computer：给模型一双可靠的手来操作终端、浏览器、文件系统。下一个问题是 Agent × Team：让模型在对话、权限和组织知识——工作真正发生的地方——拥有一个可信的位置。Harness 正在从脚手架进化为运行环境。

无论你自建、采用开源框架，还是运行生产级 Harness，把 Harness 当作经过工程设计、有版本管理、可度量的软件来对待的团队，才是 Agent 真正能把活干完的团队。

常见问题

AI 中的 Agent Harness 是什么？

Agent Harness 是包裹在语言模型外围、让它能作为 Agent 行动的基础设施：它组装提示词、定义并执行工具、管理环境（如 Docker 容器或浏览器）、限制步数和成本，并记录轨迹用于评估。这个术语既涵盖 SWE-bench 这样的评测装置，也涵盖 Claude Code、Codex 这样的生产级 Harness。

Agent Harness 和 Agent 框架有什么区别？

框架（如 LangChain 或 AutoGen）提供构建 Agent 的积木，而 Harness 是具体的运行配置：围绕模型为某个任务搭建的特定循环、工具、提示词模板和环境。Harness 常常用框架搭建，但 mini-SWE-agent 这样的极简 Harness 证明，大约 100 行纯 Python——除 bash 外没有工具——就能在 SWE-bench Verified 上超过 74%。

2026 年最流行的开源 Agent Harness 有哪些？

采用最广的开源 Agent Harness 包括：DeepSeek Harness（数月内突破 17 万 GitHub star 的插件化 Harness）、用于全栈软件 Agent 的 OpenHands、用于极简基准测试的 mini-SWE-agent、作为研究参考的 SWE-agent、用于终端结对编程的 Aider、用于评测 Harness 的 Inspect AI，以及开源的 Codex CLI。

为什么基准分数依赖于 Agent Harness？

因为 Harness 控制着模型看到什么、能做什么：提示词结构、工具设计、观察截断、重试逻辑和步数限制都会改变结果。OpenAI 测得 GPT-4 在 SWE-bench Lite 上用两套不同 Harness 分别得到 2.7% 和 28.3%——这就是为什么实验室现在报告分数时都会附上 Harness。

如何用 Harness 评估一个 Agent？

把任务环境可复现地打包（通常用 Docker），在固定步数和成本限制下让 Agent 跑完 Harness 循环，记录完整轨迹，然后对环境的最终状态评分——例如在 SWE-bench 中运行仓库的测试套件，或在 Terminal-Bench（经由其 Harbor 运行时）中检查任务完成情况。Inspect AI 和 SWE-bench CLI 等框架可以自动化这条流水线的大部分。