AgentScope Runtime沙箱服务完全指南:SandboxService三步实现沙箱复用与生命周期管理
AgentScope Runtime沙箱服务完全指南:SandboxService三步实现沙箱复用与生命周期管理
AgentScope Runtime 是面向生产环境的智能体运行时框架,其中的 SandboxService 沙箱服务为每个用户会话提供隔离的工具执行环境,核心能力是沙箱复用与生命周期管理:同一会话多轮对话自动复用已有沙箱,会话结束自动释放资源,避免容器泄漏。本文将带你快速掌握它的原理、用法和最佳实践。
一、SandboxService 是什么?为什么需要它?
智能体(Agent)执行工具时——跑 Python 代码、操作浏览器、读写文件——必须在一个安全隔离的容器环境里进行,这就是"沙箱"。
如果每次调用都重新创建容器,启动慢、资源浪费;如果从不释放,容器又会无限堆积。SandboxService 正是解决这个问题的核心组件:
| 核心能力 | 说明 |
|---|---|
| 🔄 沙箱复用 | 同一 session_id 再次连接时,直接复用已创建的沙箱,无需冷启动 |
| 🧵 会话隔离 | 按 session_id + user_id 复合键隔离环境,多用户互不干扰 |
| 📦 多类型支持 | 支持 base、browser、gui、filesystem、mobile 等多种沙箱类型 |
| 🚦 生命周期管理 | start() / stop() / health() 标准生命周期接口,优雅停机自动排水释放 |
核心实现位于 sandbox_service.py,官方教程可参考 sandbox_service.md。
二、沙箱复用是如何工作的?
这是 SandboxService 最巧妙的设计,理解它只需看懂 connect() 方法的判断逻辑:
connect(session_id, user_id, sandbox_types)
│
▼
拼复合键 session_ctx_id = "session_id_user_id"
│
▼
该会话已有沙箱?
├─ 有 → 直接连接到已有环境(复用,秒级返回)
└─ 无 → 从预热池创建新沙箱(create_from_pool)
- 复用判断:sandbox_service.py 中,
connect()先查询会话映射(get_session_mapping),命中则走_connect_existing_environment直接连上旧容器;未命中才走_create_new_environment创建新环境。 - 预热池加速:新建沙箱时优先从预热容器池出队(sandbox_manager.py 的
create_from_pool),出队的容器是预先启动好的,还会校验镜像版本与运行状态,失效容器会自动丢弃重建——所以"创建"往往也快于冷启动。 - 会话隔离:
user_id参与复合键拼接(sandbox_service.py),不同用户即使session_id相同也会得到各自的独立沙箱。
三、快速上手:三步接入沙箱服务
SandboxService 实现了标准的 Service 生命周期接口(定义于 base.py),支持异步上下文管理器写法,三步即可接入:
from agentscope_runtime.engine.services.sandbox import SandboxService
# 1. 创建并启动服务(嵌入式模式,无需外部依赖)
sandbox_service = SandboxService()
await sandbox_service.start()
# 2. 连接沙箱:首轮创建,后续轮次自动复用
sandboxes = sandbox_service.connect(
session_id="Chat1001",
user_id="User1",
sandbox_types=["browser"],
)
# 3. 会话结束,显式释放资源
sandbox_service.release(session_id="Chat1001", user_id="User1")
三个方法各司其职:
connect():连接或创建沙箱,是复用的入口release():手动释放指定会话的所有沙箱start()/stop()/health():服务级生命周期与健康检查
四、嵌入式 vs 远程:两种运行模式怎么选?
SandboxService 的构造参数决定了运行模式(sandbox_service.py):
| 对比项 | 嵌入式模式 base_url=None |
远程 API 模式 |
|---|---|---|
| 适用场景 | 本地开发、单机调试 | 生产部署、多进程/多机共享 |
| 配置 | 零配置,开箱即用 | base_url="http://host:8000" + bearer_token |
| 资源归属 | 随进程退出而释放 | 沙箱可存活于服务进程之外,跨进程复用 |
| 扩展性 | 单机 | 可配合 Redis 做分布式状态共享 |
远程模式下,服务端通过 runtime-sandbox-server 命令启动,支持 Docker、K8s、gVisor、函数计算等多种容器后端,配置项(预热池大小 POOL_SIZE、心跳超时、实例上限等)详见 advanced.md。
用环境变量创建服务:SandboxServiceFactory
不想在代码里硬编码配置?SandboxServiceFactory 支持纯环境变量驱动(sandbox_service_factory.py):
export SANDBOX_BACKEND=default
export SANDBOX_DEFAULT_BASE_URL="http://sandbox-server:8000"
export SANDBOX_DEFAULT_BEARER_TOKEN="your-token"
service = await SandboxServiceFactory.create()
它的底层机制在 service_factory.py:按 SANDBOX_ 前缀扫描环境变量自动填充参数,且代码传参优先级高于环境变量,还支持 register_backend 注册自定义后端——切换环境只需改环境变量,业务代码零改动。单测行为可参考 test_sandbox_service_factory.py。
五、生命周期管理细节:如何防止沙箱泄漏?
这是 SandboxService 区别于"裸用 SDK"的关键价值,共三道防线:
1️⃣ 优雅停机排水(drain_on_stop)
stop() 默认会遍历本服务持有的全部会话映射,逐一释放所有非 AgentBay 沙箱(sandbox_service.py):
drain_on_stop=True(默认):停机时清空资源,防泄漏drain_on_stop=False:沙箱交给外部管理、需比进程活得更久时使用
嵌入式模式下,stop() 还会额外调用 manager_api.cleanup() 拆除本进程拉起的全部容器。
2️⃣ 心跳超时自动回收(Reap)
沙箱服务端内置 watcher 后台线程,周期性执行心跳扫描(heartbeat_mixin.py、sandbox_manager.py):
- 会话的每次工具调用都会刷新心跳(
touch_session装饰器自动完成) - 超过
HEARTBEAT_TIMEOUT(默认 300 秒)无活动的会话被判定闲置,容器标记为RECYCLED - 会话再次活跃时自动恢复(restore),文件数据通过挂载目录/对象存储保留——即"回收不丢数据"
- 预热池自动补齐,
RELEASED状态的过期记录自动 GC
3️⃣ 实例数上限保护
MAX_SANDBOX_INSTANCES 可限制活跃沙箱总量,超限的创建请求会被直接拒绝(sandbox_manager.py),防止流量高峰打爆资源。
六、把沙箱注册为 Agent 工具(推荐用法)
官方不建议业务代码直接操作底层沙箱 API,而是通过 adapter 把沙箱方法包装成工具函数,注册进 Agent 的 Toolkit:
from agentscope_runtime.adapters.agentscope.tools import sandbox_tool_adapter
toolkit = Toolkit()
for tool in [
sandboxes[0].browser_navigate,
sandboxes[0].browser_take_screenshot,
]:
toolkit.register_tool_function(sandbox_tool_adapter(tool))
这样做的三个好处:屏蔽底层沙箱 API 细节、由 Runner/Engine 统一托管生命周期、切换运行模式或沙箱类型时业务逻辑零改动。适配器源码见 tool 适配器。
七、选型建议与最佳实践
| 场景 | 推荐配置 |
|---|---|
| 快速原型 / 本地开发 | 嵌入式模式 + base / browser 类型按需创建 |
| 生产多用户部署 | 远程模式 + bearer_token 认证 + Redis 共享状态 |
| 高隔离要求 | 每用户独立沙箱,会话结束及时调用 release() |
| 高并发低延迟 | 调大 POOL_SIZE 预热池,让新请求"秒分配" |
最佳实践清单:
- ✅ 长会话用固定
session_id,让框架自动复用沙箱,减少冷启动 - ✅ 用户维度的隔离务必传入
user_id - ✅ 会话明确结束时调用
release(),不要只依赖心跳回收 - ✅ 沙箱需比进程存活更久时,设
drain_on_stop=False并交由远程管理器托管 - ✅
AGENTBAY类型沙箱在对象销毁时自动清理,无需手动 release(sandbox_service.py)
总结
SandboxService 用 connect / release 两个核心方法 + 标准生命周期接口,把沙箱复用(会话映射命中即复用)、会话隔离(复合键区分用户)和资源回收(停机排水 + 心跳回收 + 实例上限三道防线)封装成开箱即用的服务。配合 SandboxServiceFactory 的环境变量配置能力,同一套业务代码可以在本地嵌入式开发与生产远程部署之间无缝切换——这正是它作为 AgentScope Runtime 沙箱服务核心组件的价值所在。