Agent Sandbox SDK — 文档中心

Agent Sandbox 是可切换提供方的沙箱 SDK。默认提供方是阿里云极速版（函数计算）。同一套 API 还有 Modal 风格的 @sandbox 装饰器，以及沙箱内的 Agents API（Codex 与 Qwen Code，按需安装 CLI）。

范围： 本仓库记录 Python SDK（agent-sandbox）与容器侧运行时（agent-sandbox-server）。abx CLI 是独立的 Node.js 项目，拥有自己的文档集；见相关：abx CLI。

设计文档

#	文档	说明
1	系统架构设计	六层分层架构总览、各层职责、目录结构
2	SDK API 设计	核心文档 — 两种使用范式、命令与错误模型、SDK 边界
3	沙箱类型体系	临时/持久/休眠三种模式、生命周期状态机、计费模型
4	MCP Server	7 个 P0 工具定义、会话绑定、STDIO 与 Streamable HTTP 传输、IDE 配置
5	模板体系	官方模板、自定义模板、sandbox.yaml 规范、版本管理、模板市场
6	Server API	容器内 HTTP Server 端点定义、42 端点、8 个能力组
7	Provider 与凭证	规范配置名、provider 插件、EPP/1

用户向的 Agents API 在托管代理（Codex 与 Qwen Code，CLI 按需安装）。其余维护者设计稿在 DESIGN.md 中索引。

这些页面是评审记录或目标设计，不是现行规范。

文档	说明
Client SDK	这一侧是什么，以及下面这些文档怎么串起来
快速开始	安装、配置、第一个沙箱
SDK 使用	命令、文件、代码解释器、命名命令
云上端到端练习	在默认提供方上跑 quickstart 与 compat-demos
认证配置	API Key / AK-SK
声明式用法	`@sandbox` 装饰器
MCP 集成	把沙箱操作交给 IDE
会话持久化	本地会话存储
E2B 迁移	从 E2B 迁移
提供方	选择、安装、编写提供方
环境变量	注入与沙箱内读取
故障排查	常见问题
对比	与 E2B、Modal、Docker Sandbox
命令与 SDK 对照	与 E2B、OpenSandbox 的命令和方法

文档	说明
Server SDK	这一侧是什么，以及 `commands.py` 怎么启动
模板编写	`template.yaml`、能力声明、注册命令、Dockerfile
模板服务器 HTTP API	`commands.py` 实际提供的路由
最佳实践	服务器不携带提供者、按需打开能力组
细粒度能力	按端点打开路由
文件与命令控制	限制路径和命令
Agents API	沙箱里的 Codex 与 Qwen Code HTTP 会话
托管代理	这些路由的拒绝和响应
构建与部署	`abx template build` 与 `abx template deploy`

测试如何算完成，见测试与完成定义。

文档	说明
API 参考	Client SDK 公开 API
配置参考	Client SDK 的环境变量、配置文件、凭证解析
错误码	E1xxx–E8xxx 错误码索引
template.yaml 规范	Server SDK 模板定义（`template.yaml`）
Server HTTP API	沙箱内 Server SDK 的 HTTP API
Agents API 参考	Server SDK 上每条 Agents 路由的参数与响应

文档	说明
完整设计文档	设计专题索引与实现状态

模板真源（awesome-templates）：alibaba-agent-sandbox/awesome-templates — 官方与社区模板内容、索引（awesome-templates.yaml）与发布的唯一真源
English Documentation：English docs