|
| 1 | +--- |
| 2 | +catalog_title: Sprites |
| 3 | +catalog_description: Persistent, stateful Linux sandboxes with checkpoint and restore for agent code execution |
| 4 | +catalog_icon: /integrations/assets/sprites.png |
| 5 | +catalog_tags: ["code"] |
| 6 | +--- |
| 7 | + |
| 8 | +# Sprites plugin for ADK |
| 9 | + |
| 10 | +<div class="language-support-tag"> |
| 11 | + <span class="lst-supported">Supported in ADK</span><span class="lst-python">Python</span> |
| 12 | +</div> |
| 13 | + |
| 14 | +The [Sprites ADK plugin](https://github.com/superfly/sprites-adk) connects your |
| 15 | +ADK agent to [Sprites](https://sprites.dev) — persistent, stateful Linux |
| 16 | +sandboxes from [Fly.io](https://fly.io). Unlike ephemeral sandboxes, a Sprite |
| 17 | +keeps its filesystem, installed packages, and running processes between |
| 18 | +sessions, and it can **checkpoint and restore** its entire state — so your |
| 19 | +agent can snapshot the environment before a risky change and roll back if it |
| 20 | +goes wrong. |
| 21 | + |
| 22 | +## Use cases |
| 23 | + |
| 24 | +- **Persistent development environments**: A named Sprite is reused across |
| 25 | + sessions — packages and files from earlier runs are still there, so |
| 26 | + long-running projects don't rebuild the environment from scratch each time. |
| 27 | + |
| 28 | +- **Secure code execution**: Run agent-generated Python, JavaScript, or bash in |
| 29 | + an isolated microVM instead of on the host machine. |
| 30 | + |
| 31 | +- **Safe experimentation**: Checkpoint the whole environment before package |
| 32 | + upgrades, migrations, or bulk edits, then restore it if the change breaks |
| 33 | + things. |
| 34 | + |
| 35 | +- **File workflows**: Write scripts and data into the sandbox, run them, and |
| 36 | + read the results back. |
| 37 | + |
| 38 | +## Prerequisites |
| 39 | + |
| 40 | +- A [Sprites](https://sprites.dev) account |
| 41 | +- A Sprites API token (set as the `SPRITES_TOKEN` environment variable) |
| 42 | + |
| 43 | +## Installation |
| 44 | + |
| 45 | +```bash |
| 46 | +pip install sprites-adk |
| 47 | +``` |
| 48 | + |
| 49 | +## Use with agent |
| 50 | + |
| 51 | +```python |
| 52 | +from sprites_adk import SpritesPlugin |
| 53 | +from google.adk.agents import Agent |
| 54 | +from google.adk.runners import InMemoryRunner |
| 55 | + |
| 56 | +# SpritesPlugin() gives each run a fresh sandbox; SpritesPlugin(sprite_name="my-project") |
| 57 | +# reuses one persistent environment across sessions. |
| 58 | +plugin = SpritesPlugin( |
| 59 | + # token="your-sprites-token" # Or set the SPRITES_TOKEN environment variable |
| 60 | +) |
| 61 | + |
| 62 | +root_agent = Agent( |
| 63 | + model="gemini-flash-latest", |
| 64 | + name="sandbox_agent", |
| 65 | + instruction="Run code and commands in the Sprite sandbox, not locally.", |
| 66 | + tools=plugin.get_tools(), |
| 67 | +) |
| 68 | + |
| 69 | +# Register the plugin on the runner so its lifecycle callbacks and cleanup run. |
| 70 | +runner = InMemoryRunner(agent=root_agent, plugins=[plugin]) |
| 71 | +``` |
| 72 | + |
| 73 | +## Available tools |
| 74 | + |
| 75 | +Tool | Description |
| 76 | +---- | ----------- |
| 77 | +`execute_command_in_sprite` | Run a shell command in the sandbox |
| 78 | +`execute_code_in_sprite` | Execute Python, JavaScript, or bash code |
| 79 | +`write_file_to_sprite` | Write a text file into the sandbox |
| 80 | +`read_file_from_sprite` | Read a text file from the sandbox |
| 81 | +`create_sprite_checkpoint` | Snapshot the entire environment (filesystem, packages, processes) |
| 82 | +`list_sprite_checkpoints` | List available checkpoints |
| 83 | +`restore_sprite_checkpoint` | Roll back to a checkpoint (destructive; requires confirmation) |
| 84 | + |
| 85 | +## Additional resources |
| 86 | + |
| 87 | +- [sprites-adk on PyPI](https://pypi.org/project/sprites-adk/) |
| 88 | +- [sprites-adk on GitHub](https://github.com/superfly/sprites-adk) |
| 89 | +- [Sprites documentation](https://docs.sprites.dev) |
0 commit comments