Agent Sandbox

English | 中文

为 AI Agent 打造的云沙箱 —— 秒级创建、执行、管理隔离环境。

Agent Sandbox 是基于阿里云函数计算（FC）Agent Sandbox 服务的 Python SDK，定位是运行时客户端： 创建、使用、销毁沙箱。模板的构建和部署由 CLI 的 abx template build|deploy 完成。SDK 的方法名参考了 E2B， 方便 E2B 代码迁移，但它不是 E2B 的直接替代品（见从 E2B 迁移）。

本仓库（python-sdk）包含 Python SDK，以两个版本同步发布的 PyPI 分发包提供。命令行工具 abx 是独立的 Node.js 项目，位于 cli 仓库（见相关：abx CLI）。

两个分发包共享 agent_sandbox 命名空间（client 提供 agent_sandbox/__init__.py，server 只包含 agent_sandbox/server/），并以相同版本号同步发布。

Client SDK 跑在你的机器上：创建沙箱并使用它。说明见 Client SDK。示例在 examples/quickstart/、examples/compat-demos/、examples/agents/、examples/scenarios/。

Server SDK 跑在沙箱镜像里面：镜像启动的 HTTP 服务。说明见 Server SDK。示例是 examples/templates/python-hello/commands.py 和 examples/templates/agents-cli/commands.py。

Client SDK

• 异步优先 —— Sandbox.create()，Shell 执行、代码解释、文件读写、端口转发、WebSocket 流。
• 三种执行原语 —— sandbox.commands.run()（裸 Shell）、sandbox.run_code()（代码解释器）、sandbox.run("name", **kwargs)（调用 Server SDK 注册的命令）。
• MCP Server —— 将沙箱操作暴露为 MCP 工具，供 LLM Agent 调用。
• 声明式装饰器 —— @sandbox 将普通函数变为远程沙箱执行，自动序列化。
• 会话持久化 —— 跨运行保存和恢复沙箱状态。
• E2B 风格方法名 —— agent_sandbox.compat 覆盖一部分 E2B 表面，见从 E2B 迁移。

Server SDK

• 镜像内 HTTP 服务 —— commands.py 导入 agent_sandbox.server 并调用 start(9000)。
• 注册命令 —— @command 函数变成路由，Client SDK 用 sandbox.run 调用。
• Agents API —— 沙箱里的 Codex 与 Qwen Code HTTP 会话。CLI 按需安装。说明见 Agents API。
• 模板 —— 镜像和 template.yaml 用 abx template build|deploy 构建和部署。

安装

# 仅核心客户端 SDK
pip install agent-sandbox

# 完整安装（MCP + 快速 JSON + 会话 + 声明式 + server）
pip install "agent-sandbox[all]"

# 容器侧运行时（安装到你的沙箱镜像内）
pip install agent-sandbox-server
pip install playwright                       # 仅在启用 browser 能力组时需要

# 开发环境（在仓库根目录执行；含两个包的测试与 lint 工具）
pip install -e ./server-sdk -e "./client-sdk[dev]"

agent-sandbox 依赖同版本的 agent-sandbox-server，因此 pip install agent-sandbox 同样会提供 agent_sandbox.server（@sandbox 装饰器的 server 代理在本地需要它）。[server] extra 作为无害的别名保留。

abx CLI 不再属于 Python 包（不再有 [cli] extra，也没有 abx 控制台脚本），由 cli 仓库分发（见相关：abx CLI）。

快速开始

import asyncio
from agent_sandbox import Sandbox

async def main():
    async with await Sandbox.create(template="python-base") as sandbox:

        # 1. 裸 Shell —— sandbox.commands.run(cmd)
        proc = await sandbox.commands.run("echo 'Hello from sandbox!'")
        print(proc.stdout)          # Hello from sandbox!
        print(proc.exit_code)       # 0

        # 2. 代码解释器 —— sandbox.run_code(code)
        result = await sandbox.run_code("print(2 ** 10)")
        print(result.text)          # 1024

        # 3. 命名命令 —— sandbox.run(name, **kwargs)
        #    向沙箱内 SandboxServer 发送 POST /commands/hello
        greeting = await sandbox.run("hello", name="Alice")
        print(greeting)             # 注册函数的返回值

        # 4. 文件操作
        await sandbox.files.write("/tmp/data.txt", "content")
        content = await sandbox.files.read("/tmp/data.txt")

        # 5. 端口访问
        url = sandbox.network.get_url(3000)

asyncio.run(main())

执行 API

三种执行方法，分别对应不同场景：

命名命令只有一种机制：服务端注册命令。在模板里用 @sandbox.register（或 CommandRegistry）注册， sandbox.run("name", **kwargs) 向沙箱内 SandboxServer 发送 POST /commands/name。名字不存在抛 CommandNotFoundError；await sandbox.list_commands() 列出 server 已注册的命令。见声明式用法。

环境变量： envd 使用直接执行（direct exec）—— Shell 特性（$VAR 展开、管道、重定向）需要 sh -c '...'。用 printenv VAR 读取变量值。详见环境变量指南（中文） | Environment Variables (EN)。

模板

官方与社区模板统一维护在 alibaba-agent-sandbox/awesome-templates 仓库——模板内容、索引与发布的唯一真源。该索引由 abx template search|install 命令使用 （见相关：abx CLI）；模板遵循的 template.yaml 契约见 Template YAML 规范。

examples/templates/ 仅保留一个最小的 python-hello **测试夹具（fixture）**用于离线测试，并非模板发布真源。夹具契约与索引行为 （缓存、离线回退、锁定版本）详见 examples/templates/README.md。

架构

graph TB
    L5["L5 Agent — MCP Server、Agents API 客户端"]
    L4["L4 Declarative — @sandbox 装饰器"]
    L3["L3 API — Sandbox、Files、Code、Commands"]
    L2["L2 Protocol — envd REST + WebSocket"]
    L1["L1 Transport — HTTP/2、API Key、AK/SK"]
    GW["阿里云函数计算 FC"]

    L5 --> L4 --> L3 --> L2 --> L1 --> GW

低层不引用高层。完整设计文档：docs/zh/design/architecture.md。

文档

完整文档索引：docs/README.md（双语导航）

教程与指南

参考手册

设计与架构

其他资源

相关：abx CLI

命令行工具 abx（@agent-sandbox/cli，Node.js）在 cli 仓库中开发， 与本 SDK 共享沙箱、模板与凭证。其安装方式、命令参考、教程、MCP Server 命令以及 Agent Skill（SKILL.md） 均在该仓库中维护：

• CLI README —— 安装（npm install -g @agent-sandbox/cli）
• CLI 教程 · CLI 参考
• Agent Skill 安装与分发

贡献

欢迎贡献！请阅读 贡献指南 了解详情。

许可证

Apache-2.0 —— 版权信息见 NOTICE。