在现代软件开发中，如何让 AI 代理高效地执行代码修改、测试运行和 Pull Request 创建等异步任务，是一个系统工程难题。LangChain 开源的 Open-SWE 项目给出了自己的答案：基于 Deep Agents 框架构建，采用云沙箱隔离环境，结合子代理并行编排与中间件驱动的任务流程控制，实现了一个生产级别的异步编程代理架构。本文将深入剖析其核心实现，为你拆解可复用的工程设计模式。
一、Agent Harness：基于 Deep Agents 的编排基石
Open-SWE 并没有从零构建代理框架，而是采用了「组合优于 fork」的策略，直接基于 Deep Agents 框架搭建 Agent Harness。这种设计理念与 Ramp 公司基于 OpenCode 构建内部工具的做法一脉相承，其核心优势在于两点：一是能够持续接收上游的功能更新和安全补丁，二是允许组织根据自身需求定制编排逻辑、工具集和中间件。
从代码层面来看，创建一个 Deep Agent 的核心模式非常简洁：指定模型（如 anthropic:claude-opus-4-6）、构造系统提示词、注入工具列表、选择沙箱后端、配置中间件链路。这种声明式的配置方式，使得代理的行为可以被版本化管理和持续迭代。系统提示词的构造通常会传入代码仓库的上下文信息，让模型能够理解项目的架构规范和编码约定。
这种架构选择的深层逻辑在于：AI 代理技术仍处于快速演进阶段，今天的「最佳实践」可能明天就会被新的范式颠覆。通过基于成熟框架进行组合而非自行构建，组织可以在享受底层框架更新的同时，将定制精力集中在业务相关的工具和流程设计上。
二、云沙箱架构：任务隔离与生命周期管理
2.1 隔离原则与多后端支持
Open-SWE 的核心安全假设是「先隔离，再赋予充分权限」。每个任务都运行在独立的云沙箱中 —— 一个具有完整 shell 访问权限的远程 Linux 环境。代码仓库会被克隆到沙箱内，代理拥有完全的运行权限，但所有操作都被限制在这个隔离边界内，不会对生产环境造成任何影响。这种设计思路与 Stripe、Ramp、 Coinbase 等公司在内部编码代理上的实践完全一致。
项目开箱即支持四种沙箱提供者：Modal、Daytona、Runloop 和 LangSmith。这种可插拔的架构设计，让组织可以根据成本、延迟、隐私合规等自身约束条件选择最合适的方案。例如，对数据敏感的组织可能倾向于选择支持私有部署的方案，而初创公司则可能优先考虑成本更低的 serverless 方案。官方提供了完整的自定义指南，指导你如何接入自建的沙箱后端。
2.2 持久化与自动恢复
沙箱的生命周期管理是异步任务调度的关键细节。Open-SWE 实现了两个重要特性：第一是持久化沙箱 —— 同一个线程（thread）内的多次消息交互会复用同一个沙箱，这意味着代理可以在一个连贯的环境中持续工作，而不必每次交互都从头初始化；第二是自动重建 —— 如果沙箱因为网络波动或其他原因变得不可达，系统会自动创建新的沙箱实例，确保任务不会因为临时故障而中断。
对于并发任务处理，每个任务拥有独立的沙箱实例，天然支持并行执行而无需排队等待。这种设计使得系统可以充分利用云资源的弹性能力，同时保证任务之间的完全隔离。
三、子代理编排：并行任务的精细化控制
3.1 Task 工具的代理生成机制
在复杂任务场景下，单一代理往往难以高效处理多方面的子任务。Open-SWE 通过 Deep Agents 原生提供的 task 工具来解决这个问题，允许主代理动态生成子代理（child agents）。每个子代理不仅拥有独立的执行上下文，还有自己的中间件栈和待办事项列表（todo list）。
这种设计的实际价值在于：主代理可以将一个大型任务分解为多个独立的子任务，然后并行委托给子代理处理。例如，一个代码审查任务可以被拆解为「检查单元测试覆盖率」「扫描安全漏洞」「验证代码风格」等多个子任务，每个子任务在独立的子代理中并行执行，最终由主代理汇总结果。
3.2 与传统并行模式的对比
与传统的任务队列（如 Celery 或 RQ）相比，子代理编排的核心优势在于智能化的任务分解和上下文感知。传统任务队列需要预先定义任务类型和参数，而子代理模式可以根据任务的实际状态动态决定下一步操作。同时，每个子代理可以访问完整的项目上下文，而不仅仅是任务队列中的序列化数据。
四、中间件系统：任务流程的确定性控制
4.1 消息队列注入中间件
check_message_queue_before_model 是 Open-SWE 最具特色的中间件之一。它允许用户在代理运行过程中发送补充消息 —— 无论是 Linear 上的新评论还是 Slack 线程中的新消息，都会在代理下一次模型调用前被注入到上下文中。这意味着你可以「实时指挥」一个正在工作的代理，而不是只能等待它完成后再重新启动。
这种机制的工程实现依赖于确定性线程 ID 的设计：每一次任务触发（无论是通过 Slack、Mention、Linear Issue 还是 GitHub PR Comment）都会基于上下文信息生成一个稳定的线程 ID，后续所有相关消息都会被路由到同一个正在运行的代理实例。
4.2 自动 PR 创建安全网
open_pr_if_needed 中间件充当了代理行为的「安全网」。它的职责很简单：如果代理完成工作后没有自行创建 PR，就由中间件代为执行提交并打开 Draft PR。这是一种将关键业务逻辑从 LLM 行为中剥离出来的策略 —— 即使模型的输出存在不确定性，核心的业务流程仍然能够得到保证。
这种设计思想与 Stripe 的「deterministic nodes」概念一脉相承：在 Agentic（代理行为）与 Deterministic（确定性逻辑）之间找到平衡，让 LLM 处理需要灵活判断的任务，而将必须执行的固定流程交给确定性代码。
4.3 工具错误处理
ToolErrorMiddleware 提供了统一的工具异常捕获和处理机制。在实际的代理运行中，工具调用失败是常态而非例外 —— 网络请求可能超时、文件权限可能不足、命令执行可能报错。中间件会在工具执行出错时进行预处理，可能包括重试、降级或者将错误信息格式化为模型可以理解的上下文。
五、工程化参数配置建议
5.1 沙箱选型参考
| 考量因素 | Modal | Daytona | Runloop | LangSmith |
|---|---|---|---|---|
| 冷启动延迟 | 中等 | 低 | 低 | 中等 |
| 成本模型 | 按计算时间 | 按实例 | 按会话 | 按调用量 |
| 私有部署 | 不支持 | 支持 | 支持 | 支持 |
| 适用场景 | 通用场景 | 快速迭代 | 企业级 | 调试与监控 |
5.2 中间件链路配置
对于一般规模的团队，建议采用「最小中间件集合」：保留 check_message_queue_before_model 以支持实时交互、保留 open_pr_if_needed 作为安全网、保留 ToolErrorMiddleware 处理异常。随着团队对代理行为的理解加深，可以逐步引入自定义中间件，例如添加代码质量检查、视觉验证或审批流程。
5.3 并发控制参数
在配置并行任务数量时，需要权衡两个因素：沙箱资源的成本和模型上下文窗口的限制。建议初始配置为每个并发任务分配独立的沙箱实例，但将并发数量控制在 3 到 5 个以内 —— 这考虑到当前大模型上下文窗口的实际限制，以及多任务同时运行带来的资源成本和管理复杂度。
六、总结
Open-SWE 展示了一套成熟的异步编程代理架构范式：通过云沙箱实现任务隔离与弹性资源利用，通过子代理机制支持复杂任务的并行分解，通过中间件系统将关键的确定性逻辑从 LLM 行为中解耦。对于希望构建内部编码代理的组织而言，这些设计模式可以直接作为架构决策的参考，而其模块化的设计也允许根据具体业务需求进行灵活定制。