Skip to content

面向长时运行 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 的失败主要呈现为两种模式:

  1. 一次铺得太开。 它试图一口气把整个应用做完,常常在实现中途耗尽上下文,下一次 Session 只能猜测前一次做到哪里。
  2. 过早宣布完成。 做出一部分功能后,新的 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 开始工作时,都应依次完成以下步骤:

  1. 运行 pwd,确认当前工作目录。
  2. 阅读 Git log 与进度文件,了解最近的改动。
  3. 阅读功能清单,选择优先级最高、尚未完成的一项功能。

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.shSession 开始时先阅读并运行 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 团队。

脚注 ​

  1. 文中将两类 Agent 分开称呼,仅仅是因为它们接收的初始用户提示不同;两者的 system prompt、工具以及整体 Agent Harness 其余部分完全相同。
AI 落地咨询
艾维禾砺数字科技

企业 AI 落地全链路服务

Agent 开发工作流搭建Claude Code 集成
微信咨询
d187l8801b6124
访问官网 ivheli.com