面向长时间运行智能体的有效框架

Effective harnesses for long-running agents

Anthropic · 2025-11-26 · Anthropic Engineering ↗

打开互动全文版(逐段中英对照 + 针对本篇提问)→

摘要 · Abstract

长时间运行的 AI 智能体面临一个根本性障碍:它们以离散会话方式工作,每个新的上下文窗口开始时都不记得先前的工作。本文介绍了一个基于 Claude Agent SDK 构建的两部分框架来解决该问题:初始化智能体在首次运行时搭建环境,编码智能体则在之后的每个会话中取得增量进展,同时为下一个会话留下清晰的产物。作者识别出四种常见失败模式,包括试图一次性构建整个应用、过早宣称项目完成、使环境带有缺陷或缺乏文档,以及在未做端到端测试的情况下将功能标记为完成。他们的解决方案包括结构化的 JSON 功能清单、结合 git 历史的进度笔记文件、用于运行和测试应用的 init.sh 脚本,以及显式的基于浏览器的验证。结论是,提示智能体一次只处理一个功能,并在每个会话结束时保持干净、已提交的状态,可以在多个上下文窗口中实现一致的进展,但在多智能体架构以及推广到 Web 开发之外等方面仍存在未解问题。

Long-running AI agents face a fundamental obstacle: they work in discrete sessions, and each new context window begins without memory of prior work. This article describes a two-part harness built on the Claude Agent SDK to address that problem: an initializer agent that sets up the environment on the first run, and a coding agent that makes incremental progress in every later session while leaving clear artifacts for the next one. The authors identify four common failure modes, including attempting to build an entire app at once, prematurely declaring the project complete, leaving the environment buggy or undocumented, and marking features done without end-to-end testing. Their solutions include a structured JSON feature list, a progress notes file combined with git history, an init.sh script for running and testing the app, and explicit browser-based verification. The conclusion is that prompting agents to work one feature at a time and end each session in a clean, committed state enables consistent progress across many context windows, though open questions remain about multi-agent architectures and generalizing beyond web development.

核心贡献 · Key contributions

局限 · Limitations

章节 · Sections(共 9)

全文 · Full text(逐段中英对照)

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

2026 年 3 月 24 日 面向长时运行应用开发的 Harness 设计

Mar 24, 2026 Harness design for long-running application development

随着 AI 智能体能力不断增强,开发者越来越多地要求它们承担需要持续数小时乃至数天的复杂任务。然而,如何让智能体在多个上下文窗口之间保持一致的进展,仍是一个未解决的问题。

As AI agents become more capable, developers are increasingly asking them to take on complex tasks requiring work that spans hours, or even days. However, getting agents to make consistent progress across multiple context windows remains an open problem.

长时运行智能体的核心挑战在于:它们必须在离散的会话中工作,而每个新会话开始时都不记得之前发生过什么。想象一个软件项目由轮班工作的工程师组成,每位新到的工程师对上一班发生的事情毫无记忆。由于上下文窗口有限,且大多数复杂项目无法在单个窗口内完成,智能体需要一种方式来弥合各编码会话之间的鸿沟。

The core challenge of long-running agents is that they must work in discrete sessions, and each new session begins with no memory of what came before. Imagine a software project staffed by engineers working in shifts, where each new engineer arrives with no memory of what happened on the previous shift. Because context windows are limited, and because most complex projects cannot be completed within a single window, agents need a way to bridge the gap between coding sessions.

我们开发了一套双重方案,使 Claude Agent SDK 能够在多个上下文窗口之间高效工作:一个**初始化智能体**,在首次运行时搭建环境;以及一个**编码智能体**,其任务是在每个会话中取得增量进展,同时为下一个会话留下清晰的产物。你可以在随附的快速入门中找到代码示例。

We developed a two-fold solution to enable the Claude Agent SDK to work effectively across many context windows: an **initializer agent** that sets up the environment on the first run, and a **coding agent** that is tasked with making incremental progress in every session, while leaving clear artifacts for the next session. You can find code examples in the accompanying quickstart.

长期运行智能体问题 The long-running agent problem

Claude Agent SDK 是一个强大、通用的智能体框架,擅长编码以及需要模型使用工具来收集上下文、规划和执行的其他任务。它具有上下文管理能力,例如压缩(compaction),这使得智能体能够在不耗尽上下文窗口的情况下处理任务。理论上,在这种设置下,智能体应该有可能在任意长的时间内持续进行有用的工作。

The Claude Agent SDK is a powerful, general-purpose agent harness adept at coding, as well as other tasks that require the model to use tools to gather context, plan, and execute. It has context management capabilities such as compaction, which enables an agent to work on a task without exhausting the context window. Theoretically, given this setup, it should be possible for an agent to continue to do useful work for an arbitrarily long time.

然而,压缩并不足够。即使像 Opus 4.5 这样的前沿编码模型在 Claude Agent SDK 上跨多个上下文窗口循环运行,如果只给出一个高层次的提示,例如“构建一个 claude.ai 的克隆”,它也无法构建出生产质量的 Web 应用。

However, compaction isn’t sufficient. Out of the box, even a frontier coding model like Opus 4.5 running on the Claude Agent SDK in a loop across multiple context windows will fall short of building a production-quality web app if it’s only given a high-level prompt, such as “build a clone of claude.ai.”

Claude 的失败表现为两种模式。首先,智能体倾向于一次性做太多事情——本质上是试图一次性完成应用。通常,这导致模型在实现过程中耗尽上下文,使得下一个会话开始时某个功能只实现了一半且没有文档记录。然后,智能体不得不猜测发生了什么,并花费大量时间试图让基本应用重新工作。即使有压缩,这种情况也会发生,因为压缩并不总是将完全清晰的指令传递给下一个智能体。

Claude’s failures manifested in two patterns. First, the agent tended to try to do too much at once—essentially to attempt to one-shot the app. Often, this led to the model running out of context in the middle of its implementation, leaving the next session to start with a feature half-implemented and undocumented. The agent would then have to guess at what had happened, and spend substantial time trying to get the basic app working again. This happens even with compaction, which doesn’t always pass perfectly clear instructions to the next agent.

第二种失败模式通常发生在项目的后期。在一些功能已经构建之后,后来的智能体实例会环顾四周,看到已经取得了进展,然后宣布任务完成。

A second failure mode would often occur later in a project. After some features had already been built, a later agent instance would look around, see that progress had been made, and declare the job done.

这将问题分解为两部分。首先,我们需要建立一个初始环境,为给定提示所需的所有功能奠定基础,这为智能体逐步、逐个功能地工作做好了准备。其次,我们应该提示每个智能体朝着目标取得增量进展,同时在会话结束时将环境保持在干净状态。所谓“干净状态”,我们指的是适合合并到主分支的代码:没有重大错误,代码有序且文档齐全,并且一般来说,开发者可以轻松开始新功能的工作,而无需先清理不相关的混乱。

This decomposes the problem into two parts. First, we need to set up an initial environment that lays the foundation for _all_ the features that a given prompt requires, which sets up the agent to work step-by-step and feature-by-feature. Second, we should prompt each agent to make incremental progress towards its goal while also leaving the environment in a clean state at the end of a session. By “clean state” we mean the kind of code that would be appropriate for merging to a main branch: there are no major bugs, the code is orderly and well-documented, and in general, a developer could easily begin work on a new feature without first having to clean up an unrelated mess.

在内部实验中,我们采用两部分方案来解决这些问题:

When experimenting internally, we addressed these problems using a two-part solution:

1. 初始化智能体:第一个智能体会话使用专门的提示词,要求模型搭建初始环境:一个 init.sh 脚本、一个记录智能体已完成工作的 claude-progress.txt 文件,以及一个展示新增文件的初始 git 提交。

1. Initializer agent: The very first agent session uses a specialized prompt that asks the model to set up the initial environment: an init.sh script, a claude-progress.txt file that keeps a log of what agents have done, and an initial git commit that shows what files were added.

2. 编码智能体:后续每个会话都要求模型取得增量进展,然后留下结构化的更新记录。

2. Coding agent: Every subsequent session asks the model to make incremental progress, then leave structured updates.

这里的关键洞见在于,找到一种方法让智能体在全新的上下文窗口中启动时能快速理解工作状态,这通过 claude-progress.txt 文件配合 git 历史来实现。这些做法的灵感来源于了解高效的软件工程师每天是如何工作的。

The key insight here was finding a way for agents to quickly understand the state of work when starting with a fresh context window, which is accomplished with the claude-progress.txt file alongside the git history. Inspiration for these practices came from knowing what effective software engineers do every day.

环境管理 Environment management

在更新后的 Claude 4 提示指南中,我们分享了一些关于多上下文窗口工作流的最佳实践,其中包括一种 harness 结构,该结构对“第一个上下文窗口使用不同的提示词”。这个“不同的提示词”要求初始化智能体搭建好环境,并准备好后续编码智能体高效工作所需的全部必要上下文。在此,我们对此类环境的一些关键组成部分做更深入的探讨。

In the updated Claude 4 prompting guide, we shared some best practices for multi-context window workflows, including a harness structure that uses "a different prompt for the very first context window." This "different prompt" requests that the initializer agent set up the environment with all the necessary context that future coding agents will need to work effectively. Here, we provide a deeper dive on some of the key components of such an environment.

功能列表 Feature list

为解决智能体一次性完成应用或过早认为项目已完成的问题,我们提示初始化智能体编写一份全面的功能需求文件,对用户的初始提示进行扩展。在 claude.ai 克隆示例中,这意味着超过 200 项功能,例如“用户可以打开新对话、输入查询、按回车,并看到 AI 响应”。这些功能最初都被标记为“失败”,以便后续的编码智能体能够清楚地了解完整功能应包含哪些内容。

To address the problem of the agent one-shotting an app or prematurely considering the project complete, we prompted the initializer agent to write a comprehensive file of feature requirements expanding on the user's initial prompt. In the claude.ai clone example, this meant over 200 features, such as "a user can open a new chat, type in a query, press enter, and see an AI response." These features were all initially marked as "failing" so that later coding agents would have a clear outline of what full functionality looked like.

``` { "category": "functional", "description": "New chat button creates a fresh conversation", "steps": [ "Navigate to main interface", "Click the 'New Chat' button", "Verify a new conversation is created", "Check that chat area shows welcome state", "Verify conversation appears in sidebar" ], "passes": false } ```

``` { "category": "functional", "description": "New chat button creates a fresh conversation", "steps": [ "Navigate to main interface", "Click the 'New Chat' button", "Verify a new conversation is created", "Check that chat area shows welcome state", "Verify conversation appears in sidebar" ], "passes": false } ```

我们提示编码智能体仅通过更改 passes 字段的状态来编辑此文件,并使用措辞强硬的指令,例如“移除或编辑测试是不可接受的,因为这可能导致功能缺失或出现缺陷”。经过一些实验,我们最终选择使用 JSON 来实现这一点,因为与 Markdown 文件相比,模型不太可能不恰当地更改或覆盖 JSON 文件。

We prompt coding agents to edit this file only by changing the status of a passes field, and we use strongly-worded instructions like "It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality." After some experimentation, we landed on using JSON for this, as the model is less likely to inappropriately change or overwrite JSON files compared to Markdown files.

增量式进展 Incremental progress

在给定这一初始环境脚手架之后,编码智能体的下一轮迭代被要求一次只处理一个功能。事实证明,这种增量式方法对于纠正智能体倾向于一次性做太多事情的问题至关重要。

Given this initial environment scaffolding, the next iteration of the coding agent was then asked to work on only one feature at a time. This incremental approach turned out to be critical to addressing the agent's tendency to do too much at once.

即便采用增量式工作方式,模型在做出代码更改后仍必须使环境保持干净状态,这一点依然至关重要。在我们的实验中,我们发现,促使模型表现出这种行为的最佳方式是要求模型用描述性的提交信息将其进展提交到 git,并在进展文件中写下其进展摘要。这使得模型能够利用 git 回退错误的代码更改,并恢复代码库的可工作状态。

Once working incrementally, it is still essential that the model leaves the environment in a clean state after making a code change. In our experiments, we found that the best way to elicit this behavior was to ask the model to commit its progress to git with descriptive commit messages and to write summaries of its progress in a progress file. This allowed the model to use git to revert bad code changes and recover working states of the code base.

这些方法还提高了效率,因为它们消除了智能体不得不猜测发生了什么、并花时间试图让基础应用重新运行起来的需要。

These approaches also increased efficiency, as they eliminated the need for an agent to have to guess at what had happened and spend its time trying to get the basic app working again.

测试 Testing

我们观察到的最后一个主要失败模式是,Claude 倾向于在没有进行适当测试的情况下将某个功能标记为已完成。在缺乏明确提示时,Claude 往往会修改代码,甚至通过单元测试或针对开发服务器的 curl 命令进行测试,但无法识别该功能并未端到端正常工作。

One final major failure mode that we observed was Claude's tendency to mark a feature as complete without proper testing. Absent explicit prompting, Claude tended to make code changes, and even do testing with unit tests or curl commands against a development server, but would fail to recognize that the feature didn't work end-to-end.

在构建 Web 应用的情况下,一旦明确提示 Claude 使用浏览器自动化工具并像人类用户那样进行所有测试,Claude 大多能很好地端到端验证功能。

In the case of building a web app, Claude mostly did well at verifying features end-to-end once explicitly prompted to use browser automation tools and do all testing as a human user would.

为 Claude 提供这类测试工具显著提升了性能,因为该智能体能够识别并修复仅从代码中不易察觉的缺陷。

Providing Claude with these kinds of testing tools dramatically improved performance, as the agent was able to identify and fix bugs that weren't obvious from the code alone.

仍存在一些问题,例如 Claude 的视觉能力以及浏览器自动化工具的限制,使得难以识别所有类型的缺陷。例如,Claude 无法通过 Puppeteer MCP 看到浏览器原生的警告模态框,因此依赖这些模态框的功能往往更容易出现缺陷。

Some issues remain, like limitations to Claude's vision and to browser automation tools making it difficult to identify every kind of bug. For example, Claude can't see browser-native alert modals through the Puppeteer MCP, and features relying on these modals tended to be buggier as a result.

快速上手 Getting up to speed

在完成上述所有设置后,每个编码智能体都会被提示执行一系列步骤以熟悉环境,其中一些步骤相当基础,但仍然很有帮助:

With all of the above in place, every coding agent is prompted to run through a series of steps to get its bearings, some quite basic but still helpful:

1. _运行 `pwd` 查看当前工作目录。你只能编辑该目录中的文件。_

1. _Run `pwd` to see the directory you're working in. You'll only be able to edit files in this directory._

2. _阅读 git 日志和进度文件,以快速了解最近的工作内容。_

2. _Read the git logs and progress files to get up to speed on what was recently worked on._

3. _阅读功能列表文件,并选择尚未完成的最高优先级功能来着手处理。_

3. _Read the features list file and choose the highest-priority feature that's not yet done to work on._

这种方法在每个会话中为 Claude 节省了一些 token,因为它不必再摸索如何测试代码。同时,让初始化智能体编写一个 `init.sh` 脚本也很有帮助,该脚本可以启动开发服务器,并在实现新功能之前运行一遍基础的端到端测试。

This approach saves Claude some tokens in every session since it doesn't have to figure out how to test the code. It also helps to ask the initializer agent to write an `init.sh` script that can run the development server, and then run through a basic end-to-end test before implementing a new feature.

在 claude.ai 克隆项目这一案例中,这意味着智能体总是先启动本地开发服务器,并使用 Puppeteer MCP 来开启一个新对话、发送一条消息并接收响应。这确保了 Claude 能够快速判断应用是否处于损坏状态,并立即修复任何已存在的缺陷。如果智能体转而开始实现新功能,则很可能使问题进一步恶化。

In the case of the claude.ai clone, this meant that the agent always started the local development server and used the Puppeteer MCP to start a new chat, send a message, and receive a response. This ensured that Claude could quickly identify if the app had been left in a broken state, and immediately fix any existing bugs. If the agent had instead started implementing a new feature, it would likely make the problem worse.

综上所述,一次典型的会话会以如下助手消息开始:

Given all this, a typical session starts off with the following assistant messages:

``` [Assistant] I'll start by getting my bearings and understanding the current state of the project. [Tool Use] <bash - pwd> [Tool Use] <read - claude-progress.txt> [Tool Use] <read - feature_list.json> [Assistant] Let me check the git log to see recent work. [Tool Use] <bash - git log --oneline -20> [Assistant] Now let me check if there's an init.sh script to restart the servers. <Starts the development server> [Assistant] Excellent! Now let me navigate to the application and verify that some fundamental features are still working. <Tests basic functionality> [Assistant] Based on my verification testing, I can see that the fundamental functionality is working well. The core chat features, theme switching, conversation loading, and error handling are all functioning correctly. Now let me review the tests.json file more comprehensively to understand what needs to be implemented next. <Starts work on a new feature> ```

``` [Assistant] I'll start by getting my bearings and understanding the current state of the project. [Tool Use] <bash - pwd> [Tool Use] <read - claude-progress.txt> [Tool Use] <read - feature_list.json> [Assistant] Let me check the git log to see recent work. [Tool Use] <bash - git log --oneline -20> [Assistant] Now let me check if there's an init.sh script to restart the servers. <Starts the development server> [Assistant] Excellent! Now let me navigate to the application and verify that some fundamental features are still working. <Tests basic functionality> [Assistant] Based on my verification testing, I can see that the fundamental functionality is working well. The core chat features, theme switching, conversation loading, and error handling are all functioning correctly. Now let me review the tests.json file more comprehensively to understand what needs to be implemented next. <Starts work on a new feature> ```

智能体的失败模式与解决方案 Agent failure modes and solutions

Claude 过早地宣布整个项目已告完成。

Claude declares victory on the entire project too early.

建立功能清单文件:根据输入规格,建立一个结构化 JSON 文件,其中包含端到端功能描述列表。

Set up a feature list file: based on the input spec, set up a structured JSON file with a list of end-to-end feature descriptions.

在会话开始时读取功能清单文件,并选择单个功能开始处理。

Read the feature list file at the beginning of a session. Choose a single feature to start working on.

Claude 使环境处于存在缺陷或进度未被记录的状态。

Claude leaves the environment in a state with bugs or undocumented progress.

写入初始 git 仓库与进度记录文件。

An initial git repo and progress notes file is written.

在会话开始时读取进度记录文件和 git 提交日志,并在开发服务器上运行基本测试,以捕获任何未记录的缺陷。在会话结束时编写 git 提交和进度更新。

Start the session by reading the progress notes file and git commit logs, and run a basic test on the development server to catch any undocumented bugs. End the session by writing a git commit and progress update.

Claude 过早地将功能标记为已完成。

Claude marks features as done prematurely.

对所有功能进行自我验证。只有在仔细测试之后,才将功能标记为“通过”。

Self-verify all features. Only mark features as "passing" after careful testing.

Claude 不得不花时间弄清楚如何运行该应用。

Claude has to spend time figuring out how to run the app.

编写一个能够运行开发服务器的 init.sh 脚本。

Write an init.sh script that can run the development server.

总结长时运行 AI 智能体中四种常见的失效模式及其解决方案。

Summarizing four common failure modes and solutions in long-running AI agents.

未来工作 Future work

本研究表明,在长时间运行的智能体框架(agent harness)中,存在一组可行的解决方案,使模型能够在多个上下文窗口之间逐步取得进展。然而,仍有一些开放性问题有待解决。

This research demonstrates one possible set of solutions in a long-running agent harness to enable the model to make incremental progress across many context windows. However, there remain open questions.

最值得注意的是,目前尚不清楚是单一的通用编程智能体在各种情境下表现最佳,还是通过多智能体架构能够获得更好的性能。一个合理的设想是,诸如测试智能体、质量保证智能体或代码清理智能体等专用智能体,或许能在软件开发生命周期的各个子任务上表现得更为出色。

Most notably, it's still unclear whether a single, general-purpose coding agent performs best across contexts, or if better performance can be achieved through a multi-agent architecture. It seems reasonable that specialized agents like a testing agent, a quality assurance agent, or a code cleanup agent, could do an even better job at sub-tasks across the software development lifecycle.

此外,本演示针对全栈 Web 应用开发进行了优化。未来的一个方向是将这些发现推广到其他领域。这些经验中的部分或全部,很可能可以应用于诸如科学研究或金融建模等领域所需的长时间运行的智能体式任务。

Additionally, this demo is optimized for full-stack web app development. A future direction is to generalize these findings to other fields. It's likely that some or all of these lessons can be applied to the types of long-running agentic tasks required in, for example, scientific research or financial modeling.

互动版:针对本篇提问 →

接着读 · Read next