Sprites plugin for ADK¶

Supported in ADKPython

The Sprites ADK plugin connects your ADK agent to Sprites — persistent, stateful Linux sandboxes from Fly.io. Unlike ephemeral sandboxes, a Sprite keeps its filesystem, installed packages, and running processes between sessions, and it can checkpoint and restore its entire state — so your agent can snapshot the environment before a risky change and roll back if it goes wrong.

Use cases¶

Persistent development environments: A named Sprite is reused across sessions — packages and files from earlier runs are still there, so long-running projects don't rebuild the environment from scratch each time.
Secure code execution: Run agent-generated Python, JavaScript, or bash in an isolated microVM instead of on the host machine.
Safe experimentation: Checkpoint the whole environment before package upgrades, migrations, or bulk edits, then restore it if the change breaks things.
File workflows: Write scripts and data into the sandbox, run them, and read the results back.

Prerequisites¶

A Sprites account
A Sprites API token (set as the SPRITES_TOKEN environment variable)

Installation¶

pip install sprites-adk

Use with agent¶

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

# SpritesPlugin() gives each run a fresh sandbox; SpritesPlugin(sprite_name="my-project")
# reuses one persistent environment across sessions.
plugin = SpritesPlugin(
  # token="your-sprites-token"  # Or set the SPRITES_TOKEN environment variable
)

root_agent = Agent(
    model="gemini-flash-latest",
    name="sandbox_agent",
    instruction="Run code and commands in the Sprite sandbox, not locally.",
    tools=plugin.get_tools(),
)

# Register the plugin on the runner so its lifecycle callbacks and cleanup run.
runner = InMemoryRunner(agent=root_agent, plugins=[plugin])

Available tools¶

Tool	Description
`execute_command_in_sprite`	Run a shell command in the sandbox
`execute_code_in_sprite`	Execute Python, JavaScript, or bash code
`write_file_to_sprite`	Write a text file into the sandbox
`read_file_from_sprite`	Read a text file from the sandbox
`create_sprite_checkpoint`	Snapshot the entire environment (filesystem, packages, processes)
`list_sprite_checkpoints`	List available checkpoints
`restore_sprite_checkpoint`	Roll back to a checkpoint (destructive; requires confirmation)