Effective harnesses for long-running agents

随着 AI 智能体能力的提升，开发者越来越多地要求他们承担需要数小时甚至数天工作的复杂任务。然而，让智能体在多个上下文窗口中保持一致进展仍是一个悬而未决的问题。其中：核心挑战是智能体必须在离散的会话中工作，而每次新会话开始时都不记得之前发生的事情。

长时间运行的智能体（long‑running agent）指的是可以在长时间跨度（从几十分钟到数天、跨多轮会话等）内，围绕同一任务持续推进、在中途多次中断后依然能「接得上」前文、最终完成复杂目标的系统，而不仅是单轮对话或短暂工具调用。

典型场景包括：

• 大型软件开发与重构（数百次提交、跨多日）

• 文献综述/调研（Deep Research 几十到上百篇论文）

• 复杂业务流程自动化（跨多个系统、多阶段审批）

长时间运行（long‑running agent）本质上包括三类场景：

1. 跨上下文窗口的长任务

   1. 任务本身需要多轮推理、多次工具调用、甚至跨天/周执行。

   2. 模型单次上下文有限，不能一次性装下所有历史。

2. 跨会话的持续任务

   1. Agent 多次被“重新启动”（进程重开、服务重启、会话中断）。

   2. 但任务要求它能“接着上次继续干”，而不是从零开始。

3. 跨场景与跨用户生命周期的记忆

   1. 以用户为中心的长期交互（如个人助手、长期科研智能体、长期项目开发智能体）。

   2. 要记住关键事实、偏好、和长期项目结构。

因此，长时间运行机制不是简单的给模型加长上下文，而是要把智能体视为一个具有可重入状态、可治理的记忆结构、清晰的任务分解与进度管理的面向长期任务的工程闭环，而不只是带工具的单轮LLM 调用。

---

The long-running agent problem 长时间运行智能体的问题

        Claude是一款强大的通用智能体工具，擅长编码以及其他需要模型使用工具收集上下文、规划和执行的任务。它具备上下文管理功能，如上下文压缩/compaction，使智能体能够在不耗尽上下文窗口的情况下完成任务。理论上，在这种设置下，一个智能体应该可以持续进行有用的工作一段时间任意长的时间。但是实际上仅有上下文压缩远远不够。

典型失败模式

Anthropic 在做长时间运行 Agent 的过程中，总结了几个 Agent 常见的失败模式：

1. 失败模式 1：试图一步到位（One-shotting）。

   1. Agent 倾向于一次性做太多事情，这常常导致模型在实现过程中耗尽上下文，使下一个会话只能从一个半成品且未文档化的功能开始。

   2. 下一个会话启动时看到的是半成品、没有文档的代码，只能花大量时间猜测之前发生了什么，并试图恢复工作状态。

   3. 结果：中途上下文爆掉，下一个会话接不上，项目陷入失败。

2. 失败模式 2：过早宣布任务完成。第二种失败模式通常出现在项目后期。在某些功能已经建立后，后续的智能体实例看到已有进展，便误判任务已经完成，从而放弃剩余特性，导致项目整体的失败。

3. 失败模式 3：过早标记功能完成。在没有明确提示的情况下，Agent 写完代码就标记为“passing”，却没有做端到端测试。单元测试或 curl 命令通过了不代表功能真正可用。

4. 失败模式 4：环境启动困难。

   1. 每次新会话启动时，Agent 需要花费大量 token 弄清楚如何运行应用、如何启动开发服务器，而不是把时间花在实际开发上。

   2. 即便做了记录 /摘要 /compaction，如果缺少结构化环境和进度管理，Agent 仍然会迷路而发生第一个模式下一个会话启动失败的情况。因为压缩并不能总是将清晰的指令完美传递给下一个智能体。

除此之外，还有三种额外的失败模式，随着长期任务的进行会加剧：

1. 上下文内容过多Context rot：上下文窗口会显示工具输出、历史和先前推理。随着填充，模型失去了对原始说明的思考。即使有 20 万+个窗口，密集的中间上下文内容也会被忽略 。

2. 工具调用幻觉：没有验证，智能体会调用参数类型错误的函数或引用不存在的API。如果没有拦截器拦截调用，智能体会消耗token重试同一个无法使用的工具调用。

3. 失败时失去状态：任何网络超时或服务器重启都会清除内存进度。下一次直接从零开始。

例如：上下文窗口的有效区间

Dex Horthy 有个很实用的经验观察：上下文填得越满，LLM输出质量越差。以 168K token 的上下文窗口为例，大约用到 40% 就开始走下坡路了：

• Smart Zone（前约 40%）：聚焦、准确的推理。Agent 拥有相关、精炼的信息。

• Dumb Zone（超过约 40%）：幻觉、循环、格式错误的工具调用、低质量代码。更多 token 反而损害性能。

给Agent塞大量MCP工具、冗长文档和累积的对话历史，不会让它聪明，反而会变笨

出现“You’re absolutely right” 是一个不好的迹象

===>

这提示 Anthropic 需要：

1. 设置一个初始环境，为给定提示所要求的所有功能奠定基础，从而让智能体能够逐步、按功能分步工作。

2. 提示每个智能体在朝着目标前进的同时，以干净状态结束会话，即适合合并到主分支的代码：没有重大错误，代码有序且文档齐全，总体而言，开发者可以轻松开始新功能，而无需先清理无关的混乱。

===>

引出一个更大的话题：Harness Engineering

---

Harness Engineering 智能体的驾驭工程

Harness本意是马具——缰绳、鞍具那一套东西，把马的力气引到正确方向上。拿来类比 AI Agent 即：LLM 就像一匹蛮力十足但方向感不太行的马，跑得快但容易跑偏，因此使用马鞍进行方向的确认和稳定。

• 马是 AI 模型——强大、快速，但它不知道自己该往哪走

• 马具 Harness是基础设施——约束、护栏、反馈回路，它们将模型的力量转化为生产力

• 骑手是人类工程师——提供方向，而不是亲自奔跑

【What】什么是 Harness Engineering？

Harness Engineering 是一套围绕 AI Agent 构建的约束、反馈与控制系统，让 Agent 在人类设定的边界内自主、可靠、可持续地工作——它不优化模型本身，而是优化模型运行的"环境"。

Harness Engineering（可译为架构工程或驾驭工程）是一门为AI智能体（特别是 Coding Agent）构建可靠运行时环境的系统工程学科。是围绕 AI 模型的软件基础设施，负责管理除模型实际推理外的所有内容。

  其中：

• Harness 是指除模型本身外所有的代码、配置和执行逻辑。通过搭建约束机制、辅助工具、反馈回路、持续改进流程等，Harness优化了模型在执行特定任务时的性能、Token效率和延迟的工作。

• Harness 的核心目标是将模型本身具有波动性的智能塑造成能够稳定处理特定任务的能力，确保其输出的可靠性、一致性和长期可维护性。

• Harness 作为大型语言模型与外部世界之间的中介，负责工具执行、内存存储、状态持久性和错误恢复。通过在多个会话间保持上下文，将一个简单的文本生成器转变为一个功能强大且运行时间长的智能体。

有人说：在智能体系统中，Model负责智能推理，Harness控制流与状态管理的编排层，负责状态管理、工具调用、执行环境、记忆与上下文管理。 通过系统化Harness工程，模型能力被放大，最终形成真正可以持续工作的智能体系统。并且总结了下面的公式：

智能体的核心公式如下：

这个公式也体现了Harness工程在智能体系统中的重要性。“如果你不是模型，你就是Harness”

Harness 是指除模型本身外所有的代码、配置和执行逻辑，人们描述为：

1. LangChain 创始人Viv Trivedy指出：“Harness Engineering 就是如何围绕模型构建系统，使其智能成为有用的工作引擎”。

2. HumanLayer 团队认为它是利用各种“配置点”（系统提示、工具、子智能体等）来提高编码Agent输出质量和可靠性的工程实践。

3. Mitchell Hashimoto 描述为“每次发现智能体犯错时，就工程化地修复环境，让智能体不再重复该错误”。

4. 菲利普·施密德（Philipp Schmid）通过将其与计算机进行比较来可视化：

   

   1. 模型就是 CPU：提供原始的处理能力。

   2. 上下文窗口是内存：是有限且易变的工作记忆。

   3. 驾驭工程是操作系统：管理上下文、初始化序列和标准工具驱动程序。

   4. 智能体是应用程序：运行在操作系统顶部的特定用户逻辑。

【四大核心架构】

Harness工程 的过程如下：

Harness 工程是设计和实施以下系统的过程：

1. 约束（Constrain）：AI 智能体可以执行的操作（架构边界、依赖规则）

2. 告知（Inform）：智能体应该做什么（上下文工程、内存与状态管理、文档）

3. 验证（Verify）：智能体是否正确完成了任务（测试、集成校验）

4. 纠正（Correct）：当智能体出错时进行修复（反馈回路、自修复机制）

对于智能体框架设计，有三种常见的架构模式：

1. 单智能体架构。一个包含工具、内存和验证的循环模型。框架管理初始化、上下文注入、工具调度、状态持久化和清理。适用于有知识库和工单系统的有限任务，如客服智能体。

2. 双智能体(初始化智能体-执行智能体)。Anthropic针对长编码任务记录的方法。初始化器运行一次并设置持久化项目环境：文件夹结构、功能列表、init.sh、初始git提交。每个执行器会话从该环境读取，在一个功能上逐步推进，运行测试、提交、更新进度文件并干净退出。项目环境是所有会话共享的内存。

3. 多智能体系统。对于复杂项目，框架调度专业智能体（研究员、写手、审阅者），管理交接，确保每个智能体从上一步获取相关上下文而不包含无关历史。ICML 2025论文《General Modular Harness for LLM Agents in Multi-Turn Gaming Environments》使用可分离感知、记忆和推理模块在GPT-4级模型上测试了此方法。被框架封装的模型在所有测试游戏中始终优于未使用框架的相同模型。

        论文研究发现，在同一底层模型上对比启用harness和禁用harness，且模型权重和提示无变化的情况下，可以显著提升模型在复杂多回合任务（2048、糖果消除、俄罗斯方块）中的性能。即使对于本身具备强大推理能力的模型也有增益效果，且不同游戏的Harness敏感度不同。

支柱一：上下文架构（Context Architecture）

核心原则：Agent 应当恰好获得当前任务所需的上下文——不多不少。

每个团队都独立发现，将所有指令塞进一个文件无法扩展。解决方案是分层上下文与渐进式披露：

• OpenAI使用 AGENTS.md 作为动态反馈循环文件，每当 Agent 遇到失败时更新。

• Anthropic使用大量 README 和每次会话频繁更新的进度文件。

• Horthy倡导"频繁有意识压缩"（Frequent Intentional Compaction）。

支柱二：Agent 专业化（Agent Specialization）

核心原则：专注于特定领域、拥有受限工具的 Agent 优于拥有全部权限的通用 Agent。

• Anthropic 的编译器项目将 Agent 专业化为编译器核心、去重、性能优化和文档四类角色。

• Vasilopoulos部署了 19 个领域特定 Agent。

• Huntley使用子 Agent 来保持 主Agent 上下文的清洁。

支柱三：持久化记忆（Persistent Memory）

核心原则：进度持久化在文件系统上，而非上下文窗口中。每次新 Agent 会话通过文件系统重建上下文。

细节可以查看下文的Anthropic的实践工程——双智能体结构【初始化Agent + 编码Agent】。

支柱四：结构化执行（Structured Execution）

核心原则：将思考与执行分离。研究和规划在受控阶段进行，执行基于验证过的计划，验证通过自动化反馈（测试、Linter、CI）和人类审查完成。

所有团队都施加了刻意的执行序列：理解 → 规划 → 执行 → 验证。

• OpenAI使用声明式 prompt 和反馈回路。轻量的计划用于小变更，复杂工作通过带有进度和决策日志的执行计划完成，并检入仓库。

• Huntley将规划模式与构建模式分离。

• Horthy的 Research-Plan-Implement 工作流围绕上下文管理精心设计。

当然，也没有什么标准划分，也有人划分为下面六个架构：

Harness六维度划分

工具集成层

• 通过定义的协议将模型连接到外部 API、数据库、代码执行环境和自定义工具。

记忆与状态管理

• 多层记忆（工作上下文、会话状态、长期记忆），其持久性超越单个上下文窗口。
• Anthropic 的方法使用进度文件和 git 历史来连接不同的会话。

上下文工程与提示词管理

• 动态地管理每次模型调用中出现的信息。
• 它不是静态的提示词模板，而是基于当前任务状态的主动上下文选择。

规划与分解

• 引导模型通过结构化的任务序列，而不是试图一次性完成所有事情。

验证与护栏

• 验证检查、格式验证、安全过滤器，即自我修正的循环。当智能体遇到困难时，驾驭将此视为一个信号，用以识别缺失的环节。

模块化与可扩展性

• 可插拔的组件，可以独立地启用、禁用或替换。

---

【五大核心组件】

综合 OpenAI、Anthropic、LangChain 和 Martin Fowler 网站四方的实践，Harness 的核心组件可以归纳为五层。下面逐个拆解。

组件一：结构化知识系统

AI Agent 要在百万行代码库里干活，它得知道整体架构、各模块职责、API 约定、设计决策的背景。怎么给？

最天真的做法是写一个巨大的 AGENTS.md，把所有信息塞进去。

OpenAI 踩过这个坑，发现行不通。两个原因：

1. 第一，上下文窗口是稀缺资源，全塞进去关键信息反而被淹没；

2. 第二，大而全的文档腐烂得最快——代码改了文档没跟上，过时信息比没有信息更危险。

正确做法是渐进式披露——把 AGENTS.md 当地图，不当百科全书：

repo/
├── AGENTS.md          ← 目录/地图，指向下面的详细文档
├── docs/
│   ├── architecture/  ← 整体架构设计
│   ├── domains/       ← 各业务域的详细文档
│   ├── plans/         ← 执行计划（版本控制的一等工件）
│   ├── specs/         ← 产品规格
│   └── runbooks/      ← 操作手册

Agent 从地图出发，根据当前任务按需深入。就像去一个陌生城市——不是把整个城市的历史读一遍，而是先看地图搞清楚方向，走到具体地方再看详细介绍。

更关键的一步：OpenAI 建了一个 “doc-gardening Agent”——后台运行的 AI，唯一工作就是扫描文档和代码之间的不一致，自动提交 PR 修复过时文档。Martin Fowler 网站的文章把这类 Agent 叫"垃圾回收 Agent"——不做新功能只做清理，但没有它，整个系统的信息质量会不可逆地腐烂。【手动进行熵减的操作】

组件二：机械化架构约束

这是整个 Harness 中最反直觉但最有效的部分。

传统开发中，架构规范靠人维护——资深工程师在 Code Review 时指出"这个模块不应该直接调用那个模块"。但 Agent 一天几百个 PR 的吞吐量下，人工审查成了瓶颈。

OpenAI 的解法：把所有架构规则变成自定义 Linter（代码检查工具），机械化强制执行。

他们的层级依赖模型如下：

Types → Config → Repo → Service → Runtime → UI 
基础类型层 → 配置层 → 数据层 → 服务层 → 运行时层 → 界面层

每个业务域按这个层级组织，下层不能反向依赖上层。这条规则不是写在文档里靠人记的，是写成 Linter 规则——任何违反的代码都过不了 CI，无论人写的还是 AI 写的。

Linter 错误信息本身也是上下文工程的一部分。OpenAI 把自定义 Lint 错误写得很详细，不只说"你违反了规则 X"，而是解释"为什么这个规则存在、正确的做法是什么"。这样 Agent 遇到 Lint 错误时能自己理解为什么错了并自我修正，不需要人类介入。

Birgitta Böckeler提出：“为了获得更高的 AI 自主性，运行时必须受到更严格的约束。增加信任需要的不是更多自由，而是更多限制”。即：越想让 AI 自由干活，就越要把规矩定死。 就像高速公路上的护栏——正是因为有护栏，我们才敢踩到 120 码。

组件三：可观测性与验证

AI 写完代码，怎么知道对不对？

最原始做法是跑测试。但测试只覆盖我们预想到的场景。

OpenAI 的做法激进得多：让 Codex 直接接入应用的运行时环境。

具体操作：

• 通过 git worktree 启动独立应用实例

• 接入 Chrome DevTools Protocol，Agent 能像人一样在浏览器里操作应用、看到 UI 实际渲染

• 直接用 LogQL 和 PromQL 查询日志和监控指标

• Agent 可执行"确保服务启动在 800ms 内完成"这样的具体可量化验证任务

Anthropic 走了类似路线，但更强调截图验证——要求 Agent 用 Puppeteer 像真实用户一样操作应用然后截图对比预期。他们发现这招"显著提高了性能，使 Agent 能够识别并修复仅从代码中看不出的 Bug"。

这里有个深刻的认知转变：传统软件工程中，观测是给人看的（仪表盘、报警）；Harness Engineering 中，观测是给 AI 看的。 日志、指标、UI 状态都要设计成"机器可读"的格式。

组件四：自修复闭环【熵管理与"垃圾回收机制"】

任何大型代码库都有个天敌：熵增。代码越多，模式越分裂，技术债务越堆积。

Agent 大量生成代码时这个问题会放大数倍。AI 会复现代码库中已有的坏模式——如果某处有一段写得烂的代码，Agent 在相邻模块工作时可能模仿这种写法，导致坏模式扩散。

OpenAI 的解法是把清理也变成自动化 Agent 任务：

1. 后台定期运行"垃圾回收 Agent"

2. 扫描代码库中偏离"黄金标准"的地方

3. 清理冗余或低质量代码，并自动提交重构 PR

4. CI 验证通过后自动合并

这就是代码库的"垃圾回收机制"——不等技术债务堆到崩溃才还，而是小额、高频、持续地偿还。前面提到的 doc-gardening Agent 也是自修复闭环的一部分——代码变了，文档自动跟着变。

组件五：Agent 互审机制

传统流程里每个 PR 需要人审。但系统一天几百个 PR 时，人工审查是严重瓶颈。

OpenAI 引入了 AI Reviewer——专门负责 Code Review 的 Agent。Agent A 写代码，Agent B 审代码，有问题 Agent A 改完再提交，直到 Agent B 通过。内部叫这个 “Ralph Wiggum 循环”。

人类的角色缩减到只介入架构层面的重大决策。 日常代码风格、逻辑正确性、测试覆盖这些，全部 Agent 互审。

---

【三层工程】与 Prompt / Context Engineering 的区别与联系

Phil Schmid有个绝妙的比喻：模型是CPU，上下文窗口是内存，Harness就是操作系统。

每个人对这段关系的看法都有些不同：另一个观点认为，上下文工程帮助模型更好地思考，而驾驭工程则防止整个系统偏离轨道，后者是前者的一个子集。

实际上重要的不是框架本身，而是认识到仅靠上下文工程无法解决的问题。

可以把三者理解成递进关系：

• Prompt Engineering（提示词工程）【通过优化提示句和规则来引导模型】：优化单次交互。

• Context Engineering（上下文工程）【通过管理上下文窗口的信息丰富输入】：优化当前任务的输入组织。

• Harness Engineering（驾驭工程）【通过设计运行流程、监测机制和验证闭环，让Agent在复杂任务中能持续稳定地工作】：负责整个系统的长期稳定性、质量和治理。

类比理解：

• Prompt = 给马输入"向右转"的命令

• Context = 同时输入帮助马理解方向的地图、路标、地形

• Harness = 包含缰绳、马鞍、围栏和道路的整体设计，让十匹马能同时安全奔跑

Harness工程的核心理念是让Agent在执行任务时一做就对，通过体系化的环境和工具链不断修复错误并自动化测试，以提高AI开发的生产力和可靠性。

• 与Prompt Engineering相比，Harness工程的关注点更广泛：Prompt工程重点在于优化单次交互的提示文本，而Harness工程关注整个系统级的上下文和执行流程。

• 与Context Engineering相比，Harness工程并非仅提供外部知识给模型，而是同时额外覆盖：架构约束、确定性验证、熵治理、安全护栏、生命周期管理等”模型看不到”的系统层面。

维度	Prompt Engineering	Context Engineering	Harness Engineering
核心问题	说什么？（How to ask）	让模型看到什么？（What it sees）	在什么环境里做事？（Where）
主要对象	单次 / 少量交互	模型输入上下文（知识、历史、工具结果）	整个 Agent 运行时系统（工具、约束、反馈、生命周期）
典型产物	精心设计的 prompt / system prompt	CLAUDE.md、Rules、Skills、MCP 资源、代码结构化文档	AGENTS.md 栈、工具与沙箱、架构约束、测试 & CI、熵管理 Agent、观测与评估体系
时间跨度	单次调用	一次会话 / 一次任务	长期演化，贯穿产品全生命周期
成功度量	单次响应质量	若干任务成功率、稳定性	端到端交付能力、长期可维护性、技术债/熵水平

这三个概念之所以会依次出现，是因为人们使用人工智能的方式发生了变化。

1. 在提示工程阶段，交互通常主要是通过 ChatGPT 等工具完成的一次性模式。赋予模型角色，将工作拆分步骤，并添加示例，往往足以提升结果。

2. 这种情况在 2025 年年中左右发生了变化。人们发现光靠 Prompt 不够——AI 需要看到相关文档、代码片段、历史对话、工具调用结果才能给出好答案。 上下文工程开始吸引更广泛的关注。关键思想是，仅仅表达提示词是不够的；模型在推理时可用的完整上下文必须在系统层面设计。

3. 但一旦人工智能智能体真正进入生产环境，就显现出仅靠上下文设计无法涵盖一切。当智能体在多个步骤中自主行动时，会出现另一类问题。智能体可能无视团队约定，生成违反架构依赖方向的代码，在并行执行中自我碰撞，或逐渐降低代码质量。这些问题不是“模型应该看到什么？”的问题。它们是“系统应该阻挡、测量和修复什么？”的问题。这时，驾驭工程也就出现了。

相关链接：

1. Anthropic — Effective harnesses for long-running agents

2. OpenAI — Harness engineering: leveraging Codex in an agent-first world

3. Anthropic — Demystifying evals for AI agents

4. LangChain — Improving Deep Agents with harness engineering

5. LangChain — The Anatomy of an Agent Harness

6. https://zhuanlan.zhihu.com/p/1993995295214814861：Claude的提示词工程最佳实践

7. https://zhuanlan.zhihu.com/p/1978858922615015372：有效支持长期运行智能体的机制