✦✦Firefly Labs Studio
Back to translations

用 Harness 工程提升 Deep Agents 性能

从 Top 30 到 Top 5：通过 Harness 优化提升编码 Agent 的实战经验

Vivek Trivedy·2026-02-17·Published on 2026-03-17·Original article

TLDR：我们的编码 Agent 在 Terminal Bench 2.0 上从 Top 30 跃升至 Top 5。我们只改变了 Harness。以下是我们进行 Harness 工程的方法（剧透：自我验证和 Trace 分析帮助很大）。

Harness 工程的目标

Harness 的目标是将模型参差不齐的智能塑造成我们关心的任务所需的形态。Harness 工程是关于系统的——你围绕模型构建工具链，以优化任务性能、token 效率、延迟等目标。设计决策包括系统提示词、工具选择和执行流程。

但你应该如何改变 Harness 来提升你的 Agent？

在 LangChain，我们使用 Trace 来大规模理解 Agent 的故障模式。当今的模型很大程度上是黑盒，它们的内部机制难以解读。但我们可以看到它们在文本空间中的输入和输出，并在改进循环中使用这些信息。

我们使用一个简单的方案，将 deepagents-cli（我们的编码 Agent）在 Terminal Bench 2.0 上迭代改进了 13.7 分——从 52.8 提升到 66.5。我们只调整了 Harness，模型保持不变（gpt-5.2-codex）。

实验设置与 Harness 上的旋钮

我们使用 Terminal Bench 2.0，这是一个现在被广泛采用的代理编码评估基准。它包含 89 个跨领域的任务，涵盖机器学习、调试和生物学等领域。我们使用 Harbor 来编排运行。它启动沙箱（Daytona），与我们的 Agent 循环交互，并执行验证和评分。

每个 Agent 操作都存储在 LangSmith 中。它还包括延迟、token 计数和成本等指标。

我们可以调节的旋钮

Agent Harness 有很多旋钮：系统提示词、工具、钩子/中间件、技能、子代理委派、记忆系统等。我们有意压缩优化空间，专注于三个：系统提示词、工具和中间件（我们对围绕模型和工具调用的钩子的称呼）。

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

运行变更内容得分
基线默认编码提示词、文件系统工具、规划等52.8%
+ 自定义提示词和中间件聚焦构建-验证循环、注入环境上下文。添加循环保护和超时警告63.6%
+ 自适应推理xhigh+high 推理66.5%

Trace 分析技能

我们希望 Trace 分析可重复，因此将其做成了一个 Agent 技能。它作为我们分析跨运行错误并改进 Harness 的方案。流程如下：

  • 从 LangSmith 获取实验 Trace

  • 生成并行错误分析 Agent → 主 Agent 综合发现和建议

  • 聚合反馈并对 Harness 进行针对性修改

这类似于提升法（Boosting），专注于之前运行中的错误。人类在第 3 步（虽然不是必须的）可以帮助验证和讨论建议的修改。过度拟合某个任务的更改会损害泛化能力，并可能导致其他任务的回归。

自动化 Trace 分析节省了大量时间，使快速尝试实验变得容易。我们很快就会发布这个技能，目前正在测试将其用于通用提示词优化。

真正提升 Agent 性能的方法

自动化 Trace 分析帮助我们调试 Agent 出错的地方。问题包括推理错误、不遵循任务指令、缺少测试和验证、超时等。我们在以下部分详细介绍这些改进。

构建与自我验证

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

自我验证允许 Agent 通过运行内的反馈进行自我改进。然而，它们没有自然进入构建-验证循环的倾向。

最常见的故障模式是：Agent 编写解决方案、重新阅读自己的代码、确认看起来没问题，然后就停止了。测试是自主代理编码的关键部分。它帮助测试整体正确性，同时为 Agent 提供持续改进的信号。

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

  • 规划与发现：阅读任务，扫描代码库，根据任务规范和如何验证解决方案制定初始计划。

  • 构建：以验证为前提实施计划。构建测试（如果不存在），测试正常路径和边界情况。

  • 验证：运行测试，阅读完整输出，对照需求（而不是对照自己的代码）。

  • 修复：分析任何错误，重新审视原始规范，修复问题。

我们真正专注于测试，因为它驱动了每次迭代中的变化。我们发现，除了提示词之外，确定性的上下文注入有助于 Agent 验证它们的工作。我们使用 PreCompletionChecklistMiddleware，在 Agent 退出前拦截它，提醒它根据任务规范执行验证。这类似于 Ralph Wiggum 循环——钩子在退出时强制 Agent 继续执行，我们将其用于验证。

给 Agent 提供环境上下文

Harness 工程的一部分是为上下文工程构建良好的传递机制。Terminal Bench 任务带有目录结构、内置工具和严格的时间限制。

  • 目录上下文和工具：LocalContextMiddleware 在 Agent 启动时运行，映射当前工作目录和其他父子目录。我们运行 bash 命令来查找 Python 安装等工具。上下文发现和搜索容易出错，因此注入上下文减少了错误面，帮助 Agent 熟悉其环境。

  • 教 Agent 编写可测试的代码：Agent 不知道它们的代码需要怎样才能可测试。我们添加提示词说明它们的工作将通过程序化测试来衡量，类似于提交代码时的情况。例如，提到文件路径的任务规范应该被精确遵循，以便解决方案在自动评分步骤中正常工作。强调边界情况的提示词帮助 Agent 避免只检查"正常路径"。强制模型遵循测试标准是避免随时间"质量滑坡"的有力策略。

  • 时间预算：我们注入时间预算警告来推动 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 任务非常困难。一个好的计划有助于更快地获得可行的解决方案。

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

仅在 xhigh 模式下运行得分很差，只有 53.9%（因为 Agent 超时），而 high 模式为 63.6%。在不同推理预算分配的试运行中没有显著差异，所以我们坚持使用我们的方法，将得分推至 66.5%。

模型的自然方法是自适应推理，如 Claude 和 Gemini 模型所示——模型决定在推理上花费多少计算资源。

在多模型 Harness 中，平衡推理预算可以表现为使用大模型进行规划，然后交接给较小的模型进行实现。

构建 Agent Harness 的实践总结

Agent 的设计空间很大。以下是我们实验和构建 deepagents 过程中的一些通用原则。

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

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

  • Trace 作为反馈信号。Trace 允许 Agent 自我评估和调试。将工具和推理一起调试很重要（例如：模型走错路径是因为它们缺少工具或如何做某事的指令）。

  • 短期检测和修复不良模式。当今的模型并不完美。Harness 设计者的工作是围绕当今的不足进行设计，同时为未来更智能的模型做规划。盲目重试和不验证工作就是很好的例子。这些护栏几乎肯定会在时间推移中消失，但要构建稳健的 Agent 应用，它们是值得尝试的有用工具。

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

Harness 设计还有更多开放研究要做。有趣的途径包括多模型系统（Codex、Gemini 和 Claude 协同工作）、用于持续学习的记忆原语（让 Agent 能自主改进任务），以及跨模型衡量 Harness 变更。

对于改进 Agent 的外层循环，我们正在研究 RLM 等方法来更高效地挖掘 Trace。我们将继续改进 Harness 并公开分享我们的研究。

我们创建了 Trace 数据集 与社区分享。

Deep Agents 是开源的。Python 和 Javascript。

致以更多的持续优化和开放研究。