PPIO Sandbox 提供为 AI Agent 设计的隔离、有状态的执行环境。它支持运行代码、安装依赖、访问文件、使用浏览器,并能跨会话保留状态,而无需管理基础设施。
简介
PPIO Sandbox 是一个面向 AI Agent 的托管执行环境,适用于需要运行代码、使用浏览器、处理文件并跨会话保留状态的场景。它为每个 Agent 提供隔离的运行时,而无需你管理基础设施。核心概念
Sandbox
供 Agent 执行任务的隔离执行环境。每个 Sandbox 都拥有自己的文件系统和运行时,Agent 可以在其中运行命令、管理文件、安装依赖,并处理基于浏览器的工作流。生命周期
- Running — Sandbox 处于活跃状态,可以执行命令并对外提供连接。
- Paused — Sandbox 被挂起;其文件系统和内存状态会被保留,计算资源停止计费。它可以恢复回 Running 状态(通常约 1 秒)。
- Killed — Sandbox 被终止,其资源被释放。已终止的 Sandbox 无法恢复。
- 超时(Timeout) — Sandbox 的最长生命周期。它从创建时开始倒计时,与活动无关;到期后 Sandbox 默认会被停止,也可以通过相应的生命周期配置改为暂停。参见超时处理。
- 空闲超时(Idle timeout) — 仅当在配置的时长内没有任何客户端连接时触发,自动终止或暂停 Sandbox。参见空闲超时处理。
Template
定义 Sandbox 的初始环境。Template 通过预定义的依赖、配置和设置步骤,确保多个 Sandbox 之间环境的一致性。Snapshot
Snapshot 将 Sandbox 的当前状态保存为可复用的环境。当你已经配置好 Sandbox、安装了依赖或生成了需要复用的文件时,Snapshot 非常有用。新的 Sandbox 可以基于 Snapshot 创建,无需重复相同的设置步骤。Secret
Secret 是在 PPIO Sandbox 中安全存储和使用敏感值（如 API 密钥、令牌和密码）的方式。它在当前团队范围内加密管理，让 Sandbox 中运行的代码无需在源代码、Snapshot 或环境变量中硬编码凭证，即可向外部服务进行身份验证。何时使用 PPIO Sandbox
适用于需要隔离环境来执行任务、维护状态或复用已准备好的环境的工作负载。常见使用场景包括:- 运行代码、安装软件包并执行测试的编码 Agent
- 自动化 Web 工作流的浏览器 Agent
- 处理文件并生成报告的数据分析 Agent
- 需要大量隔离环境的研究或 RL 工作负载
区域
PPIO 目前提供两个区域的访问方式:
v2 区域在 v1 的基础上新增了 Secret 密钥、Snapshot 快照等能力，功能更加完善。推荐优先使用 v2 区域。
本文档的 SDK 和 CLI 同时兼容 v1 和 v2 区域。如果想使用 v2 区域,需要配置环境变量
PPIO_DOMAIN: