Skip to content

ADK 的 Sprites 插件

在 ADK 中受支持Python

Sprites ADK 插件 将你的 ADK 智能体连接到 Sprites —— 来自 Fly.io 的持久化、有状态 Linux 沙箱。与临时沙箱不同，Sprite 会在会话之间保留其文件系统、已安装的软件包和正在运行的进程，并且可以 检查点和恢复 其完整状态——因此你的智能体可以在执行有风险的更改之前对环境进行快照，并在出错时回滚。

用例

  • 持久化开发环境：命名的 Sprite 可在多个会话之间复用——之前运行中安装的软件包和创建的文件仍然存在，因此长期项目无需每次都从头重建环境。

  • 安全的代码执行：在隔离的 microVM 中运行智能体生成的 Python、JavaScript 或 bash 代码，而不是在宿主机上运行。

  • 安全的实验：在进行软件包升级、迁移或批量编辑之前对整个环境创建检查点，如果更改导致问题则恢复到该检查点。

  • 文件工作流：将脚本和数据写入沙箱，运行它们，然后读取结果。

前置条件

  • 一个 Sprites 账户
  • 一个 Sprites API 令牌（设置为 SPRITES_TOKEN 环境变量）

安装

pip install sprites-adk

与智能体一起使用

from sprites_adk import SpritesPlugin
from google.adk.agents import Agent
from google.adk.runners import InMemoryRunner

# SpritesPlugin() 为每次运行提供全新的沙箱；
# SpritesPlugin(sprite_name="my-project") 在多个会话之间复用同一个持久化环境。
plugin = SpritesPlugin(
  # token="your-sprites-token"  # 或者设置 SPRITES_TOKEN 环境变量
)

root_agent = Agent(
    model="gemini-flash-latest",
    name="sandbox_agent",
    instruction="在 Sprite 沙箱中运行代码和命令，而不是在本地运行。",
    tools=plugin.get_tools(),
)

# 在运行器上注册插件，使其生命周期回调和清理操作正常运行。
runner = InMemoryRunner(agent=root_agent, plugins=[plugin])

可用工具

工具 描述
execute_command_in_sprite 在沙箱中运行 shell 命令
execute_code_in_sprite 执行 Python、JavaScript 或 bash 代码
write_file_to_sprite 将文本文件写入沙箱
read_file_from_sprite 从沙箱读取文本文件
create_sprite_checkpoint 对整个环境创建快照（文件系统、软件包、进程）
list_sprite_checkpoints 列出可用的检查点
restore_sprite_checkpoint 回滚到某个检查点（破坏性操作；需要确认）

更多资源