面向长时运行 Agent 的有效 Harness
官方原文: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
发布日期： 2025 年 11 月 26 日
作者： Justin Young
当 Agent 必须跨越多个 Context Window 连续工作时，如何让它稳定推进仍是一项难题。Anthropic 从人类工程团队的协作方式中得到启发，为长时运行 Agent 设计了一套更可靠的 Harness。
随着 AI Agent 的能力提升，开发者开始把需要数小时甚至数天才能完成的复杂任务交给它们。但要让 Agent 跨多个 Context Window 持续、稳定地完成工作，至今仍未有彻底的通用解法。
根本原因在于，Agent 以一次次相互独立的 Session 工作；每次新 Session 开始时，它都不知道之前发生过什么。这很像一个软件项目由轮班工程师接力开发，而每位接班者对上一班的工作毫无了解。Context Window 有限，而多数复杂项目无法在一个窗口内完成，因此必须建立机制，衔接相邻的开发 Session。
解决方案
Anthropic 围绕 Claude Agent SDK 设计了两类 Agent：首次运行时负责搭建基础环境的 initializer agent，以及每个 Session 都只推进一小步、并为下一次 Session 留下清晰工作痕迹的 coding agent。相关代码示例见配套快速入门。
长时运行 Agent 面临的问题
Claude Agent SDK 是一套面向编码任务的通用 Agent Harness，并提供 compaction 等上下文管理能力。从理论上说，这些能力应让 Agent 可以在很长时间内持续产出。
但只依靠 compaction 还不够。即使让 Opus 4.5 基于 Claude Agent SDK 跨多个 Context Window 循环执行，仅凭一条高层需求也难以完成一个达到生产质量的 Web 应用。
研究中，Claude 的失败主要呈现为两种模式：
- 一次铺得太开。 它试图一口气把整个应用做完，常常在实现中途耗尽上下文，下一次 Session 只能猜测前一次做到哪里。
- 过早宣布完成。 做出一部分功能后，新的 Agent 实例看到项目已有进展，便误以为任务已经结束。
因此，解决思路分为两部分：先准备一个覆盖所有必需功能的初始环境；再要求每次执行只做增量推进，并在结束时让项目保持可继续工作的状态，即没有重大 Bug，代码结构清晰、文档完整。
环境管理
功能清单
initializer agent 会根据用户的初始需求，编写一份完整的功能需求清单。以 claude.ai 克隆项目为例，清单包含 200 多项功能，例如“用户可以新建聊天、输入问题、按下回车，并看到 AI 回复”。所有条目一开始都标记为未通过，使后续 coding agent 对“完整可用”有明确的共同定义。
每项功能以 JSON 表示，包含 category、description、steps 以及布尔字段 passes。示例条目描述“新建聊天按钮会创建一段全新的对话”，并列出验证步骤，初始状态为 passes: false。
coding agent 只能通过修改 passes 的状态来更新该文件，提示词明确禁止删除或改写测试内容。选择 JSON 而非 Markdown，是因为模型更不容易不恰当地修改或覆盖 JSON 文件。
增量推进
coding agent 被要求一次只处理一个功能。这种增量式工作方式是解决“一次做太多”倾向的关键。模型还需要以描述清楚的提交信息提交 Git 变更，并在进度文件中记录摘要。这样既能回滚有问题的改动，也能让后续 Session 快速恢复到可工作的状态。
测试
另一个常见失败模式是，Claude 没有充分测试就把功能标为完成。它可能改完代码后跑了单元测试或 curl，却没有发现功能在真实端到端流程中并不能正常工作。
在构建 Web 应用时，只要明确要求它使用浏览器自动化工具、像真实用户一样验证功能，Claude 的端到端测试表现会明显提升。文中展示了 Claude 通过 Puppeteer MCP server 测试 claude.ai 克隆项目时截取的页面截图。
提供合适的测试工具能显著改善结果，但仍有边界。例如 Claude 的视觉能力和浏览器自动化工具本身都有局限；通过 Puppeteer MCP，它看不到浏览器原生的 alert 对话框。
快速进入状态
每个 coding agent 开始工作时，都应依次完成以下步骤：
- 运行
pwd，确认当前工作目录。 - 阅读 Git log 与进度文件，了解最近的改动。
- 阅读功能清单，选择优先级最高、尚未完成的一项功能。
initializer agent 会提供用于启动开发服务器的 init.sh。coding agent 在开始实现新功能前，先执行一次基础端到端测试。这样它能尽早识别项目是否已损坏，避免在错误状态上继续叠加改动。
一个典型 Session 会先完成定位和交接：读取进度文件、功能清单与 Git log，启动开发服务器，确认基础功能仍然可用，再开始实现下一项功能。
Agent 失败模式与应对方式
| 问题 | initializer agent 的职责 | coding agent 的职责 |
|---|---|---|
| Claude 过早宣布任务完成 | 建立结构化 JSON 功能清单 | Session 开始时阅读清单，并只选择一项功能 |
| Claude 留下有 Bug 或缺乏文档的环境 | 初始化 Git 仓库和进度记录文件 | 开始时阅读进度记录和 Git log，执行基础测试；结束时提交并更新记录 |
| Claude 过早将功能标为已完成 | 建立功能清单 | 自行验证全部验收步骤；仅在充分测试后标记为通过 |
| Claude 花时间摸索如何启动应用 | 编写 init.sh | Session 开始时先阅读并运行 init.sh |
后续研究方向
这项研究展示了一套可行的长时运行 Agent Harness 方案，仍有一些问题有待验证：
- 跨多个 Context 时，是单个通用 coding agent 效果最好，还是由测试、QA、代码清理等角色组成的 multi-agent architecture 更有效？
- 如何把这些发现从全栈 Web 应用开发推广到科学研究、金融建模等其他领域？
致谢
本文由 Justin Young 撰写，特别感谢 David Hershey、Prithvi Rajasakeran、Jeremy Hadfield、Naia Bouscal、Michael Tingley、Jesse Mu、Jake Eaton、Marius Buleandara、Maggie Vo、Pedram Navid、Nadine Yasser 与 Alex Notov。该工作凝聚了 Anthropic 多个团队的共同投入，尤其包括 code RL 与 Claude Code 团队。
脚注
- 文中将两类 Agent 分开称呼，仅仅是因为它们接收的初始用户提示不同；两者的 system prompt、工具以及整体 Agent Harness 其余部分完全相同。