通过工程化的Harness改进Deep Agent

我们的Coding Agent 在 Terminal Bench 2.0 上从前 30 名跃升至前 5 名。我们只改了 harness。以下是我们的 harness 工程方法（核心观点：自我验证，另外tracing会有巨大的帮助）。

Harness 工程的目标

Harness的目标本质上就是讲模型表现出的不稳定的智能，进行塑造，从而解决我们真正所关注的任务的能力。Harness工程关注的是系统性的解决方案。我们在模型周围构建各种工具，已完成优化任务性能、token效率、延迟等目标。在进行设计的时候需要做出各种决策，其中包括系统提示词、工具选择和执行流程。

但是我们是如何通过改变Harness来提升Agent的。

在 LangChain，我们使用 Trace 来大规模地总结Agent的失败模式。当今的模型在很大程度上是黑箱，其内部机制难以解释和探究。但我们可以观察它们的输入和输出的文本，并将其用于我们的改进循环中。

我们使用了一个简单的方法，在 Terminal Bench 2.0 上将 deepagents-cli（我们的编码 agent）从 52.8 迭代提升了 13.7 个百分点，达到 66.5。我们使用的是同一个模型gpt-5.2-codex，但是我们优化了我们的harness。

设置实验与Harness的可调参数

我们使用了Terminal Bench 2.0，这是目前评估 agent 编码能力的标准基准测试方案。它包含 89 个任务，涵盖机器学习、调试和生物学等领域。我们使用Harbor来编排运行。Harbor负责启动沙箱（Daytona）、与我们的 agent 循环进行交互，并执行验证和评分。

每个 agent 的操作都存储在 LangSmith 中，同时还包括延迟、token 数量和成本等指标。

我们可以调节的参数

一个 agent harness 有很多可调参数：系统提示词、工具、钩子/中间件、技能、子agent委派、记忆系统等。我们为了提升专注度，将聚焦于三个方面：系统提示词、工具和中间件（我们对围绕模型调用和工具调用的钩子的称呼）。

我们从默认提示词和标准工具+中间件开始。使用 GPT-5.2-Codex 的初始得分为 52.8%，这是一个不错的分数，刚好在当前排行榜前 30 名之外，但仍有提升空间。

Trace 分析skill

我们希望 trace 分析是可重复的，因此将其封装为一个 Agent Skill。这是我们可以多次持续运行分析错误并改进 harness 的方法。其流程如下：

1. 从LangSmith中获得试验数据

2. 生成多个并行的错误分析Agents，然后主Agent汇总结果并提出建议

3. 汇总反馈对Harness针对性的修改建议。

这与Boosting方法的工作原理类似，即专注于先前运行中的错误。在第 3步中，人类参与会非常有帮助（虽然不是必须的），因为这可以有效的验证和进一步分析修改方案。过度拟合某个任务的修改会损害泛化能力，并可能导致其他任务出现回退。

自动化 trace 分析节省了大量时间，并可以快速尝试，这使得实验变得容易了。我们即将发布这个技能，目前正在测试其在通用提示词优化方面的效果。

真正提升Agent性能的关键因素

自动化 Trace 分析使我们能够定位 agent 出错的位置。问题包括推理错误、未遵循任务指令、缺少测试和验证、超时等。我们将在以下章节中详细介绍这些改进。

构建并自验证

当今的模型是出色的自我改进机器。

自我验证允许 agent 在单次运行中通过反馈进行自我改进。然而，它们并没有天然的具备这种构建-验证循环的倾向。

最常见的失败模式是：agent 编写了一个解决方案，重新阅读自己的代码，确认看起来没问题，然后就停止了。测试是自主 agent 编码的关键环节，它有助于验证整体的正确性，同时为 agent提供可以持续优化的信号。

我们在系统提示词中添加了关于如何进行问题解决的指导：

1. 规划与发现：阅读任务描述，扫描代码库，并根据任务规格说明及验证方案制定初始计划。

2. 构建：在实现计划时牢记验证的必要性。如果测试不存在就编写测试，并且这些测试需要覆盖正常路径和边界情况。

3. 验证：运行测试，阅读完整输出，与任务要求（而非自己的代码）进行对照比较。

4. 修复：分析所有错误，回顾原始Spec文件，修复问题。

我们非常注重测试，因为它驱动着每次迭代中的改进。我们发现，除了提示词之外，确定性的上下文注入也有助于 agent 验证其工作。我们使用了一个 PreCompletionChecklistMiddleware，它在 agent退出前进行拦截，提醒它针对任务规格说明执行一次验证。这类似于 Ralph Wiggum 循环，通过钩子强制 agent 在退出时继续执行。我们就是通过这样不断循环来完成验证的。

为 Agent 提供其环境的上下文

Harness 非常重要的一个环节就是是为上下文工程构建良好的交付机制。Terminal Bench的任务附带有目录结构、内置工具和严格的超时限制。

1. 目录上下文与工具：LocalContextMiddleware 在 agent 启动时运行，映射当前工作目录及其父目录和子目录。我们运行 bash 命令来发现工具，例如已经安装的python。上下文发现和搜索容易出错，因此注入有效上下文可以减少这类错误，帮助 agent 快速熟悉其环境。

2. 教 Agent 编写可测试的代码：Agent 并不知道它们的代码需要具备可测试性。我们在提示词中说明其工作将通过程序化测试来评估，类似于提交代码时的情况。例如，任务说明中提到的文件路径应被严格遵循，以确保解决方案在自动评分步骤中能正常工作。强调边界情况的提示词有助于 agent避免只检查"正常路径"。强制模型遵循测试标准是一种非常有效的的策略，能够避免随时间累积的"质量滑坡"。

3. 时间预算管理：我们在上下文中注入时间预算警告，引导agent尽快完成工作并转入验证阶段。Agent在时间估算方面出了名地差，因此这一启发式方法在此环境中很有帮助。现实世界的编码通常没有严格的时间限制，但如果不提供任何约束信息，agent就不能按时完成任务。

Agent 对其环境、约束条件和评估标准了解得越多，就越能自主地规划和执行工作。

Harness 工程师的职责：准备环境和明确的交付上下文，使 agent 能够自主完成工作。

鼓励Agent进行回退，重新审视计划

一旦 agent 确定了一个计划，它们可能会变得短视，导致"死循环"，对同一个有缺陷的方法进行微小变动（在某些 trace 中多达 10 次以上）。

我们使用 LoopDetectionMiddleware 通过工具调用钩子跟踪每个文件的编辑次数。在对同一文件进行 N 次编辑后，它会注入类似"……请考虑重新审视你的方法"的上下文。这有助于 agent从死循环中恢复，尽管如果模型认为自己是正确的，它可能仍会继续沿着该路径前进。

重要提示：这是一种针对当前模型已知问题而设计的启发式方法。随着模型的改进，这些防护机制可能将不再需要，但在当下它有助于 agent 正确且自主地执行。

选择在推理上投入多少计算资源

推理模型可以自主运行数小时，因此我们必须决定在每个子任务上投入多少计算资源。我们可以对每个任务都使用最大推理预算，但大多数工作都能从优化推理计算预算中受益。

Terminal Bench 的超时限制让我们可以进行更多思考和权衡。更多的推理有助于 agent 评估每个步骤，但可能消耗超过 2 倍的 token 和时间。gpt-5.2-codex 有 4 种推理模式：low、medium、high 和 xhigh。

我们发现推理有助于规划阶段充分理解问题，一些 Terminal Bench 任务非常困难，一个好的计划能帮助Agent更快地达成可行的解决方案。

后期验证阶段也受益于更多的推理来捕捉错误并提交解决方案。作为一种启发式方法，我们选择了 xhigh-high-xhigh 的"推理三明治"作为基线。

仅使用 xhigh 模式由于 agent 超时，得分仅为 53.9%，而 high 模式则为 63.6%。在不同推理预算分配的试验运行中差异不大，因此我们沿用了自己的方法，最终将分数推至 66.5%。

更自然的方法是自适应推理，这在 Claude 和 Gemini 模型中已经实现，由模型自行决定在推理上投入多少计算资源。

在多模型 harness 中，对成本平衡的可以体现为：使用大模型进行规划，然后将实现任务交给较小的模型执行。

构建 Agent Harness 的实践要点

Agent的还有很多能力供我们去设计开发。以下是我们从实验和构建 deepagents 过程中总结的一些通用原则。

1. 代替 Agent 进行上下文工程。上下文组装对于当今的 agent来说仍然很困难，尤其是在陌生环境中。通过目录结构、可用工具、编码最佳实践和问题解决策略等上下文来引导模型入职，有助于减少搜索失误和规划中可避免错误的发生面。

2. 帮助 Agent 自我验证其工作。模型倾向于偏信第一个看似合理的解决方案。积极地提示它们，让它通过运行测试来验证自己的工作和优化解决方案。这在没有人类参与的自主编码系统中尤为重要。

3. Trace 作为反馈信号。Trace 使 agent 能够自我评估和自我调试。将工具和推理结合在一起进行调试非常重要（例如：模型走上错误的路径，是因为缺少某个工具或缺少如何操作的指令）。

4. 快速的检测并修复不良模式。当今的模型并不完美。Harness设计者的工作是针对当前的不足进行设计，同时为未来更智能的模型做好规划。盲目重试和不验证工作就是典型的例子。这些防护机制，大概率会随着时间推移而消失，但要在当下构建稳健的agent应用，它们是值得尝试的有用工具。

5. 为模型量身定制 Harness。Codex 和 Claude 的提示词指南表明，不同模型需要不同的提示方式。使用早期版本的 harness 对 Claude Opus 4.6 进行测试，得分为 59.6%，具有竞争力，但不如Codex，因为我们没有对 Claude 运行同样的改进循环。许多原则是通用的，比如良好的上下文准备和对验证的重视，但针对你的任务进行几轮 harness 迭代有助于在各类任务中最大化 agent 性能。

在 harness 设计方面还有更多开放性研究有待开展。有趣的方向包括多模型系统（Codex、Gemini 和 Claude 协同工作）、用于持续学习的记忆原语以使 agent 能够自主改进任务表现，以及衡量harness 变更在不同模型间的效果。

于改进 agent 的外循环，我们正在研究 RLMs 等方法，以更高效地挖掘 trace 数据。我们将继续改进 harness 并公开分享我们的研究成果。同时我们分享了我们的跟踪数据

译者评注

在2026年2月份的时候，自己开始了一个叫morty的项目，其核心目的就是控制Claude Code进行24小时不间断的编程。其中核心的思想和这篇文章有很多不谋而合的地方，在不同的阶段使用不同的模型，注重计划的生成和任务的验证，记录迭代信息以便以后进一步的优化。但是在三月的时候，自己就将这个项目封存停止开发了，因为发现了更好的项目，另外自己取消了24小时不间断编程的任务。当然取消24小时编程的事情就是另外一个故事了。

从构建Agent的角度来说，我们在构建真正的Agent系统前应当构建出一套针对Agent的追踪系统，当然我们可以使用LangSmith，然是如果我们的Agent系统是内嵌在workflow中的，那么我们就更应该构建自己的追踪系统，以便于我们能正确评估我们的Agent的表现。

从使用Coding Agent的使用角度来看，我们在claude.md/agents.md这两个文件的内容上来说，将会发生一些变革，不再是针对代码而是针对可控的环境和环境中可用工具的边界。我们应当转变思维，将Coding Agent员工化，释放自己的时间和生产力，做到爱自己以人为本。

原文：Improving Deep Agents with harness engineering