如何开发长期运行的AI代理

随着AI代理变得越来越强大，开发人员越来越多地要求它们承担需要跨越数小时甚至数天的工作的复杂任务。然而，让代理在多个上下文窗口中保持一致的进展仍然是一个开放性问题。

长期运行代理的核心挑战在于，它们必须在离散的会话中工作，而每个新会话开始时都没有之前的信息记忆。想象一下，一个软件项目由工程师轮班工作，每个新工程师到来时都没有前一班次的任何信息。由于上下文窗口有限，并且大多数复杂项目无法在一个窗口内完成，代理需要一种方法来弥合编码会话之间的差距。

我们开发了一个双管齐下的解决方案，使Claude Agent SDK能够在许多上下文窗口中有效工作：一个初始化代理，用于首次运行时设置环境，以及一个编码代理，它被指派在每次会话中逐步推进任务，同时为下一次会话留下清晰的成果。你可以在配套的快速入门中找到代码示例。

1、长期运行代理的问题

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

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

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

第二种失败模式通常会在项目后期发生。在一些功能已经建立之后，后续的代理实例会四处查看，发现已经有进展，然后宣布任务完成。

这将问题分解为两个部分。首先，我们需要设置一个初始环境，为给定提示所需的所有功能奠定基础，这使得代理能够逐步、分功能地工作。其次，我们应该提示每个代理在会话结束时做出增量进展并保持环境处于干净状态。所谓“干净状态”是指适合合并到主分支的代码：没有重大错误，代码有序且有良好的文档说明，一般来说，开发者可以轻松地开始新功能的开发，而无需先清理无关的混乱。

在内部实验中，我们通过一个两部分的解决方案解决了这些问题：

1. 初始化代理：第一个代理会话使用一个专门的提示，要求模型设置初始环境：一个 init.sh 脚本、一个 claude-progress.txt 文件，用于记录代理已完成的工作，以及一个初始 git 提交，显示添加了哪些文件。
2. 编码代理：每次后续会话都会要求模型进行增量进展，然后留下结构化的更新。

这里的关键见解是找到一种方式，使代理在使用新的上下文窗口时能够快速了解工作的状态，这通过 claude-progress.txt 文件和 git 历史记录得以实现。这些做法的灵感来自于了解有效的软件工程师每天所做的工作。

2、环境管理

在更新的Claude 4 提示指南中，我们分享了一些多上下文窗口工作流程的最佳实践，包括一个使用“不同提示”的钩子结构，即第一个上下文窗口。这个“不同的提示”请求初始化代理设置环境，提供未来编码代理有效工作的所有必要上下文。在这里，我们深入探讨了此类环境中的一些关键组件。

2.1 功能列表

为了解决代理一次性完成应用程序或过早认为项目完成的问题，我们提示初始化代理编写一份全面的功能需求文件，扩展用户的初始提示。在claude.ai 克隆的例子中，这意味着超过 200 个功能，例如“用户可以打开一个新聊天，输入查询，按回车键，并看到 AI 的响应”。这些功能最初都被标记为“失败”，以便后续编码代理可以清楚地了解完整功能是什么样子。

{
    "category": "functional",
    "description": "新聊天按钮创建一个新的对话",
    "steps": [
      "导航到主界面",
      "点击 '新聊天' 按钮",
      "验证创建了一个新的对话",
      "检查聊天区域显示欢迎状态",
      "验证对话出现在侧边栏"
    ],
    "passes": false
  }

我们提示编码代理仅通过更改 passes 字段的状态来编辑此文件，我们使用措辞强烈的指示，如“删除或编辑测试是不可接受的，因为这可能导致遗漏或有缺陷的功能。”经过一些实验后，我们决定使用 JSON，因为模型不太可能不当更改或覆盖 JSON 文件，而不是 Markdown 文件。

2.2 增量进展

有了这个初始环境的结构，接下来的编码代理被要求一次只处理一个功能。这种渐进的方法对于解决代理倾向于一次做太多事情的趋势至关重要。

一旦采用渐进方式，模型在进行代码更改后仍需确保环境处于干净状态。在我们的实验中，我们发现最有效的方法是要求模型用描述性的提交信息将进度提交到 git，并在进度文件中写入其进度摘要。这允许模型使用 git 回滚错误的代码更改并恢复代码库的工作状态。

这些方法还提高了效率，因为它们消除了代理必须猜测发生了什么并花费时间重新使基本应用程序正常工作的需要。

2.3 测试

我们观察到的最后一个主要失败模式是 Claude 倾向于在没有充分测试的情况下将功能标记为完成。如果没有明确提示，Claude 会进行代码更改，甚至使用单元测试或 curl 命令对开发服务器进行测试，但无法识别功能端到端是否工作。

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

向 Claude 提供这些类型的测试工具显著提高了性能，因为代理能够识别并修复单凭代码无法察觉的错误。

仍然存在一些问题，比如 Claude 视觉能力的限制以及浏览器自动化工具的局限性，使得难以识别每种类型的错误。例如，Claude 无法通过 Puppeteer MCP 看到浏览器原生的警报模态框，因此依赖这些模态框的功能往往会更易出错。

3、快速上手

在上述所有措施到位后，每个编码代理都会被提示运行一系列步骤来熟悉环境，有些步骤非常基础，但仍有所帮助：

1. 运行 pwd 以查看当前所在的目录。你只能编辑该目录中的文件。
2. 阅读 git 日志和 progress 文件，以了解最近的工作内容。
3. 阅读功能列表文件，选择优先级最高且尚未完成的功能来着手处理。

这种方法在每次会话中节省了 Claude 的 token，因为它不需要再考虑如何测试代码。此外，这也帮助初始化代理编写一个 init.sh 脚本，可以运行开发服务器，然后在实现新功能之前运行基本的端到端测试。

在 claude.ai 克隆案例中，这意味着代理始终启动本地开发服务器，并使用 Puppeteer MCP 开始一个新聊天，发送消息并接收响应。这确保了 Claude 可以迅速识别应用程序是否处于损坏状态，并立即修复现有错误。如果代理一开始就实施新功能，很可能会使问题变得更糟。

鉴于所有这些，典型的会话开始如下助理消息：

[助手] 我将首先了解项目的当前状态并熟悉环境。
[工具使用] <bash - pwd>
[工具使用] <read - claude-progress.txt>
[工具使用] <read - feature_list.json>
[助手] 让我查看 git 日志以了解最近的工作。
[工具使用] <bash - git log --oneline -20>
[助手] 现在我要检查是否有 init.sh 脚本可以重启服务器。
<启动开发服务器>
[助手] 太好了！现在让我导航到应用程序并验证一些基本功能是否仍在工作。
<测试基本功能>
[助手] 根据我的验证测试，我可以看到基本功能运行良好。核心聊天功能、主题切换、对话加载和错误处理都正常工作。现在让我更全面地查看 tests.json 文件，以了解下一步需要实现的内容。
<开始新功能的开发>

代理故障模式和解决方案

总结长期运行的AI代理的四种常见故障模式和解决方案。

4、未来工作

这项研究展示了一种可能的解决方案集，在长期运行的代理框架中，使模型能够在许多上下文窗口中逐步推进。然而，仍然存在一些开放性问题。

最重要的是，尚不清楚单一的通用编码代理在不同上下文中表现最佳，还是通过多代理架构可以获得更好的性能。似乎合理的观点是，像测试代理、质量保证代理或代码清理代理这样的专业代理，可能在软件开发生命周期的子任务中做得更好。

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

原文链接：Effective harnesses for long-running agents

汇智网翻译整理，转载请标明出处