LangChain 用 harness engineering 将 deepagents-cli 在 Terminal Bench 2.0 上从 52.8 提升到 66.5

TLDR：我们的编程智能体在 Terminal Bench 2.0 上从 Top 30 跃升至 Top 5。我们只改了 harness。以下是我们进行 harness 工程的方法（剧透：自我验证与追踪帮助很大）。

Harness 工程的目标

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

但你应该如何修改 harness 来提升你的智能体？

在 LangChain，我们使用 Traces 来大规模理解智能体的失败模式。如今的模型在很大程度上是黑盒，其内部机制难以解释。但我们可以在文本空间中看到它们的输入和输出，然后将其用于我们的改进循环。

我们用一个简单的配方，在 Terminal Bench 2.0 上迭代改进 deepagents-cli（我们的编程智能体）13.7 points，从 52.8 提升到 66.5。我们只调整了 harness，模型保持不变，gpt-5.2-codex。

实验设置与 Harness 上的可调旋钮

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

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

我们可以转动的旋钮

智能体 harness 有很多旋钮：系统提示词、工具、钩子/中间件、技能、子智能体委派、记忆系统等等。我们刻意压缩优化空间，聚焦于三个：系统提示词、工具和 中间件（我们对模型和工具调用周围钩子的称呼）。

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

Trace Analyzer 技能

我们希望追踪分析可以重复进行，因此将其做成了一个 Agent Skill。这是我们跨运行分析错误并改进 harness 的配方。流程是：

1. 从 LangSmith 获取实验追踪
2. 启动并行错误分析智能体 → 主智能体综合发现 + 建议
3. 汇总反馈并对 harness 进行有针对性的修改。

这与 boosting 类似，后者聚焦于之前运行中的错误。在步骤 3 中，人类可以非常有帮助（尽管并非必需），来验证和讨论提议的修改。过度拟合某个任务的修改不利于泛化，并可能导致其他任务出现回归。

自动化追踪分析节省了数小时时间，让快速尝试实验变得容易。我们很快会发布这个技能，目前正在针对提示词优化进行通用性测试。

实际提升智能体表现的因素

自动化追踪分析让我们能够调试智能体出错的地方。问题包括推理错误、未遵循任务指令、缺少测试和验证、时间耗尽等。我们将在下面的章节中更详细地介绍这些改进。

构建与自我验证

如今的模型是卓越的自我改进机器。

自我验证让智能体能够在一次运行中通过反馈自我改进。然而，它们并没有自然倾向于进入这种构建-验证循环。

最常见的失败模式是：智能体写了一个解决方案，重新阅读自己的代码，确认看起来没问题，然后就停下了。测试是自主智能体编程的关键部分。它有助于检验整体正确性，同时为智能体提供可用来爬坡优化的信号。

我们在系统提示词中加入了关于如何着手解决问题的指导。

1. 规划与探索：阅读任务，扫描代码库，并根据任务规范以及如何验证解决方案来制定初步计划。
2. 构建：在实现计划时始终考虑验证。如果测试不存在，就编写测试，并同时测试正常路径和边界情况。
3. 验证：运行测试，阅读完整输出，与任务要求进行对比（而不是与你自己的代码对比）。
4. 修复：分析任何错误，重新审视原始规范，并修复问题。

我们非常重视测试，因为它驱动着每一次迭代中的变化。我们发现，除了提示词之外，确定性的上下文注入也能帮助智能体验证自己的工作。我们使用一个PreCompletionChecklistMiddleware，在智能体退出前拦截它，并提醒它针对任务规范运行一次验证。这类似于Ralph Wiggum 循环，即通过钩子在退出时强制智能体继续执行，我们将其用于验证。

为智能体提供关于其环境的上下文

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

1. 目录上下文与工具：智能体启动时会运行一个LocalContextMiddleware来映射cwd以及其他父级和子级目录。我们运行bash命令来查找诸如Python安装之类的工具。上下文发现和搜索容易出错，因此注入上下文可以减少这一错误面，并帮助让智能体熟悉其环境。
2. 教会智能体编写可测试的代码：智能体并不知道自己的代码需要如何可测试。我们添加提示词，说明它们的工作将根据程序化测试来衡量，类似于提交代码时的情况。例如，提到文件路径的任务规范应被严格遵循，以便解决方案能在自动评分步骤中正常工作。强调边界情况的提示词有助于智能体避免只检查“正常路径”情况。强制模型遵循测试标准是避免随时间推移出现“垃圾堆积”的有力策略。
3. 时间预算：我们注入时间预算警告，以促使智能体完成工作并转向验证。智能体在时间估计方面出了名地糟糕，因此这一启发式方法在此环境中很有帮助。现实世界的编程通常没有严格的时间限制，但如果不加入任何关于约束的知识，智能体就不会在时间范围内工作。

智能体对其环境、约束和评估标准了解得越多，就越能自主地指导自己的工作。

harness 工程师的职责：准备并传递上下文，使智能体能够自主完成工作。

鼓励智能体退后一步并重新考虑计划

智能体一旦确定了计划，就可能变得目光短浅，从而导致“死亡循环”，即对同一个有问题的方案做微小改动（在某些轨迹中超过 10 次）。

我们使用一个LoopDetectionMiddleware，通过工具调用钩子来跟踪每个文件的编辑次数。当对同一文件进行N次编辑后，它会添加上下文，比如“……考虑重新考虑你的方法”。这可以帮助智能体从死循环中恢复，不过如果模型认为自己的方向正确，它仍可能继续沿着同一条路走下去。

重要提示。这是一种设计启发式，是工程师针对当前所感知到的模型问题而采用的。随着模型不断改进，这些护栏很可能将不再必要，但今天它们有助于智能体正确且自主地执行任务。

如何选择在推理上投入多少算力

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

Terminal Bench 的超时限制带来了权衡。更多推理有助于智能体评估每一步，但可能多消耗超过2x的 token/时间。gpt-5.2-codex有 4 种推理模式：low、medium、high和xhigh。

我们发现推理有助于规划，从而充分理解问题，有些 Terminal Bench 任务非常困难。好的规划有助于更快得到可用的解决方案。

后期验证也能从更多推理中受益，以发现错误并提交解决方案。作为一种启发式，我们选择 xhigh-high-xhigh 的“推理三明治”作为基线。

仅以xhigh运行时，由于智能体超时，在53.9%上得分很低，相比之下63.6%在high上表现更好。不同推理预算分配下的试运行没有太大差异，所以我们坚持了自己的方法，将得分提升到了66.5%。

对模型而言，自然的方式是自适应推理，这在Claude和Gemini模型中可以看到，由模型自行决定在推理上投入多少算力。

在多模型框架中，平衡推理预算可以表现为：用大模型进行规划，然后交接给小模型来实施。

构建智能体框架的实用要点

智能体的设计空间很大。以下是我们实验以及整体构建 deepagents 得出的一些通用原则。

1. 代表智能体进行上下文工程。如今对智能体来说，上下文组装仍然很困难，尤其是在未见过的环境中。用目录结构、可用工具、编码最佳实践和问题解决策略等上下文来引导模型，有助于减少糟糕搜索和规划中本可避免错误的出错面。
2. 帮助智能体自我验证其工作。模型会偏向于自己第一个看似合理的解决方案。要大力提示它们通过运行测试和优化解决方案来验证自己的工作。这在没有人类参与循环的自主编码系统中尤为重要。
3. 将追踪作为反馈信号。追踪让智能体能够自我评估和自我调试。将工具和推理一起调试很重要（例如：模型之所以走上错误路径，是因为缺少某个工具或不知道如何做某事的说明）。
4. 在短期内检测并修复不良模式。如今的模型并不完美。Harness 设计者的职责是围绕当下的不足进行设计，同时为未来更智能的模型做好规划。盲目重试和不验证工作就是很好的例子。这些护栏几乎肯定会随时间消解，但要在今天构建稳健的 agent 应用，它们是值得试验的有用工具。
5. 让 Harness 适配模型。The Codex 和 Claude 的提示指南表明，模型需要不同的提示方式。使用 Claude Opus 4.6 进行的一次测试运行在较早版本的 harness 上得分为 59.6%，具有竞争力，但不如 Codex，因为我们没有对 Claude 运行相同的 Improvement Loop。许多原则是通用的，比如良好的上下文准备和对验证的关注，但为你的任务运行几轮 harness 迭代有助于在各类任务中最大化 agent 性能。

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

对于改进 agent 的外层循环，我们正在研究像 RLMs 这样的方法，以更高效地挖掘 trace。我们将继续改进 harness 的工作，并公开分享我们的研究。

我们创建了一个包含我们 Trace 的数据集，与社区分享。

Deep Agents 是开源的。Python 和 Javascript。

向着更多的爬山与开放研究前进。