当业界大多数 AI 代理项目将代理逻辑直接嵌入虚拟机内部运行时，Vercel Labs 推出的 Open Agents 项目做出了一个截然不同的架构选择：代理并不运行在沙箱之中。这一设计决策看似反直觉，却解决了长期困扰云端代理系统的核心难题。本文将从架构原理出发，解析这一设计的技术价值，并给出可落地的部署参数建议。
三层架构：Web、代理工作流与沙箱的职责分离
Open Agents 采用经典的三层结构，从前到后依次是 Web 层、代理工作流层和沙箱执行层。Web 层负责身份验证、会话管理、聊天界面以及流式响应推送；代理层运行在 Vercel 的 Durable Workflow 之上，负责意图理解、工具调度和多步骤执行编排；沙箱层则是独立的虚拟机环境，提供文件系统、Shell、Git、开发服务器以及预览端口等完整的工作站能力。
这种职责分离的核心逻辑在于：每一层的生命周期、技术选型和扩展策略都应当独立演进。Web 层可以随用户交互模式变化而快速迭代，代理层的模型和提示词可以频繁调整，沙箱层的镜像和资源配置也能独立优化。如果代理逻辑与沙箱 runtime 深度绑定，任何一方的改动都会波及整体，系统的迭代速度将受到严重制约。
核心架构决策：代理不是沙箱
在传统的 AI 编程代理方案中，代理进程通常直接运行在沙箱虚拟机内部。这种模式的优势是部署简单、调试直观，但在生产环境中面临几个关键挑战。首先是请求生命周期的绑定问题：代理执行必须在一个 HTTP 请求的时间窗口内完成，无法支持长时间运行的多步骤任务。其次是沙箱状态管理的困难 —— 当代理意外终止或需要恢复执行时，沙箱的状态一致性很难保证。最后是资源隔离的模糊地带：代理逻辑与执行环境共享资源，容易引发 OOM 或资源争用。
Open Agents 将代理运行在沙箱外部，通过文件读取、编辑、搜索、Shell 命令等工具与沙箱进行交互。这种架构带来了几个显著优势：代理执行不再受限于单一请求的生命周期，可以跨多个持久化的工作流步骤继续执行；沙箱可以独立进行休眠和基于快照的恢复，代理侧无需感知底层状态迁移细节；模型和提供商的切换与沙箱实现完全解耦，团队可以在不修改执行环境的情况下实验不同的 LLM 方案。
具体实现上，每次聊天请求会触发一个工作流运行，而不是 inline 执行代理。代理的每个回合可以跨越多个持久化的工作流步骤，当前运行可以通过重新连接到已有工作流流来恢复。沙箱使用基础快照创建，支持端口 3000、5173、4321 和 8000 的暴露，并在 inactivity 之后自动进入休眠状态。
生产部署的关键参数与配置清单
部署 Open Agents 需要配置多层环境变量，以下是经过验证的核心参数组合。基础运行时必须配置 PostgreSQL 连接字符串和 Better Auth 的会话签名密钥，生成方式为 openssl rand -base64 32。如果使用 Vercel 官方的一键部署按钮，Neon Postgres 会自动 Provision，但生产环境建议验证连接池配置是否满足并发需求。
身份验证层面需要创建 Vercel OAuth 应用，回调地址设为 https://YOUR_DOMAIN/api/auth/callback/vercel，并在环境变量中填入 NEXT_PUBLIC_VERCEL_APP_CLIENT_ID 和 VERCEL_APP_CLIENT_SECRET。这是实现团队协作的基础，不配置将无法使用多用户功能。
如果需要完整的 GitHub 集成以实现从提示词到代码变更的完整流程，还需要创建 GitHub App。 Homepage URL 设为部署域名，Callback URL 为 https://YOUR_DOMAIN/api/auth/callback/github，Setup URL 为 https://YOUR_DOMAIN/api/github/app/callback。特别注意将 GitHub App 设为公开模式（public），否则组织级别的安装会出现权限问题。相关的环境变量包括 NEXT_PUBLIC_GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET、GITHUB_APP_ID、GITHUB_APP_PRIVATE_KEY、NEXT_PUBLIC_GITHUB_APP_SLUG 和 GITHUB_WEBHOOK_SECRET。其中 GITHUB_APP_PRIVATE_KEY 可以直接存储 PEM 内容（需要转义换行符）或使用 base64 编码格式。
可选配置中，Redis 或 Vercel KV 用于技能元数据的缓存，生产环境建议配置以避免内存泄漏问题。VERCEL_SANDBOX_BASE_SNAPSHOT_ID 可以覆盖默认的沙箱基础快照，适用于需要预装特定工具链的场景。如果启用语音输入功能，需配置 ELEVENLABS_API_KEY。
沙箱管理的技术细节与监控要点
沙箱是整个系统中资源消耗最大的组件，其配置直接影响成本和用户体验。Open Agents 的沙箱具备基于快照的恢复能力，这意味着每次启动新沙箱时会基于一个预定义的基础镜像创建，显著缩短了冷启动时间。开发团队可以通过 bun run sandbox:snapshot-base 命令刷新基础快照，集成新的工具或依赖。
沙箱暴露的端口映射也有明确的约定：3000 端口用于 Next.js 开发服务器，5173 适用于 Vite 生态，4321 对应 Astro，8000 则预留给了其他通用服务。代理层在执行过程中会根据任务类型自动选择合适的端口启动服务。这一设计使得代理可以同时运行多个服务并通过端口进行访问，而无需在沙箱内部运行复杂的进程管理逻辑。
生产环境中建议监控以下指标：沙箱的休眠与唤醒频率（过高说明任务调度可能存在问题）、单个任务执行的平均时长（超过阈值应触发告警）、沙箱内存使用峰值（用于评估快照大小的合理性）以及 GitHub API 调用配额（自动提交和 PR 创建功能会消耗可观的 API 额度）。
与现有方案的差异化定位
区别于年初发布的 agent-skills 示例（侧重本地开发环境和 Anthropic 金融服务的垂直场景），Open Agents 面向的是完整的云端代理产品化需求。它不仅仅是一个技术演示，而是一个可以 fork 并根据自身需求改编的生产级参考应用。从身份验证到会话共享，从代码提交到 PR 创建，整个交付链路都被纳入架构考量。对于希望快速构建内部编码代理的团队而言，这一模板提供了经过验证的基础设施，团队可以聚焦于代理行为和工具链的定制，而非底层 runtime 的重复建设。
资料来源：GitHub vercel-labs/open-agents