AI coding agent 正在从“本机命令行助手”走向“平台能力”。一旦你想在产品里批量运行 agent，问题就不只是模型选哪一个，而是：代码在哪个隔离环境里执行？如何复用镜像和依赖？怎样切换云端 sandbox？如何保留 streaming、approval、工具调用和多模态输入，而不是把 agent 降级成一次性的 --print 命令？

今天推荐的 TwillAI/agentbox-sdk 就是在处理这一层。它是一个 TypeScript SDK，用同一套 Agent / Sandbox API 把 Claude Code、OpenCode、Codex 和多种 sandbox provider 接起来。GitHub 页面当前显示项目约有 155 stars、15 forks、主要语言是 TypeScript、许可为 MIT，没有发布 GitHub release。通过 git 历史可见首个提交在 2026 年 4 月 7 日，最近一次提交在 2026 年 5 月 25 日；npm 上的 agentbox-sdk 最新版本为 0.1.315，发布时间为 2026 年 5 月 25 日。

项目概览

属性详情
仓库TwillAI/agentbox-sdk
Stars约 155
Forks15
主要语言TypeScript
许可MIT
首个提交2026 年 4 月 7 日
最近提交2026 年 5 月 25 日
GitHub release暂未发布
npm 最新版本0.1.315

它解决的是运行层问题

现在很多 AI coding 工具都假设用户在本机项目目录里启动 CLI。这个模式适合个人开发，但当你要把 agent 放进 Web 产品、内部平台、CI、评测系统或批量任务队列时，运行层会立刻变复杂。

你需要一个干净的工作目录，需要把代码 clone 进去，需要安装依赖，需要传入有限的密钥，需要暴露 preview port，需要在任务结束后销毁环境。有时你想用本机 Docker，有时想用 E2B、Modal、Daytona 或 Vercel 的云端沙箱。更麻烦的是，不同 agent 的启动方式、事件格式、approval 流程和 hook 机制并不一致。

AgentBox 的价值不在于再造一个新 agent，而是把这层差异收进 SDK。应用代码可以说“我要一个 sandbox，再在里面跑某个 agent”，而不是到处散落 provider 专用逻辑。

Agent 和 Sandbox 分开选

README 里最核心的设计是两个维度可以独立替换。

Agent provider 当前覆盖 Claude Code、OpenCode 和 Codex。Sandbox provider 当前覆盖 local Docker、E2B、Modal、Daytona 和 Vercel。也就是说，同一个上层流程可以先在本地 Docker 里跑 Claude Code，之后换成 E2B 里的 Codex，或者在 Modal 上测试 OpenCode，而不必重写业务代码。

这对做 agent 平台的人很有用。早期你可能只想在一台开发机上用 Docker 验证任务流；等到需要并发和隔离时，再换云端沙箱。模型和 agent CLI 也会变，今天用 Claude Code，明天可能要接 Codex 或 OpenCode。AgentBox 把这些变化点变成构造参数，而不是让它们渗进整个应用。

当然，抽象不会消灭差异。每个 sandbox provider 的鉴权、镜像、端口和生命周期仍然不同；每个 agent 的模型命名和能力边界也不同。AgentBox 更像是把差异放在明确位置，而不是承诺所有 provider 完全一样。

不是简单 shell out

AgentBox README 特别强调，它不是把 CLI 当成非交互命令跑一次。它会在 sandbox 里把 agent 作为 server process 启动，并通过 WebSocket 或 HTTP 通信。这样做的意义是保留完整的交互能力，包括 streaming events、approval flows、tool-use control 等。

这点是它和普通脚本封装的关键区别。很多平台一开始会用 child_process 调 CLI，再解析 stdout。这个办法很快能 demo，但 agent 真正进入产品后，stdout 字符串不够用。你需要知道一次运行的事件流、文本增量、工具调用、审批点、完成结果和错误状态。

AgentBox 提供 agent.run() 和 agent.stream() 两种入口。前者适合一次性任务，后者返回 async iterable，可以逐步处理 normalized events。对 Web UI 来说，这意味着前端可以实时显示 agent 输出；对后台队列来说，则可以记录事件、审计工具调用、在必要时中断或审批。

沙箱生命周期显式化

AgentBox 的 Sandbox 不会在构造时立刻创建真实环境。README 里要求先调用 findOrProvision()，后续的 run、gitClone、uploadAndRun、agent run 等操作都复用这个 sandbox。

这个小设计很重要。远端 sandbox 的创建可能很慢，也可能收费；有的场景希望复用已有环境，有的场景必须每次新建。把 attach / create 这一步显式化，可以让调用方掌握成本、并发和清理时机。

SDK 还把常见环境操作放进同一接口，例如 run()、runAsync()、gitClone()、uploadAndRun()、openPort()、getPreviewLink()、snapshot()、stop() 和 delete()。这让 agent 运行前后的准备和收尾更容易标准化。

如果你要构建“给用户开一个临时工作区，让 agent 修复 bug 并打开预览链接”的产品，这类生命周期接口比直接拼接 provider SDK 更省心。

Skills、sub-agents 和 MCP 也进了模型

AgentBox 不只处理“把 prompt 发给 agent”。README 还展示了 skills、sub-agents、MCP servers、自定义 slash commands、hooks 和多模态输入。

这些能力说明它面向的是较完整的 agent runtime，而不是简单任务执行器。你可以给 Claude Code 挂 GitHub repo 形式的 skill，也可以内嵌一小段 skill 文件；可以定义 reviewer 这类 sub-agent；可以把 filesystem 或远端服务作为 MCP server 接进去；也可以注册 /triage 这类自定义命令。

对应用开发者来说，这很现实。真正的 agent 产品往往需要一组固定工作流，而不是每次只塞一段 prompt。把这些工作流作为 SDK 参数传入，至少比在 prompt 里反复描述“你现在拥有某某工具和流程”更稳定。

镜像和 provider 迁移是重点

AgentBox 提供 image build CLI，可以用内置 preset 构建 sandbox image，也可以写 my-image.mjs 定义自己的镜像。README 示例里包含 Node base image、系统依赖、全局安装 pnpm / Claude Code、安装 Playwright 浏览器等步骤。

这部分看起来偏基础设施，但它往往决定 agent 平台能不能稳定跑。AI coding agent 不是纯推理服务，它需要 git、包管理器、编译器、浏览器、系统库、测试数据库，甚至项目特定工具链。如果每次运行都临时安装，速度和可重复性都会很差。

更有意思的是，README 说明 image build 会针对不同 provider 输出对应引用：本地 Docker tag、Modal image ID、E2B template 或 Daytona snapshot。也就是说，AgentBox 试图把“准备运行环境”也纳入可替换层，而不是只抽象任务调用。

适合什么场景

AgentBox 适合已经在搭建 agent 产品或内部平台的人，而不一定适合普通个人用户。

如果你只是偶尔在项目里打开 Codex 或 Claude Code，本机 CLI 已经足够。AgentBox 真正有价值的场景是：

  • 在 Web 应用里给用户启动隔离的 coding agent；
  • 在 CI 或评测系统里批量运行 agent；
  • 想在 Docker、E2B、Modal、Daytona、Vercel 之间切换执行环境；
  • 需要统一 Claude Code、OpenCode、Codex 的运行事件；
  • 想把 skills、MCP、sub-agents、hooks 作为平台配置管理；
  • 需要让 agent 生成代码后打开 preview port 或保存 snapshot。

换句话说，它更像 agent runtime SDK，而不是终端里的另一个聊天工具。

需要注意的边界

AgentBox 还很早期，版本仍在 0.1.x，GitHub release 也暂未发布。虽然 npm 上已经有连续版本，但如果要放进生产平台，建议先用单一 provider 和低风险任务验证。

另外，统一 API 并不等于完全无差别运行。README 已经能看到一些 provider 专属行为，例如 Vercel sandbox 需要在创建时声明端口，snapshot 的处理方式也不同。实际接入时仍要理解底层 provider 的限制、计费、冷启动、网络策略和凭据管理。

安全边界也不能省略。Agent 会在 sandbox 里执行代码和命令，传入的 API key、仓库权限、网络访问、preview port 都需要最小化配置。AgentBox 给的是承载结构，平台方仍然要设计权限模型、日志保留策略和清理机制。

总结

TwillAI/agentbox-sdk 把 AI coding agent 的一个关键问题摆到了台面上：当 agent 从个人 CLI 变成平台能力时，真正难的是运行环境、隔离、事件流和 provider 迁移。它用 TypeScript SDK 把 agent provider 和 sandbox provider 分成两个可替换维度，并把 streaming、approval、skills、MCP、hooks、preview 和 snapshot 等能力放进同一套接口。

它还不是成熟基础设施，但方向很实用。对于正在做 agent 平台、内部自动化、评测系统或多 provider 实验的团队，AgentBox 是一个值得关注的小众项目。

项目地址：https://github.com/TwillAI/agentbox-sdk