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.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 problemThe 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.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’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: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.Coding agent: Every subsequent session asks the model to make incremental progress, then leave structured updates.1The 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 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 listTo 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.
随着人工智能代理的能力越来越强，开发者们越来越多地要求它们承担复杂的任务，这些任务需要花费数小时甚至数天的工作。 然而，让代理在多个上下文窗口中取得持续的进展仍然是一个悬而未决的问题。 长期运行代理的核心挑战在于它们必须在离散的会话中工作，而每个新会话开始时都没有之前的记忆。 想象一个由轮班工程师组成的软件项目，每位新工程师到来时都对前一班发生的事情毫无记忆。 由于上下文窗口是有限的，而且大多数复杂项目无法在单个窗口内完成，代理需要一种方法来弥合编码会话之间的差距。 我们开发了一个双管齐下的解决方案，使 Claude Agent SDK 能够有效地跨越多个上下文窗口工作：一个初始化代理，负责在首次运行时设置环境；一个编码代理，负责在每次会话中取得渐进式进展，同时为下一个会话留下清晰的痕迹。 您可以在随附的快速入门指南中找到代码示例。 长期运行代理问题 Claude Agent SDK 是一个强大的通用代理框架，擅长编码以及其他需要模型使用工具来收集上下文、规划和执行的任务。 它具有上下文管理功能，例如压缩，这使得代理可以在不耗尽上下文窗口的情况下处理任务。 理论上，有了这个设置，代理应该能够无限期地继续进行有用的工作。 然而，压缩并不足够。 开箱即用，即使是像 Opus 4.5 这样的前沿编码模型在 Claude Agent SDK 上跨多个上下文窗口循环运行时，如果只给它一个高层次的提示，比如“构建一个 claude.ai 的克隆版”，也无法构建出生产质量的 Web 应用。 Claude 的失败表现出两种模式。 首先，代理倾向于一次做太多事情——基本上是试图一次性完成整个应用。 这常常导致模型在实现过程中耗尽上下文，导致下一个会话开始时，一个功能只实现了一半且没有文档记录。 然后代理必须猜测发生了什么，并花费大量时间来尝试让基本应用再次工作。 即使有压缩功能，也会发生这种情况，因为它并不总是能将清晰的指令传递给下一个代理。 第二种失败模式通常发生在项目的后期。 在构建了一些功能后，后续的代理实例会环顾四周，看到已经取得了进展，然后宣布任务完成。 这会将问题分解为两个部分。 首先，我们需要设置一个初始环境，为给定提示所需的所有功能奠定基础，从而使代理能够一步一步、一个功能一个功能地工作。 其次，我们应该提示每个代理朝着目标取得渐进式进展，同时在会话结束时将环境保持在干净的状态。 我们所说的“干净状态”是指适合合并到主分支的代码：没有重大错误，代码有序且文档齐全，总的来说，开发人员可以轻松地开始新功能的开发，而无需先清理无关的混乱。 在内部实验时，我们使用了一个两部分解决方案来解决这些问题：初始化代理：第一个代理会话使用一个专门的提示，要求模型设置初始环境：一个 init.sh 脚本，一个记录代理所做事情的 claude-progress.txt 文件，以及一个显示已添加文件的初始 git 提交。 编码代理：每次后续会话都要求模型取得渐进式进展，然后留下结构化的更新。 这里的关键洞察在于找到一种方法，让代理在从一个全新的上下文窗口开始时能够快速了解工作状态，这通过 claude-progress.txt 文件和 git 历史记录来实现。 这些实践的灵感来自于了解有效的软件工程师每天都在做什么。 环境管理 在更新的 Claude 4 提示指南中，我们分享了一些多上下文窗口工作流的最佳实践，包括一种使用“为第一个上下文窗口提供不同提示”的框架结构。 这个“不同的提示”要求初始化代理设置好环境，包含未来编码代理有效工作所需的所有必要上下文。 在这里，我们对这种环境的一些关键组成部分进行了更深入的探讨。 功能列表 为了解决代理一次性完成应用或过早认为项目完成的问题，我们提示初始化代理编写一份全面的功能需求文件，扩展用户最初的提示。
