Skip to content

DESIGN.md

Latest commit

 

History

History
149 lines (109 loc) · 8.58 KB

DESIGN.md

File metadata and controls

149 lines (109 loc) · 8.58 KB
Raw

Agent Sandbox — 设计文档索引

版本：v2.0 | 最后更新：2026-10-16

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

项目概述

Agent Sandbox（PyPI 包名 agent-sandbox-client）是面向阿里云 FC Agent 沙箱服务的 Python SDK。它是运行时客户端：创建、使用、销毁沙箱；模板用 abx template build|deploy 构建和部署。方法名参考了 E2B，方便迁移，标准公开接口遵循阿里云支持的 E2B 行为契约（见从 E2B 迁移）。

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

核心设计原则

  1. 固定标准行为与显式 Provider 扩展 — 根目录 Sandbox 是同步客户端，AsyncSandbox 是异步客户端；标准与解释器客户端通过本项目维护的 MIT 源码移植遵循阿里云支持的 E2B 基线。Provider／Server／声明式扩展使用 ProviderSandbox；ABX_PROVIDER 不切换标准客户端协议。
  2. AI-First — MCP Server 是一等公民，编码 Agent 通过 Agents API 托管
  3. 明确连接配置 — 沿用既有阿里云 API Key、API URL 和沙箱域名；依赖后端条件的能力仍需实际启用。

快速上手

pip install agent-sandbox-client
export ABX_SANDBOX_API_KEY=your-api-key
from agent_sandbox import ProviderSandbox as Sandbox

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

当前内置运行通道：直接 HTTP 与迁移。

架构概览

原生 Provider 扩展采用下述分层；标准客户端使用独立的源码移植协议实现：

graph TB
    subgraph Upper["上层"]
        Agent["Agent/MCP — MCP 服务器、工具定义"]
        Decl["Declarative — @sandbox 装饰器"]
        Compat["compat — 标准客户端别名"]
        STD["Sandbox / AsyncSandbox / code_interpreter"]
    end
    subgraph Core["核心层"]
        L3["ProviderSandbox — 文件、代码、命令、网络、server 客户端"]
        PORT["_standard / interpreter — 维护的 MIT 源码移植"]
        L2["Protocol — 沙箱生命周期、文件系统、进程、终端、端口"]
        L1["Transport — HTTP、WebSocket、认证、编解码、流式传输"]
        L0["Models + Utils — Pydantic 模型、错误、配置、异步桥接"]
    end

    Agent --> L3
    Decl --> L3
    Compat --> STD --> PORT
    L3 --> L2 --> L1 --> L0
Loading

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

设计专题索引

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

核心设计

专题 文档 摘要
系统架构 architecture.md 标准客户端源码移植、原生 Provider 扩展分层及各自协议路径
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 实例架构

维护者设计文档

这些页面有中文副本，就在本目录。只有仓库布局仍是英文。

专题 文档 摘要
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 现行的 node 目录提供方和真实调用对照表
容器版 provider-alicloud-container.md ACS/ACK sandbox-manager，E2B 形状的 HTTP，不是极速版
CubeSandbox provider-cubesandbox.md CubeAPI 控制面
E2B provider-e2b.md E2B 云 API，api.e2b.app
提供方可用性 provider-readiness.md CubeSandbox、E2B、容器版在没有真实后端之前的逻辑审查
仓库布局 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 不构建模板
每个配置键一个环境变量（SDK） 已实现 见配置参考；CLI 规格见 cli/docs/zh/design/providers-and-credentials-cli.md
提供方插件（SDK，python -m agent_sandbox.providers） 已实现 见提供方。CLI 加载已安装的 node、exec 和 rest 插件（abx provider、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 命令体系与模板目录。