AI Feeds
开源项目

open-agents

开源构建云端 coding agent 的参考应用模板，提供完整的三层架构：Web UI、agent 工作流和隔离沙箱。亮点在于 agent 与沙箱分离设计，利用 Vercel Workflow SDK 实现持久化、可恢复的长时间运行任务，支持 GitHub 集成自动化代码修改和 PR。适合想在 Vercel 上快速部署 AI 编程助手的开发者。

README

Open Agents

一键部署到 Vercel

Open Agents 是一个开源参考应用，用于在 Vercel 上构建和运行后台编码代理（background coding agents）。它包含 Web UI、代理运行时（agent runtime）、沙箱编排（sandbox orchestration）以及所需的 GitHub 集成——让你只需从提示到代码变更，无需始终开着笔记本。

此仓库适合 fork 和修改，不应视为黑盒。

这是什么

Open Agents 是一个三层系统：

Web -> 代理工作流 -> 沙箱虚拟机
  • Web 应用处理认证、会话、聊天的流式 UI。
  • 代理在 Vercel 上作为持久化工作流（durable workflow）运行。
  • 沙箱是执行环境：文件系统、Shell、Git、开发服务器和预览端口。

关键架构决策：代理不是沙箱

代理不在虚拟机内部运行。它在沙箱外部运行，通过文件读写、编辑、搜索和 Shell 命令等工具与沙箱交互。

这种分离是本项目的核心要点：

  • 代理执行不与单个请求生命周期绑定
  • 沙箱生命周期可以独立休眠和恢复
  • 模型/供应商选择与沙箱实现可以分别演进
  • 虚拟机保持为纯执行环境，而不是成为控制平面

当前能力

  • 基于聊天的编码代理，具备文件、搜索、Shell、任务、技能和 Web 工具
  • 支持 Workflow SDK 的持久化多步执行：运行、流式输出和取消
  • 基于快照的隔离 Vercel 沙箱，支持恢复
  • 仓库克隆和分支操作（在沙箱内）
  • 运行成功后可选择自动提交、推送和创建 PR
  • 通过只读链接共享会话
  • 可选通过 ElevenLabs 转录进行语音输入

运行时说明

一些有助于理解当前实现的细节：

  • 聊天请求会启动一个工作流运行，而不是内联执行代理。
  • 每次代理交互可以横跨多个持久化的工作流步骤。
  • 活跃的运行可以通过重新连接到现有工作流的流式输出来恢复。
  • 沙箱使用基础快照，暴露端口 3000、5173、4321 和 8000，并在一段时间不活动后休眠。
  • 支持自动提交和自动 PR，但这是偏好驱动的功能，并非始终开启的行为。

环境变量

完整列表见 apps/web/.env.example。概述如下：

最小运行环境

POSTGRES_URL=
BETTER_AUTH_SECRET=

登录必需（Vercel OAuth）

NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=
VERCEL_APP_CLIENT_SECRET=

GitHub 仓库访问、推送和 PR 必需

NEXT_PUBLIC_GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_APP_ID=
GITHUB_APP_PRIVATE_KEY=
NEXT_PUBLIC_GITHUB_APP_SLUG=
GITHUB_WEBHOOK_SECRET=

可选

REDIS_URL=                                      # 技能元数据缓存（回退到内存）
KV_URL=                                         # Vercel KV 缓存（回退到内存）
VERCEL_PROJECT_PRODUCTION_URL=                  # 规范的生产 URL
NEXT_PUBLIC_VERCEL_PROJECT_PRODUCTION_URL=      # 公开的规范生产 URL
VERCEL_SANDBOX_BASE_SNAPSHOT_ID=                # 覆盖默认沙箱快照
ELEVENLABS_API_KEY=                             # 语音转录

在 Vercel 上部署自己的副本

  1. Fork 此仓库。

  2. 将仓库导入 Vercel。如果你使用上方的部署按钮，Neon Postgres 会自动配置。

  3. 生成用于会话签名的密钥：

    openssl rand -base64 32   # BETTER_AUTH_SECRET

  4. 在 Vercel 项目设置中添加环境变量：

    POSTGRES_URL=
BETTER_AUTH_SECRET=

  5. 首次部署以获得稳定的生产 URL。

  6. 创建一个 Vercel OAuth 应用，回调 URL 为：

    https://YOUR_DOMAIN/api/auth/callback/vercel

  7. 添加以下环境变量并重新部署：

    NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=
VERCEL_APP_CLIENT_SECRET=

  8. 如果你想获得完整的 GitHub 编码代理流程，请创建一个 GitHub App，配置：

    • 主页 URL：https://YOUR_DOMAIN
    • 回调 URL：https://YOUR_DOMAIN/api/auth/callback/github
    • 设置 URL：https://YOUR_DOMAIN/api/github/app/callback

    在 GitHub App 设置中：

    • 使用 GitHub App 的 Client ID 和 Client Secret 作为 NEXT_PUBLIC_GITHUB_CLIENT_ID 和 GITHUB_CLIENT_SECRET
    • 如果你想使组织安装正常工作，请将应用设置为公开

  9. 添加 GitHub App 的环境变量并重新部署。

  10. 可选添加 Redis/KV 和规范的生产 URL 变量。

本地设置

  1. 安装依赖：

    bun install

  2. 创建本地环境文件：

    cp apps/web/.env.example apps/web/.env

  3. 在 apps/web/.env 中填入必要的值。

  4. 启动应用：

    bun run web

如果你已有关联的 Vercel 项目，可以通过 vc env pull 在本地拉取环境变量。

OAuth 和集成设置

Vercel OAuth

认证由 Better Auth 处理，Vercel 和 GitHub 作为社交登录提供商。所有认证路由均由 /api/auth/[...all] 通配路由处理。

创建一个 Vercel OAuth 应用，使用以下回调：

https://YOUR_DOMAIN/api/auth/callback/vercel

本地开发时使用：

http://localhost:3000/api/auth/callback/vercel

然后设置：

NEXT_PUBLIC_VERCEL_APP_CLIENT_ID=...
VERCEL_APP_CLIENT_SECRET=...

GitHub App

你不需要单独的 GitHub OAuth 应用。Open Agents 将 GitHub App 的 OAuth 凭据作为 Better Auth 社交登录提供商，并使用该 App 的安装令牌访问仓库。

创建一个基于安装的 GitHub App 用于仓库访问，配置：

  • 主页 URL：https://YOUR_DOMAIN
  • 回调 URL：https://YOUR_DOMAIN/api/auth/callback/github
  • 设置 URL：https://YOUR_DOMAIN/api/github/app/callback
  • 如果你想使组织安装正常工作，请将应用设置为公开

本地开发时，使用 http://localhost:3000 作为主页 URL，http://localhost:3000/api/auth/callback/github 作为回调 URL，http://localhost:3000/api/github/app/callback 作为设置 URL。

然后设置：

NEXT_PUBLIC_GITHUB_CLIENT_ID=...   # GitHub App Client ID
GITHUB_CLIENT_SECRET=...           # GitHub App Client Secret
GITHUB_APP_ID=...
GITHUB_APP_PRIVATE_KEY=...
NEXT_PUBLIC_GITHUB_APP_SLUG=...
GITHUB_WEBHOOK_SECRET=...

GITHUB_APP_PRIVATE_KEY 可以存储为带有转义换行符的 PEM 内容，或 base64 编码的 PEM。

常用命令

bun run web                # 运行开发服务器
bun run check              # lint + 格式检查
bun run fix                # lint + 格式修复
bun run typecheck          # 对所有包进行类型检查
bun run ci                 # 完整 CI：检查、类型检查、测试、迁移检查
bun run sandbox:snapshot-base  # 刷新沙箱基础快照

仓库结构

apps/web         Next.js 应用、工作流、认证、聊天 UI
packages/agent   代理实现、工具、子代理、技能
packages/sandbox 沙箱抽象及 Vercel 沙箱集成
packages/shared  共享工具
开源项目vercel-labs2026-05-07原文

相关内容