Agent Sandbox Registry

python-sdk

Agent Sandbox — 设计文档索引

English

docs/zh/DESIGN.md

Agent Sandbox — 设计文档索引

版本：v2.0 | 最后更新：2026-09-24

本文档是 Agent Sandbox 所有设计文档的入口和索引。详细设计位于 design/ 目录下的各专题文档中。

项目概述

Agent Sandbox（PyPI 包名 agent-sandbox）是面向阿里云 FC Agent 沙箱服务的 Python SDK。它是运行时客户端：创建、使用、销毁沙箱；模板用 abx template build|deploy 构建和部署。方法名参考了 E2B，方便迁移，但它不是 E2B 的直接替代品（见从 E2B 迁移）。

本仓库包含 Python SDK，以两个版本同步发布的 PyPI 分发包提供——agent-sandbox（client-sdk/，导入 agent_sandbox）与 agent-sandbox-server（server-sdk/，导入 agent_sandbox.server，容器侧运行时）。abx CLI 是 cli 仓库中的 Node.js/TypeScript 项目，CLI 自己的设计与指南文档也在该仓库（见相关：abx CLI）。

核心设计原则

  1. 方法名参考 E2B，但不兼容 E2B — E2B 风格的方法名加一个小的迁移辅助 (from agent_sandbox.compat import Sandbox) 方便现有 E2B 用户迁移；线上协议和配置是平台自己的
  2. AI-First — MCP Server 是一等公民，编码 Agent 通过 Agents API 托管
  3. 零配置默认 — 开箱即用；从安装到第一个沙箱运行不超过 3 行代码

快速上手

pip install agent-sandbox
export ABX_SANDBOX_API_KEY=your-api-key

from agent_sandbox import Sandbox

async with await Sandbox.create(template="base") as sb:
    result = await sb.run_code("print('Hello, Agent Sandbox!')")
    print(result.text)

架构概览

SDK 采用严格分层架构 — 低层绝不导入高层：

graph TB
    subgraph Upper["上层"]
        Agent["Agent/MCP — MCP 服务器、工具定义"]
        Decl["Declarative — @sandbox 装饰器"]
        Compat["Compat — E2B 迁移辅助"]
    end
    subgraph Core["核心层"]
        L3["API — Sandbox、文件、代码、命令、网络、server 客户端"]
        L2["Protocol — 沙箱生命周期、文件系统、进程、终端、端口"]
        L1["Transport — HTTP、WebSocket、认证、编解码、流式传输"]
        L0["Models + Utils — Pydantic 模型、错误、配置、异步桥接"]
    end

    Agent --> L3
    Decl --> L3
    Compat --> L3
    L3 --> L2 --> L1 --> L0

完整架构分解详见架构设计。

设计专题索引

每个专题都有独立的设计文档，包含完整规范。

核心设计

专题 文档 摘要
系统架构 architecture.md 五层架构、层间依赖、双 API 层（Platform API vs Sandbox envd API）
SDK API 设计 sdk-api-design.md Sandbox 类、文件操作、代码执行、命令、网络、会话管理
沙箱类型体系 sandbox-types.md 临时沙箱（已实现）、持久沙箱（远期）、沙箱生命周期
提供方与凭证 providers-and-credentials.md 每个配置键一个环境变量、优先级、提供方插件（abx provider ...）、安装与信任模型、EPP/1 协议、E8xxx 错误；评审记录见 providers-and-credentials-review.md

模板

专题 文档 摘要
模板体系 template-system.md 模板分层、GitHub tarball 分发、template.yaml 规范、版本管理、模板市场架构

AI 与 Agent 集成

专题 文档 摘要
MCP Server mcp-server.md 7 个 P0 工具、STDIO 与 Streamable HTTP 传输、FC 部署产物、会话绑定
Agents API guide/agents-api.md 在沙箱里运行 Agent 的唯一方式：/v1/agents/**。基础镜像不预装 CLI

服务器与基础设施

专题 文档 摘要
Server API server-api.md Sandbox Server SDK 路由、能力组、Browser 实例架构

维护者设计文档（仅英文）

provider、capability、server-v2 与 agents-API 工作流的设计文档。它们没有中文对应版本。

专题 文档 摘要
Agents API agents-api.md、评审 在 Agent Sandbox 中托管编码 Agent
细粒度 capability fine-grained-capabilities.md、评审 agent-sandbox-server 与 template.yaml 中的 capability 范围与权限
客户端 / 服务端对齐 client-server-alignment.md 每条服务端路由与客户端的差距矩阵
基础镜像与 Server SDK base-image-and-server-sdk.md、CLI 跟进项 官方 FC Agent 沙箱基础镜像与 Server SDK；对 abx CLI 的确切修改规格
Server SDK v2 server-sdk-v2/ Server SDK 的目标操作模型设计（首页列出已实现与未实现部分）
OpenSandbox provider 调研 provider-opensandbox-mapping.md OpenSandbox provider 的 API 映射、配置键与测试计划
仓库布局 repository-layout.md python-sdk 与 cli 仓库的布局评审

实现状态

功能 状态 备注
SDK 核心（Sandbox、文件、命令、代码） 已实现
MCP Server（STDIO） 已实现 7 个 P0 工具
MCP Server（Streamable HTTP） 已实现 mcp_http.py
FC 部署产物应用 已实现 agent_sandbox.agent.mcp_http:asgi_app；产物由 CLI 的 abx mcp deploy 生成。见 mcp-server.md
模板 build/push/deploy 在 CLI 中 abx template build 与 abx template deploy；SDK 不构建模板
E2B 迁移辅助 已实现（部分） agent_sandbox.compat
每个配置键一个环境变量（SDK） 已实现 见配置参考；CLI 规格见 cli/docs/zh/design/providers-and-credentials-cli.md
提供方插件（SDK，python -m agent_sandbox.providers） 已实现 见提供方；CLI 的 abx provider 待实现
持久沙箱 远期 需底层平台支持
SandboxPool（预热池） 远期 需底层平台支持

相关资源

资源 位置
架构决策记录 (ADR) .agents/notes/
用户指南 docs/zh/guide/
API 参考 docs/zh/reference/
English design index docs/en/DESIGN.md

相关：abx CLI

abx CLI（Node.js / TypeScript，npm 包 @agent-sandbox/cli）的文档位于 cli 仓库，其设计索引是 DESIGN.md。与 SDK 读者最相关的是：CLI 架构、CLI 命令体系与模板目录。