LangChain 用 harness 工程把编码智能体在 Terminal Bench 2.0 上从 52.8 提升到 66.5

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

Harness 工程的目标

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

但你应该如何修改 harness 来改进你的 agent？

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

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

实验设置与 Harness 上的可调项

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

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

我们可以调节的旋钮

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

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

Trace 分析器技能

我们希望 trace 分析可重复，因此将其做成了一个 Agent Skill。它作为我们分析各次运行中的错误并改进 harness的配方。流程是：

从 LangSmith 获取实验 trace
启动并行错误分析 agent → 主 agent 综合发现与建议
汇总反馈并对 harness 进行有针对性的修改。

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

自动化 trace 分析节省了数小时时间，并使快速尝试实验变得容易。我们很快会发布这个技能，目前正在将其用于一般的提示词优化测试。

实际提升 agent 表现的因素

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

构建与自我验证

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

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

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

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

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

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

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

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

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

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

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 得出的一些通用原则。

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

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

对于改进智能体的外层循环，我们正在研究像 RLMs 这样的方法，以更高效地挖掘轨迹。我们将继续改进测试框架的工作，并公开分享我们的研究。

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

Deep Agents 是开源的。Python 和 Javascript。

为了更多的爬山和开放研究。