只改 Harness，LangChain 编码 Agent 在 Terminal Bench 2.0 从前30跃升至前5

TLDR：我们的编码 Agent 在 Terminal Bench 2.0 上从前 30 提升到前 5。我们只改了 harness。下面是我们做 harness engineering 的方法（先剧透：self-verification 和 tracing 帮助非常大）。

Harness Engineering 的目标

harness 的目标，是把模型本身“起伏很大”的智能，塑造成我们关心任务上的稳定能力。Harness Engineering 的核心是系统设计：围绕模型搭建工具链，以优化任务表现、Token 效率、延迟等目标。设计决策包括 system prompt、工具选择和执行流程。

但问题是：到底该怎么改 harness，才能让 Agent 变强？

在 LangChain，我们使用 Traces 来规模化理解 Agent 的失败模式。如今的模型大多仍是黑盒，内部机制很难解释；但我们可以看到它们在文本空间中的输入与输出，并据此进入改进闭环。

我们用一套简单流程，迭代优化了 deepagents-cli（我们的编码 Agent），在 Terminal Bench 2.0 上把分数从 52.8 提升到 66.5，即提升 13.7 points。我们只调整 harness，模型始终固定为 gpt-5.2-codex。

实验设置与 Harness 可调“旋钮”

我们使用 Terminal Bench 2.0 这个如今较为标准的 agentic coding 基准。它包含 89 个任务，覆盖 machine learning、debugging、biology 等领域。我们用 Harbor 编排运行流程：拉起 sandbox（Daytona）、与 Agent loop 交互、执行验证与评分。

每一步 Agent 行为都会存到 LangSmith。同时记录延迟、Token 数、成本等指标。

我们能调哪些旋钮

一个 Agent harness 可调项很多：system prompts、tools、hooks/middleware、skills、sub-agent delegation、memory systems 等。我们有意压缩优化空间，只专注三个：System Prompt、Tools 和 Middleware（我们对模型调用与工具调用外围 hooks 的叫法）。

我们从默认 prompt 和标准 tools+middleware 起步。在 GPT-5.2-Codex 上，这一版得分 52.8%。这是个不错的分数，按当时榜单大约略低于前 30，但还有提升空间。

Trace Analyzer Skill

我们希望 trace 分析可复用、可重复，于是把它做成了一个 Agent Skill。它就是我们这套跨运行分析错误并改进 harness的方法配方。流程如下：

1. 从 LangSmith 拉取实验 traces
2. 启动并行错误分析 agents → 主 agent 汇总发现与建议
3. 聚合反馈，对 harness 做定向修改。

这和 boosting 类似，聚焦前几轮运行里的错误。第 3 步里有人参与会很有帮助（但不是必须），用于核验并讨论改动建议。若改动对某些任务过拟合，会损害泛化并导致其他任务回归。

自动化 trace 分析能节省大量时间，也让快速做实验变得容易。我们会很快发布这个 skill，目前在把它用于更通用的 prompt 优化测试。

到底哪些改动真正提升了 Agent 性能

自动化 trace 分析让我们能够定位 Agent 具体错在哪。问题包括推理错误、不遵循任务说明、遗漏测试与验证、超时等。下面分项展开。

Build & Self-Verify

当前模型在“自我改进”方面已经非常强。

Self-verification 能让 Agent 在单次运行内通过反馈自我提升。但模型并不会自然进入这种 build-verify loop。

最常见的失败模式是：Agent 写完方案后，重新看一遍自己代码，确认“看起来没问题”，然后就结束。测试是 autonomous agentic coding 的关键环节：它既验证整体正确性，也给 Agent 提供持续爬坡（hill-climb）的信号。

我们在 system prompt 里加入了问题求解流程指引：

1. Planning & Discovery： 阅读任务、扫描代码库，并基于任务规范和验证方式建立初始计划。
2. Build： 围绕“可验证”来实现计划。若无测试则补测试，并覆盖 happy path 与 edge cases。
3. Verify： 运行测试，完整阅读输出，对照任务要求（而不是对照自己写的代码）。
4. Fix： 分析错误，回看原始规范，修复问题。

我们特别强调测试，因为每轮迭代改进几乎都靠它驱动。我们发现，除了 prompting，确定性的上下文注入也能帮助 Agent 做好验证。我们使用 PreCompletionChecklistMiddleware，在 Agent 即将退出时拦截并提醒它按任务规范执行一次验证。这类似 Ralph Wiggum Loop：通过 hook 强制 Agent 在退出点继续执行，我们把它用于验证。

给 Agent 注入环境上下文

harness engineering 的一部分，是建立可靠的上下文传递机制（context engineering）。Terminal Bench 任务自带目录结构、内置工具和严格超时。

1. 目录上下文与工具发现： 在 Agent 启动时，LocalContextMiddleware 会映射 cwd 及父/子目录结构。我们还会运行 bash 命令查找例如 Python 安装等工具。上下文发现与搜索本身易出错，因此主动注入上下文能降低这类错误面，并帮助 Agent 更快进入环境状态。
2. 教 Agent 写可测试代码： Agent 并不知道“代码需要怎样才算可测”。我们在 prompt 中明确其结果会被 programatic tests 评估，类似提交代码时的标准。比如任务规范里提到文件路径，就必须严格遵守，才能通过自动评分步骤。强调 edge-cases 的 prompt 能避免 Agent 只检查“happy path”。让模型遵循测试标准，是防止长期“slop buildup”的有效策略。
3. 时间预算管理： 我们注入 time budget 警告，推动 Agent 收敛工作并切换到验证。Agent 在时间估计上普遍较弱，这个启发式在该环境下很有帮助。真实开发通常没这么硬的时限，但如果不显式注入约束知识，Agent 就很难在限时内完成任务。

Agent 越了解环境、约束与评估标准，就越能自主地把工作导向正确方向。

harness engineer 的职责，就是准备并传递上下文，让 Agent 能自主完成工作。

鼓励 Agent 停下来复盘计划

Agent 一旦选定计划，常会变得短视，导致“doom loops”：在同一路径上反复小修小改（某些 traces 中出现 10+ 次）。

我们使用 LoopDetectionMiddleware，通过 tool call hooks 跟踪每个文件的编辑次数。当同一文件编辑达到 N 次后，它会注入类似“……请考虑重新审视当前方案”的上下文。这有助于 Agent 从 doom loop 中恢复；当然，如果模型仍确信当前路径正确，也可能继续走下去。

重要说明：这是一种针对当前模型问题的工程性启发。随着模型能力提升，这类护栏可能不再需要；但在当下，它确实能帮助 Agent 更正确、更自主地执行。

如何分配推理算力（compute）

Reasoning 模型可以自主运行数小时，因此我们必须决定每个子任务投入多少推理算力。你可以给每个任务都开最大预算，但多数工作更适合优化推理开销。

Terminal Bench 的超时限制带来权衡：更多推理能让 Agent 更好评估步骤，但可能消耗超过 2x 的 Token/时间。gpt-5.2-codex 有 4 种推理模式：low、medium、high、xhigh。

我们发现，任务初期规划阶段更高推理很有价值，因为部分 Terminal Bench 任务确实很难。计划质量高，往往更快到达可用解。

后期验证阶段同样受益于更高推理，有助于抓错并完成提交。基于经验，我们把 xhigh-high-xhigh 的“reasoning sandwich”作为基线。

在规划与验证阶段投入更多推理算力

全程只用 xhigh 的得分是 53.9%，主要因超时表现不佳；而全程 high 可达 63.6%。不同推理预算切分在试验中的差异不算巨大，因此我们保留上述策略，最终把分数推到 66.5%。

模型的自然方向是 Adaptive Reasoning：如 Claude 与 Gemini 所示，由模型自行决定推理算力开销。

在多模型 harness 中，推理预算平衡可能体现为：先用大模型做规划，再handoff 给小模型做实现。

构建 Agent Harness 的实践要点

Agent 设计空间很大。以下是我们实验和 deepagents 实践中的通用原则：

1. 站在 Agent 角度做 Context Engineering。 对今天的 Agent 来说，组装上下文仍然困难，尤其在陌生环境。用目录结构、可用工具、编码最佳实践、问题求解策略等上下文来“onboard”模型，能减少搜索失误和可避免的规划错误。
2. 帮助 Agent 自我验证。 模型倾向于停在第一个“看似合理”的解。要强力提示它运行测试并迭代改进。对没有人类在环的 autonomous coding system，这一点尤其关键。
3. 把 Tracing 当作反馈信号。 Traces 让 Agent 能自评与自调试。工具链与推理要一起排查（例如：模型走错路，可能是缺工具，也可能是缺指令）。
4. 短期内识别并修复坏模式。 现在的模型还不完美。harness 设计者的工作，是在面向未来更强模型的同时，先绕开当前短板。盲目重试、不做验证都是典型问题。这些护栏未来大概率会淡出，但在今天构建稳健 Agent 应用时仍非常实用。
5. 为不同模型定制 Harness。 Codex 与 Claude 的 prompting 指南都说明，不同模型需要不同提示策略。我们用较早版本 harness 跑 Claude Opus 4.6 得到 59.6%，有竞争力但弱于 Codex，因为我们没有对 Claude 做同样的改进循环。很多原则可泛化（如高质量上下文准备、重视验证），但要想在任务间最大化性能，仍建议针对具体任务做几轮 harness 迭代。

harness 设计仍有很多开放研究问题。值得探索的方向包括：多模型系统（Codex、Gemini、Claude 协同）、支持持续学习的 memory primitives（让 Agent 在任务中自主提升）、以及跨模型评估 harness 改动效果。

在 Agent 外环改进方面，我们也在关注 RLMs 等方法，以更高效地挖掘 traces。我们会继续优化 harness，并公开分享研究进展。

我们还创建了Trace 数据集，向社区开放。

Deep Agents 已开源：Python 和 Javascript。

继续 hill climbing，继续开放研究。