有效管理长期运行的智能体 | Anthropic

---

0、核心速览

  通过“总分模式”（初始化智能体做全局规划 + 编码智能体做增量执行）和动态维护的“待办清单”（功能列表 + 进度记录），解决长期运行智能体的三个核心问题：

• 上下文断裂问题：传统智能体在多轮对话或长任务中，因上下文窗口限制，无法记住之前的所有细节。
• 多智能体协同问题：如果把每次会话的编码智能体看作“独立工人”，它们之间原本没有协同机制。
• 动态变化适应问题：实际项目中需求常变，可能因上下文断裂无法灵活调整。

  通过“总分模式”和“动态维护 TODO List”完美解决上述问题：

• 第一次（总）：初始化智能体扮演“项目经理”，制定全局计划（功能清单 + 环境搭建 + 工作规则），生成初始 TODO List（功能列表）。
• 后续（分）：编码智能体扮演“执行工人”，每次从 TODO List（功能列表）里领一个“未完成任务”，做完后打勾（更新状态）并记录进展（Git + 日志），如果 TODO List 变化（新增/修改需求），人工调整后智能体按新列表继续。

  这种方式不仅解决了上下文断裂（通过轻量级记录替代长文本记忆），还通过结构化协作机制（统一的待办清单 + 规则）让多智能体（或多次会话）能像连续工作的团队一样协同，最终实现长期任务的稳定推进。

---

  随着AI智能体的能力不断提升，开发者越来越多地要求它们承担需要跨越数小时甚至数天的复杂任务。然而，如何让智能体在多个上下文窗口中保持持续进展仍然是一个悬而未决的问题。长期运行智能体的核心挑战在于，它们必须以离散的会话形式工作，且每个新会话开始时对之前的内容毫无记忆。想象一个由工程师轮班工作的软件项目，每位新来的工程师都对上一班次发生的事情毫无印象。由于上下文窗口有限，且大多数复杂项目无法在单个窗口内完成，智能体需要一种方法来弥合编码会话之间的差距。

  我们开发了一个双重解决方案，使Claude Agent SDK能够在多个上下文窗口中高效工作：一个初始化 Agent 负责在首次运行时设置环境，以及一个编码 Agent 负责在每次会话中取得增量进展，同时为下一会话留下清晰的成果。

1、长期运行Agent的问题

  Claude Agent SDK是一个强大且通用的智能体工具，擅长编码以及其他需要模型使用工具收集上下文、规划和执行的任务。它具备上下文管理功能（如压缩），使智能体能够在不耗尽上下文窗口的情况下处理任务。理论上有了这样的设置，Agent 应该能够无限期地继续进行有用的工作。

  然而，仅靠压缩功能并不足够。即使像Opus 4.5这样先进的编码模型，在Claude Agent SDK中循环运行于多个上下文窗口，如果仅给出一个高层级提示（例如“克隆一个claude.ai”），也无法构建出生产质量的Web应用。

  Claude的失败表现为两种模式：

1. 一次性做太多事：Agent倾向于一次性尝试完成整个应用，这往往导致模型在实现过程中耗尽上下文，使得下一会话从一个半实现且未记录的功能开始。智能体随后不得不猜测之前发生了什么，并花费大量时间试图让基本应用重新工作。即使有压缩功能，也不总能向下一智能体传递完全清晰的指令。

2. 过早标记完成：在项目后期，当一些功能已经构建完成后，后续的智能体实例可能会环顾四周，看到已有进展，便宣布任务完成。

1.1 定位问题

  为了解决这些问题可以分解为两个步骤：

• 首先，我们需要设置一个初始环境，为给定提示所需的所有功能奠定基础，使 Agent 能够逐步、逐个功能地工作；
• 其次，我们应该提示每个 Agent 在每次会话中朝着目标取得增量进展，同时在会话结束时将环境保持在清洁状态。所谓“清洁状态”，是指适合合并到主分支的代码：没有重大错误，代码有序且文档齐全，开发者可以轻松开始新功能的工作，而无需先清理无关的混乱。

1.2 解决方案

  在内部实验中，我们通过“总分模式”（初始化智能体做全局规划 + 编码智能体做增量执行）和动态维护的“待办清单”（功能列表 + 进度记录）的形式来解决这些问题：

• 初始化 Agent：在项目初始阶段，首次会话使用一个专门的提示，要求模型设置初始环境：一个init.sh脚本、一个记录 Agent 操作的claude-progress.txt文件，以及一个管理git提交记录的文件。
• 编码 Agent：每个后续会话要求大语言模型取得增量进展，然后留下结构化更新。

  关键在于找到一种方法，使 Agent 在启动新鲜上下文窗口时能快速理解工作状态，这是通过claude-progress.txt文件与git历史记录一起实现的。

2、环境管理

  这些实践的灵感来自于了解有效软件工程师每天所做的事情，在更新的Claude 4提示指南中，我们分享了一些多上下文窗口工作流的最佳实践，包括使用“针对第一个上下文窗口的不同提示”。这个“不同提示”要求初始化智能体设置环境，提供未来编码智能体有效工作所需的所有上下文。

2.1 Feature list

  为了解决智能体一次性尝试完成所有功能需求或过早标记功能需求完成的问题，我们提示初始化 Agent 编写一个全面的Feature list（功能需求文件），扩展用户的初始提示。以克隆claude.ai为例，这意味着超过200个功能，例如“用户可以打开新聊天，输入查询，按回车，并看到AI响应”。这些功能最初都标记为“失败”，以便后续编码智能体有一个清晰的功能完整性的轮廓。

  我们提示编码 Agent 仅通过更改passes字段的状态来编辑此文件，并使用措辞强烈的指令，如“不可接受删除或编辑测试，因为这可能导致遗漏或有缺陷的功能”。经过一些实验，我们最终选择了JSON格式，因为大语言模型相比Markdown而言，不太可能不恰当地更改或覆盖JSON文件。

{
    "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
  }

2.2 Incremental progress（渐进式进展）

  在这个初始环境框架下，下一版本的编码 Agent 被要求一次只处理一个功能。这种以渐进式进展的方式，对于解决Agent 一次性尝试过多的功能需求至关重要。一旦采用渐进式的方法，大语言模型在做出代码更改后仍需将环境保持在清洁状态。

  在我们的实验中，发现最佳方法是要求大语言模型将其进展提交到git，并附上描述性提交信息，并在进度文件中写下其进展的摘要。这使大语言模型能够使用git回滚不良的代码更改并恢复代码库的工作状态。这些方法还提高了效率，因为它们消除了智能体猜测发生了什么并花费时间试图让基本应用重新工作的需要。

2.3 Testing（测试）

  我们观察到的最后一个主要失败模式是Claude倾向于在没有适当测试的情况下将功能标记为完成。在没有明确提示的情况下，Claude倾向于进行代码更改，甚至使用单元测试或对开发服务器进行curl命令测试，但未能识别功能未端到端工作。在构建Web应用的情况下，一旦明确提示使用浏览器自动化工具并以人类用户的方式进行所有测试，Claude在验证功能端到端方面表现良好。

  Claude通过Puppeteer MCP服务器在测试claude.ai克隆时拍摄的截图。为Claude提供这些测试工具显著提高了性能，因为智能体能够识别并修复仅从代码中不明显的错误。一些问题仍然存在，例如Claude的视觉限制和浏览器自动化工具使得难以识别每种类型的错误。例如，Claude无法通过Puppeteer MCP看到浏览器原生的警报模态框，因此依赖于这些模态框的功能往往更易出错。

3、动起来

  在上述所有准备就绪后，每个编码 Agent 都被提示运行一系列步骤以了解情况，其中一些步骤非常基础但仍然有帮助：

1. 运行pwd以查看您正在工作的目录。您只能编辑此目录中的文件。
2. 读取git日志和进度文件，以了解最近的工作内容。
3. 读取功能列表文件，并选择尚未完成的最高优先级功能进行处理。

  这种方法在每个会话中为Claude节省了一些令牌，因为它不必弄清楚如何测试代码。还建议初始化智能体编写一个可以运行开发服务器的init.sh脚本，然后在实现新功能之前进行基本的端到端测试。

  在克隆claude.ai的情况下，这意味着智能体始终启动本地开发服务器，并使用Puppeteer MCP启动新聊天，发送消息并接收响应。这确保了Claude能够快速识别应用是否处于损坏状态，并立即修复任何现有错误。如果智能体反而开始实现新功能，可能会使问题更糟。

  鉴于此，典型的会话以以下助手消息开始：

[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>

Problem	Initializer Agent Behavior	Coding Agent Behavior
Claude declares victory on the entire project too early.	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 leaves the environment in a state with bugs or undocumented progress.	An initial git repo and progress notes file is written.	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 marks features as done prematurely.	Set up a feature list file.	Self-verify all features. Only mark features as “passing” after careful testing.
Claude has to spend time figuring out how to run the app.	Write an init.sh script that can run the development server.	Start the session by reading init.sh.

4、未来工作

  这项研究展示了一种可能的长期运行 Agent 工具包解决方案，使模型能够在多个上下文窗口中取得增量进展。然而，仍有一些悬而未决的问题。最值得注意的是，尚不清楚单一的通用编码 Agent 是否在各种上下文中表现最佳，或者通过多 Agent 体架构是否能获得更好的性能。合理的假设是，专业化的智能体（如测试 Agent 、质量保证 Agent 或代码清理 Agent ）可能在软件开发生命周期的子任务中表现得更好。

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

原文地址：https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents

---

一键三连，让我的信心像气球一样膨胀！