AgentScope Runtime工具沙箱入门:让AI安全执行Python与Shell代码

原创2026-10-24 19:23:441,918 阅读

AgentScope Runtime工具沙箱入门:让AI安全执行Python与Shell代码

AgentScope Runtime 是一个生产级的智能体应用运行时框架,其核心能力之一就是工具沙箱化(Tool Sandboxing):AI Agent 的 Python 代码和 Shell 命令都在隔离的 Docker 容器里执行,即使代码出错或"失控",也不会影响你的本机系统。本文将带你完成工具沙箱的安装配置,并在 5 分钟内跑通第一段隔离执行的代码。

🤔 为什么 AI Agent 需要沙箱?

当大模型驱动的智能体(Agent)学会"动手干活"——调用工具、执行代码、操作浏览器时,一个现实问题就来了:AI 生成的代码不一定安全。

  • 一段错误的 rm 命令可能删掉关键文件
  • 一个失控的循环可能占满 CPU 和内存
  • Agent 访问敏感数据时存在泄露风险

AgentScope Runtime 的思路是:把工具执行放进一个加固的隔离环境。沙箱本质是一个预装了 Python 运行时的 Docker 容器,AI 所有的代码执行、文件读写都被限制在其中,用完即销毁。这也是该项目被称为"生产级"运行时的重要原因之一 🛡️

📦 沙箱环境一键安装步骤

沙箱本地运行基于 Docker(可选配 gVisor 增强隔离,也可通过环境变量 CONTAINER_DEPLOYMENT 切换 BoxLite 等后端)。

前提条件:

  • Python 3.10 或更高版本
  • 已安装并启动 Docker

第 1 步:安装框架

pip install agentscope-runtime

第 2 步:拉取基础沙箱镜像

不同功能对应不同镜像,基础沙箱(执行 Python/Shell)只需要 runtime-sandbox-base:

docker pull agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-base:latest \
  && docker tag agentscope-registry.ap-southeast-1.cr.aliyuncs.com/agentscope/runtime-sandbox-base:latest \
  agentscope/runtime-sandbox-base:latest

💡 如果后续还要用浏览器自动化、文件操作等能力,可再拉取 runtime-sandbox-browser、runtime-sandbox-filesystem 等镜像;也支持从 Dockerfile 自行构建,见 cookbook/zh/sandbox/advanced.md。

第 3 步:验证安装

调用 run_ipython_cell 执行一句话,就能确认一切就绪:

from agentscope_runtime.sandbox import BaseSandbox

with BaseSandbox() as sandbox:
    result = sandbox.run_ipython_cell(code="print('Setup successful!')")
    print(result)

🚀 3 分钟在沙箱里执行 Python 与 Shell 代码

准备工作完成后,BaseSandbox 就提供了两个最核心的工具方法:

方法 作用
run_ipython_cell(code) 在沙箱的 IPython 环境中执行 Python 代码
run_shell_command(command) 在沙箱中执行 Shell 命令

最小示例(同步版):

from agentscope_runtime.sandbox import BaseSandbox

with BaseSandbox() as box:
    print(box.list_tools())                            # 列出所有可用工具
    print(box.run_ipython_cell(code="print('你好')"))  # 执行 Python 代码
    print(box.run_shell_command(command="echo hello")) # 执行 Shell 命令

几个值得注意的设计:

  • 上下文管理:with BaseSandbox() as box 会自动完成"创建容器 → 执行 → 销毁容器"的全生命周期,不会残留孤儿容器。
  • 同步与异步双版本:每种沙箱都有异步类(如 BaseSandboxAsync),在异步服务中可并发执行工具调用而不阻塞,适合高并发 Agent 应用。
  • MCP 兼容:工具调用结果遵循模型上下文协议(MCP)格式,可无缝对接各类 Agent 框架。

相关实现在 src/agentscope_runtime/sandbox/box/base/base_sandbox.py,镜像构建定义见 src/agentscope_runtime/sandbox/box/base/Dockerfile。

🧩 不止 Python/Shell:一图看懂沙箱家族

基础沙箱只是起点,AgentScope Runtime 为不同工具场景提供了完整的沙箱体系:

沙箱类型 适用场景 代表工具
BaseSandbox Python 代码、Shell 命令 run_ipython_cell、run_shell_command
GuiSandbox 图形桌面操作(鼠标/键盘/截图) computer_use
FilesystemSandbox 文件读写、目录管理 read_file、write_file
BrowserSandbox 浏览器自动化、网页爬取 browser_navigate、browser_click
MobileSandbox Android 模拟器上的移动操作 mobile_tap、mobile_swipe
AgentbaySandbox 基于云服务的远程沙箱,无需本地 Docker 多环境类型

它们都从统一的 SDK 导入,用法模式完全一致:

from agentscope_runtime.sandbox import GuiSandbox, BrowserSandbox, FilesystemSandbox

完整工具列表(浏览器工具、文件系统工具等 40+ 个方法)可参考 cookbook/zh/sandbox/sandbox.md。

🏢 生产部署:连接远程沙箱服务

本地 Docker 适合开发调试;生产环境推荐把沙箱部署到远端服务器或 K8s 集群,客户端代码几乎不用改:

# 在服务器上用一条命令启动沙箱服务
runtime-sandbox-server
# 本地代码只需指定远程地址
with BaseSandbox(base_url="http://your_IP_address:8000") as box:
    print(box.run_ipython_cell(code="print('hi')"))

这种"本地开发、远端执行"的模式特别适合:多客户端共享同一沙箱、把计算密集型任务分离到专用服务器、在资源受限的笔记本上开发。更进一步,SandboxService 还能按 session_id 管理沙箱生命周期并复用同一沙箱实例(会话中定义的变量不会丢),详见 src/agentscope_runtime/engine/services/sandbox/sandbox_service.py。

⚠️ 常见问题与排查指南

1. Docker 连接错误

docker.errors.DockerException: Error while fetching server API version

通常是 Python SDK 找不到 Docker 服务。如果你用 Colima,需要显式指定 socket:

export DOCKER_HOST=unix://$HOME/.colima/docker.sock

2. 沙箱启动超时

TimeoutError: Runtime service did not start within the specified timeout.

说明容器内健康检查失败。可以 docker ps 找到对应容器,进入 /var/log 查看 agentscope_runtime.err.log 等日志定位原因。

3. Apple 芯片(M1/M2)兼容性

建议在 x86 镜像运行时启用 Rosetta 2(Docker Desktop 或 colima start --vm-type=vz --vz-rosetta)。

更多排查细节见 cookbook/zh/sandbox/troubleshooting.md。

📚 总结

你想做的事 用什么
安全执行 Python/Shell BaseSandbox
浏览器自动化 BrowserSandbox
文件操作 FilesystemSandbox
多用户/生产环境 远程沙箱服务 + SandboxService

AgentScope Runtime 的工具沙箱把"AI 安全执行代码"这件事做到了开箱即用:一行 pip install 安装框架、一个 Docker 镜像完成隔离、几行代码即可在沙箱里安全运行 Python 与 Shell。对于正在构建 Agent 应用的开发者,这是通往生产环境的第一块基石 🧱

登录后查看全文
agentscope-runtime