TLDR：我们的编码智能体在Terminal Bench 2.0上从 Top 30 跃升至 Top 5。我们只改了 harness。以下是我们进行 harness 工程的方法（剧透：自我验证和追踪帮助很大）。
Harness 工程的目标
harness 的目标是塑造模型固有的、参差不齐的智能，使其适配我们关心的任务。Harness 工程关乎系统，你是在模型周围构建工具，以优化任务表现、token 效率、延迟等目标。设计决策包括系统提示词、工具选择和执行流程。
但你应该如何改动 harness 来改进你的智能体呢？
在 LangChain，我们使用追踪（Traces）来大规模理解智能体的失败模式。如今的模型在很大程度上是黑盒，其内部机制难以解释。但我们可以在文本空间中看到它们的输入和输出，然后将其用于我们的改进循环。
我们用一个简单的配方来迭代改进deepagents-cli（我们的编码智能体）13.7 points从52.8到66.5在 Terminal Bench 2.0 上。我们只调整了 harness，并保持模型固定，gpt-5.2-codex。
实验设置与 harness 上的可调旋钮
我们使用了Terminal Bench 2.0，这是一个如今用于评估智能体编码的标准基准测试。它包含 89 个任务，涵盖机器学习、调试和生物学等领域。我们使用Harbor来编排运行。它会启动沙箱（Daytona），与我们的智能体循环交互，并运行验证 + 评分。
每个智能体动作都存储在LangSmith中。它还包括延迟、token 数量和成本等指标。
我们可以转动的旋钮
一个智能体 harness 有很多旋钮：系统提示词、工具、钩子/中间件、技能、子智能体委派、记忆系统等等。我们有意压缩优化空间，聚焦于三个：系统提示词、工具，以及中间件（我们对模型和工具调用周围钩子的称呼）。
我们从默认提示词和标准工具 + 中间件开始。使用 GPT-5.2-Codex 得分为 52.8%。这是一个不错的分数，目前刚好在排行榜 Top 30 之外，但仍有增长空间。
追踪分析器技能
我们希望追踪分析可重复，因此将其做成了一个智能体技能（Agent Skill）。这是我们的配方，用于分析各次运行中的错误并对 harness 做出改进。流程是：
- 从 LangSmith 获取实验追踪
- 生成并行的错误分析智能体 → 主智能体综合发现与建议
- 汇总反馈并对 harness 进行有针对性的修改。
这与以下方法类似：提升它聚焦于此前运行中的错误。在步骤 3 中，人类可以发挥很大帮助（尽管并非必需），用于验证并讨论所提议的修改。过度拟合某个任务的修改不利于泛化，并可能导致其他任务出现回归。
自动化 trace 分析节省了数小时的时间，并让快速尝试实验变得轻而易举。我们很快会发布这项技能，目前我们正在针对提示优化对其进行通用性测试。
真正提升智能体性能的因素
自动化 Trace 分析让我们能够调试智能体出错的地方。问题包括推理错误、未遵循任务指令、缺少测试与验证、时间耗尽等。我们将在下文各节中更详细地介绍这些改进。
构建与自我验证
如今的模型是卓越的自我改进机器。
自我验证让智能体能够在一次运行中通过反馈实现自我改进。然而，它们并没有自然倾向于进入这个构建-验证循环。
最常见的失败模式是：智能体写出了一个解决方案，重新阅读自己的代码，确认看起来没问题，然后就停下了。测试是自主智能体编程的关键部分。它有助于检验整体正确性，同时为智能体提供可用来爬坡优化的信号。
我们在系统提示中加入了关于如何着手解决问题的指导。
- 规划与探索：阅读任务，扫描代码库，并基于任务规范以及如何验证解决方案来制定初步计划。
- 构建：在实现计划时始终考虑验证。如果测试不存在，就构建测试，并同时测试正常路径和边界情况。
- 验证：运行测试，阅读完整输出，与任务要求进行对比（而不是与你自己的代码对比）。
- 修复：分析任何错误，重新审视原始规范，并修复问题。
我们非常重视测试，因为它驱动着每一次迭代中的改动。我们发现，除了提示之外，确定性的上下文注入也有助于智能体验证其工作。我们使用一个PreCompletionChecklistMiddleware在智能体退出前拦截它，并提醒它针对 Task spec 运行一次验证流程。这类似于Ralph Wiggum Loop其中 hook 会强制智能体在退出时继续执行，我们用它来进行验证。
为智能体提供关于其环境的上下文
harness 工程的一部分是为上下文工程构建良好的交付机制。Terminal Bench 任务自带目录结构、内置工具和严格的超时限制。
- 目录上下文与工具：一个
LocalContextMiddleware在智能体启动时运行，以映射cwd以及其他父级和子级目录。我们会运行bash命令来查找诸如Python安装之类的工具。上下文发现和搜索容易出错，因此注入上下文可以减少这一错误面，并帮助让智能体熟悉其环境。 - 教智能体编写可测试的代码：智能体不知道它们的代码需要如何可测试。我们添加提示词，说明它们的工作将根据程序化测试来衡量，类似于提交代码时的情况。例如，提到文件路径的 Task spec 应被严格遵循，以便解决方案能在自动评分步骤中正常工作。强调边缘情况的提示词有助于智能体避免只检查“happy path”情况。强制模型符合测试标准是避免随时间推移出现“slop 堆积”的有力策略。
- 时间预算：我们会注入时间预算警告，以推动智能体完成工作并转向验证。智能体在时间估算方面出了名地糟糕，因此这一启发式方法在此环境中很有帮助。现实世界的编程通常没有严格的时间限制，但如果不添加任何关于约束的知识，智能体就不会在时间范围内工作。
智能体对其环境、约束和评估标准了解得越多，它们就越能自主地自我指导其工作。
harness 工程师的宗旨：准备并交付上下文，使智能体能够自主完成工作。
鼓励智能体退后一步并重新考虑计划
智能体一旦确定了计划就可能变得目光短浅，从而导致“doom loop”，即对同一个有问题的方案做微小改动（在某些轨迹中超过 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 整体过程中得出的一些通用原则。
- 代表智能体进行上下文工程。如今，上下文组装对智能体来说仍然很困难，尤其是在未见过的环境中。用目录结构、可用工具、编码最佳实践和问题解决策略等上下文来引导模型，有助于减少糟糕搜索带来的错误面，并避免规划中本可避免的错误。
- 帮助智能体自我验证其工作。模型会偏向于它们第一个看似合理的解决方案。要积极地提示它们通过运行测试和优化解决方案来验证自己的工作。这在没有人类参与循环的自主编码系统中尤为重要。
- 将追踪作为反馈信号。追踪让智能体能够自我评估和自我调试。同时调试工具和推理很重要（例如：模型之所以走上错误路径，是因为它们缺少某个工具或不知道如何做某事的说明）。
- 在短期内检测并修复不良模式。如今的模型并不完美。框架设计者的职责是围绕当下的不足进行设计，同时为未来更聪明的模型做规划。盲目重试和不验证工作就是很好的例子。这些护栏几乎肯定会随时间消解，但要在今天构建稳健的智能体应用，它们是值得试验的有用工具。
- 让框架适配模型。TheCodex和Claude的提示指南表明，模型需要不同的提示方式。用 Claude Opus 4.6 进行的一次测试运行得分
59.6%使用的是较早版本的框架，具有竞争力但比 Codex 差，因为我们没有对 Claude 运行同样的改进循环。许多原则是通用的，比如良好的上下文准备和对验证的关注，但为你的任务运行几轮框架迭代有助于在各类任务中最大化智能体性能。
在框架设计方面还有更多开放研究要做。有趣的方向包括多模型系统（Codex、Gemini 和 Claude 一起）、用于持续学习的记忆原语，使智能体能够自主改进任务，以及衡量框架变更在不同模型间的表现。
对于改进智能体的外层循环，我们正在研究诸如RLMs之类的方法，以更高效地挖掘追踪数据。我们将继续改进框架的工作，并公开分享我们的研究。
我们创建了一个我们的追踪数据集以与社区分享。
Deep Agents 是开源的。Python和Javascript。
为了更多的爬坡和开放研究。