AI Agent 的一体化沙盒环境

lizhongxuan
0 阅读7分钟

agent-infra/sandbox（也称 AIO Sandbox）是一个面向 AI Agent 与开发者的多合一沙盒环境。它将 Browser、Shell、File、MCP、VSCode Server 集成到单个 Docker 容器中，让 Agent 在同一上下文里连续完成网页操作、代码执行、文件处理与结果输出。

aio-index.png

一、解决了什么痛点

传统 AI 方案通常将能力拆在多个沙盒中（代码执行、浏览器自动化、文件服务分离），会带来明显工程成本：

  • 中间文件跨系统搬运困难，链路又长又脆弱
  • 多套鉴权与状态管理，维护成本高
  • 观测与调试路径割裂，难以定位 Agent 运行状态

AIO Sandbox 的核心改进是“三个统一”：

  • 统一文件系统：浏览器下载文件可立即被 Shell/Jupyter/VSCode 读取
  • 统一入口：REST API 与 MCP 通过同一服务端口暴露
  • 统一交互面：VNC、VSCode、Dashboard、Terminal 可并行查看并接管

二、核心功能特性

1. 多维度接口与可视化交互

  • VNC 浏览器：支持通过远程桌面进行视觉上的浏览器交互。
  • VSCode Server：内置了完整的 Web 版 IDE，可以直接在浏览器中编写和调试沙盒内的代码。
  • Jupyter Notebook：提供交互式的 Python 代码执行环境。
  • Web Terminal：基于 WebSocket 的终端访问。
  • Preview Proxy：预览容器内前后端服务

2. 强大的浏览器自动化

  • VNC：可视化远程操作。
  • CDP (Chrome DevTools Protocol)：支持通过代码进行底层的可编程控制（例如结合 Playwright）。
  • MCP 工具：提供高级的浏览器自动化 API 封装（如导航、点击、输入等），极其适合大模型直接调用。

browser.png

3. 深度集成 MCP

内置 MCP 服务可直接供大模型调用：

  • Browser Server：maps、screenshot、click、type、scroll
  • File Server：read、write、list、search、replace
  • Shell Server：exec、create_session、kill
  • Markitdown Server：convert、extract_text、extract_images

mcp.png

4. 易于集成的 API 与 SDK

  • REST API：如 /v1/shell/exec、/v1/file/read、/v1/browser/screenshot
  • 官方 SDK：Python（agent-sandbox）、TypeScript/JavaScript（@agent-infra/sandbox）、Golang

三、架构拆解与底层逻辑

1. 架构层次

┌─────────────────────────────────────────────────────────────┐
│ 可视化层: VNC / Dashboard / VSCode Server                  │
├─────────────────────────────────────────────────────────────┤
│ 能力/执行层: Browser / Shell / File / Jupyter / Node.js    │
├─────────────────────────────────────────────────────────────┤
│ 协议/路由层: REST API + MCP Hub                            │
├─────────────────────────────────────────────────────────────┤
│ 核心数据层: Unified File System（共享目录）                │
├─────────────────────────────────────────────────────────────┤
│ 基础设施层: Docker 隔离 / 进程守护 / 端口代理              │
└─────────────────────────────────────────────────────────────┘

ar.png

2. 逻辑交互原理

示例任务：AI Agent 从网页抓取数据，生成图表并保存 Markdown。

  1. Agent 调用 Browser API 打开网页并抓取数据
  2. 数据直接落盘到统一目录（如 /home/gem/data.json）
  3. Agent 调用 Jupyter API 读取数据并生成 report.md、chart.png
  4. Agent 调用 Shell/File API 验证和返回结果
  5. 开发者可在 VNC/VSCode 全程观察

data_flow.png

3. 底层机制

  • 进程守护与编排（Supervisor）：统一拉起和监控多服务进程
  • 虚拟显示与图形桥接（Xvfb + NoVNC）：浏览器画面可视化
  • 统一命名空间（Namespaces）：同一用户和目录视图实现文件共享
  • 网关与 IPC（API Gateway + PTY/Subprocess）：单入口高效路由
  • 安全边界（Seccomp + Docker Namespace）：容器内隔离执行

四、快速上手指南

1. 启动容器

确保已安装 Docker（建议至少 2GB 可用内存）：

docker run --security-opt seccomp=unconfined --rm -it -p 8080:8080 ghcr.io/agent-infra/sandbox:latest

2. 启动后入口

  • Dashboard: http://localhost:8080/index.html
  • VNC: http://localhost:8080/vnc/index.html?autoconnect=true
  • VSCode Server: http://localhost:8080/code-server/
  • API Docs: http://localhost:8080/v1/docs
  • MCP Hub: http://localhost:8080/mcp

3. Python SDK 极简示例

安装 SDK：

pip install agent-sandbox

代码示例：

from agent_sandbox import Sandbox

c = Sandbox(base_url="http://localhost:8080")
ctx = c.sandbox.get_context()
home = ctx.data.home_dir

c.shell.exec_command(command=f"echo 'hello sandbox' > {home}/demo.txt")
content = c.file.read_file(file=f"{home}/demo.txt")
print(content.data.content)

五、Agent 应用如何集成 AIO Sandbox

在实际项目中，Agent 集成 AIO Sandbox 通常有两条路线：MCP 接入 和 SDK/API 接入。
选型原则很简单：如果你是“大模型驱动工具调用”，优先 MCP；如果你是“业务后端精细编排”，优先 SDK/API。

1. 路线 A：通过 MCP 接入（最适合通用 Agent 框架）

适用场景：

  • 你希望让 LLM 直接使用浏览器、终端、文件工具
  • 你使用了支持 MCP 的 Agent 运行时或客户端

接入步骤：

  1. 启动 AIO Sandbox，确保 http://localhost:8080/mcp 可访问
  2. 在 Agent 配置中注册 MCP Server 地址
  3. 给模型声明可用工具（browser/file/shell/markitdown）
  4. 在系统提示词中定义工具使用边界（允许哪些命令、哪些目录可写）
  5. 通过任务回放验证：网页抓取 -> 文件落盘 -> 代码处理 -> 结果回传

最小 MCP 配置示意（伪代码）：

{
  "mcpServers": {
    "aio-sandbox": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

2. 路线 B：通过 SDK/API 接入（最适合业务系统深度集成）

适用场景：

  • 你要把沙盒能力集成到自己的后端服务
  • 你需要会话管理、任务编排、权限策略、审计日志

推荐做法：

  1. 在业务后端封装一个 SandboxClient（屏蔽底层 API 细节）
  2. 每个任务分配独立工作目录：/home/gem/workflows/{task_id}
  3. 通过 session_id 维持长任务上下文（shell/jupyter）
  4. 把关键过程标准化为四步：fetch -> transform -> verify -> deliver
  5. 将命令、文件读写、结果摘要写入审计日志

Python 集成示例（服务侧）：

from agent_sandbox import Sandbox

class SandboxExecutor:
    def __init__(self, base_url="http://localhost:8080"):
        self.client = Sandbox(base_url=base_url)
        self.home = self.client.sandbox.get_context().data.home_dir

    def run_task(self, task_id: str, url: str):
        workdir = f"{self.home}/workflows/{task_id}"
        self.client.shell.exec_command(command=f"mkdir -p {workdir}")
        # 这里可以继续串联 browser/file/jupyter 能力
        # 示例：落一个任务说明文件
        self.client.file.write_file(
            file=f"{workdir}/task.md",
            content=f"# Task\nsource: {url}\n"
        )
        return {"task_id": task_id, "workdir": workdir}

3. 推荐集成架构（生产实践）

  • Agent Orchestrator：任务拆解、状态机、重试控制
  • Sandbox Adapter：统一封装 MCP/SDK 调用
  • Policy Layer：命令白名单、路径白名单、资源限额
  • Artifact Store：归档 logs/、report.md、chart.png 等产物

建议把 AIO Sandbox 当作“受控执行层”，而不是把业务逻辑直接写进沙盒容器。

4. 集成时的关键治理点

  • 权限最小化：限制可执行命令和可写目录
  • 数据边界：任务级目录隔离，避免跨任务污染
  • 可观测性：记录每次 tool call 的输入摘要、耗时、退出码
  • 可恢复性：每个阶段落盘 checkpoint，失败可续跑
  • 人工接管：保留 VNC/VSCode 入口用于调试与应急处理

六、工程落地与进阶实践

1. 生产化部署基线（Docker Compose）

version: "3.8"
services:
  sandbox:
    image: ghcr.io/agent-infra/sandbox:latest
    container_name: aio-sandbox
    security_opt:
      - seccomp:unconfined
    shm_size: "2gb"
    ports:
      - "8080:8080"
    volumes:
      - ./workspace:/home/gem/workspace
    environment:
      WORKSPACE: /home/gem/workspace
      TZ: Asia/Shanghai
    restart: unless-stopped

2. 多 Agent 协作模式（Orchestrator Pattern）

推荐“编排者 + 工作者”模式：

  • Worker A（Browser）：网页抓取
  • Worker B（Code）：Jupyter/Shell 数据处理
  • Worker C（Writer）：汇总输出

建议统一工件目录：/home/gem/workflows/{task_id}，并在每一步写 checkpoint，避免长任务中断后全量重跑。

agent.png

3. 安全与治理边界

由于启用了 seccomp=unconfined，需要配套控制：

  • 禁止挂载宿主机敏感目录（尤其 /var/run/docker.sock、/etc）
  • API/MCP 建议放在受控内网，不直接暴露公网
  • 高风险任务建议短生命周期容器执行

4. 常见坑位与排查

浏览器崩溃

  • 检查内存和 shm_size: 2gb
  • 确认 --security-opt seccomp=unconfined

找不到文件

  • 避免硬编码路径
  • 使用 sandbox.get_context().data.home_dir 获取 home 目录

本地服务页面预览失败

  • 前端优先走 /absproxy/{port}/
  • 后端 API 走 /proxy/{port}/
  • 确认服务监听地址为 0.0.0.0

长任务中断

  • 为 shell/jupyter 设置稳定 session_id
  • 每阶段落盘中间结果

总结

AIO Sandbox 通过“浏览器 + 代码执行 + 文件系统 + MCP + 人工可视化接管”的整合模式，为 AI Agent 提供了可工程化落地的一站式执行底座，尤其适合 Agent 研究、PoC 验证和复杂自动化工作流。

参考链接

avatar
文章
阅读
粉丝