用于长时间运行代理的有效工具

# 为长时间运行的智能体设计有效的执行框架 来源：https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents 随着AI智能体能力的不断提升，开发者们越来越多地让它们承担需要数小时甚至数天才能完成的复杂任务。然而，如何让智能体在多个上下文窗口中保持持续进展，仍然是一个未解决的问题。 长时间运行智能体的核心挑战在于，它们必须在离散的会话中工作，而每个新会话开始时都对之前发生的事情毫无记忆。想象一下一个软件项目，工程师们轮班工作，每位新到岗的工程师都不记得上一班发生了什么。由于上下文窗口有限，且大多数复杂项目无法在一个窗口内完成，智能体需要一种方式来弥合会话之间的差距。 我们开发了一套双重解决方案，使Claude Agent SDK（https://platform.claude.com/docs/en/agent-sdk/overview）能够在多个上下文窗口中有效工作：**初始化智能体**（initializer agent）负责在首次运行时设置环境，**编码智能体**（coding agent）则负责在每个会话中取得渐进式进展，同时为下一个会话留下清晰的成果物。你可以在配套的快速入门指南中找到代码示例。（https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding） ## 长时间运行智能体的问题 Claude Agent SDK 是一个功能强大的通用智能体框架，擅长编码以及需要模型使用工具来收集上下文、规划和执行的其他任务。它具有上下文管理能力，例如压缩（compaction），使智能体能够在不耗尽上下文窗口的情况下处理任务。理论上，在这种设置下，智能体应该能够持续进行任意长时间的有用工作。 然而，仅靠压缩是不够的。即使像Opus 4.5这样的前沿编码模型，在Claude Agent SDK上循环运行多个上下文窗口，如果只给它一个高层级的提示，比如"构建一个claude.ai（http://claude.ai/redirect/website.v1.5aae9689-2506-4938-b8d4-f6b3892b42f8）的克隆版"，也无法构建出生产级的Web应用。 Claude的失败呈现出两种模式。首先，智能体倾向于一次性做太多——试图一次性完成整个应用。这通常导致模型在实现过程中耗尽上下文，使下一个会话开始时面对一个半途而废、缺乏文档的功能。智能体随后不得不猜测发生了什么，并花费大量时间试图让基础应用重新运行起来。即使有压缩，这种情况也会发生，因为压缩并不总是能向下一个智能体传递完全清晰的指令。 第二种失败模式通常发生在项目后期。在一些功能已经构建完成后，后续的智能体实例会环顾四周，看到已经取得了进展，就宣布工作完成。 这可以将问题分解为两部分。首先，我们需要设置一个初始环境，为给定提示所需的*所有*功能奠定基础，让智能体能够逐步、逐个功能地推进工作。其次，我们应该提示每个智能体朝着目标取得渐进式进展，同时在会话结束时将环境保持在干净状态。我们所说的"干净状态"是指适合合并到主分支的代码：没有重大bug，代码整洁且有良好文档，通常开发人员可以轻松开始新功能的开发，而无需先清理无关的混乱。 在内部实验中，我们通过两部分解决方案解决了这些问题： 1. **初始化智能体**：第一个智能体会话使用专门的提示，要求模型设置初始环境：一个`init.sh`脚本、一个记录智能体工作日志的`claude-progress.txt`文件，以及一个显示添加了哪些文件的初始git提交。 2. **编码智能体**：每个后续会话要求模型取得渐进式进展，然后留下结构化的更新。¹ 这里的关键洞见是找到一种方法，让智能体在从全新的上下文窗口开始时快速理解工作状态，这是通过`claude-progress.txt`文件和git历史共同实现的。这些实践的灵感来自于了解高效软件工程师每天的工作方式。 ## 环境管理 在更新的Claude 4提示指南（https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices#multi-context-window-workflows）中，我们分享了一些多上下文窗口工作流的最佳实践，包括一种使用"第一个上下文窗口采用不同提示"的框架结构。这种"不同的提示"要求初始化智能体设置环境，包含未来编码智能体有效工作所需的所有必要上下文。 在这里，我们对这种环境的关键组成部分进行更深入的探讨。 ### 功能列表 为了解决智能体一次性完成应用或过早认为项目完成的问题，我们提示初始化智能体编写一份全面的功能需求文件，扩展用户的初始提示。在claude.ai（http://claude.ai/redirect/website.v1.5aae9689-2506-4938-b8d4-f6b3892b42f8）克隆示例中，这意味着超过200个功能，例如"用户可以打开新聊天、输入查询、按回车键，并看到AI响应"。这些功能最初都标记为"未通过"，以便后续编码智能体能够清晰了解完整功能的面貌。 ```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 } ``` 我们提示编码智能体仅通过更改`passes`字段的状态来编辑此文件，并使用措辞强烈的指令，如"删除或编辑测试是不可接受的，因为这可能导致功能缺失或存在bug"。经过一些实验后，我们确定使用JSON格式，因为与Markdown文件相比，模型更不容易不恰当地更改或覆盖JSON文件。 ### 渐进式进展 有了这种初始环境框架，编码智能体的下一次迭代被要求一次只处理一个功能。这种渐进式方法对于解决智能体一次性做太多的倾向至关重要。 一旦采用渐进式工作，模型在进行代码更改后将环境保持在干净状态仍然至关重要。在我们的实验中，我们发现激发这种行为的最佳方式是要求模型将进展提交到git，使用描述性的提交消息，并在进度文件中写入摘要。这使得模型能够使用git来回退糟糕的代码更改，恢复代码库的工作状态。这些方法也提高了效率，因为它们消除了智能体不得不猜测发生了什么并花费时间试图让基础应用重新运行的需要。 ### 测试 我们观察到的最后一个主要失败模式是Claude倾向于在没有适当测试的情况下将功能标记为完成。在没有明确提示的情况下，Claude倾向于进行代码更改，甚至使用单元测试或`curl`命令对开发服务器进行测试，但未能识别该功能在端到端层面无法正常工作。 在构建Web应用的情况下，一旦明确提示Claude使用浏览器自动化工具并像人类用户一样进行所有测试，它在端到端验证功能方面表现良好。 > 通过Puppeteer MCP服务器，Claude在测试claude.ai克隆版时截取的屏幕截图。 > 通过Puppeteer MCP服务器，Claude在测试claude.ai克隆版时截取的屏幕截图。 为Claude提供这类测试工具显著提升了性能，因为智能体能够识别并修复仅从代码本身难以发现的bug。但仍有一些问题存在，例如Claude视觉能力的局限性以及浏览器自动化工具的限制，使其难以识别所有类型的bug。例如，Claude无法通过Puppeteer MCP看到浏览器原生的警告弹窗，依赖这些弹窗的功能因此更容易出现bug。 ## 快速上手 有了上述所有设置，每个编码智能体都被提示运行一系列步骤来了解情况，有些步骤相当基础但仍很有帮助： 1. *运行`pwd`查看你正在工作的目录。你只能编辑此目录中的文件。* 2. *阅读git日志和进度文件，了解最近的工作内容。* 3. *阅读功能列表文件，选择优先级最高且尚未完成的功能来工作。* 这种方法在每个会话中为Claude节省了一些token，因为它不必弄清楚如何测试代码。同时，让初始化智能体编写一个可以运行开发服务器的`init.sh`脚本，然后在实现新功能之前运行基本的端到端测试，也是很有帮助的。 在claude.ai克隆版的例子中，这意味着智能体总是先启动本地开发服务器，然后使用Puppeteer MCP来开始新聊天、发送消息并接收响应。这确保了Claude能够快速识别应用是否被留在了损坏的状态，并立即修复任何现有bug。如果智能体转而开始实现新功能，很可能会使问题变得更糟。 综上所述，一个典型的会话以以下助手消息开始： ``` [Assistant] I'll start by getting my bearings and understanding the current state of the project. [Tool Use] [Tool Use] [Tool Use] [Assistant] Let me check the git log to see recent work. [Tool Use] [Assistant] Now let me check if there's an init.sh script to restart the servers. [Assistant] Excellent! Now let me navigate to the application and verify that some fundamental features are still working. [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. ``` ### 智能体失败模式与解决方案 | 问题 | 初始化智能体行为 | 编码智能体行为 | |:---|:---|:---| | Claude过早宣布整个项目完成 | 设置功能列表文件：基于输入规格，设置结构化的JSON文件，包含端到端功能描述列表 | 在会话开始时阅读功能列表文件。选择一个功能开始工作 | | Claude将环境留在存在bug或进展未记录的状态 | 写入初始git仓库和进度记录文件 | 会话开始时阅读进度记录文件和git提交日志，并对开发服务器运行基本测试以捕捉任何未记录的bug。会话结束时写入git提交和进度更新 | | Claude过早将功能标记为完成 | 设置功能列表文件 | 自我验证所有功能。仅在仔细测试后将功能标记为"通过" | | Claude不得不花时间弄清楚如何运行应用 | 编写可以运行开发服务器的`init.sh`脚本 | 会话开始时阅读`init.sh` | 总结长时间运行AI智能体的四种常见失败模式及解决方案。 ## 未来工作 这项研究展示了一套在长时间运行智能体框架中的可能解决方案，使模型能够在多个上下文窗口中取得渐进式进展。然而，仍有一些未解决的问题。 最值得注意的是，目前尚不清楚单个通用编码智能体在不同上下文中表现最佳，还是多智能体架构能够实现更好的性能。像测试智能体、质量保证智能体或代码清理智能体这样的专业智能体，似乎有可能在软件开发生命周期的子任务中表现更好。 此外，此演示针对全栈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内部多个团队的集体努力，特别是代码RL和Claude Code团队，他们使Claude能够安全地进行长时程自主软件工程。有兴趣贡献的候选人欢迎申请anthropic.com/careers（http://anthropic.com/careers）。 ### 脚注 1. 我们在此上下文中将它们称为不同的智能体，仅仅因为它们有不同的初始用户提示。系统提示、工具集和整体智能体框架在其他方面是完全相同的。