mirror of
https://github.com/google/adk-docs.git
synced 2026-09-14 16:16:59 +08:00
Alex Ezell
46a56dcb8c
* Add Sprites integration Adds the Sprites integration page and catalog icon. Sprites (https://sprites.dev) are persistent, stateful Linux sandboxes from Fly.io with checkpoint/restore, via the sprites-adk plugin (pip install sprites-adk). * Refine Sprites page: benefit-forward use cases, precise wording * Address review: functional heading + runner registration in example --------- Co-authored-by: Kristopher Overholt <koverholt@google.com>
90 lines
3.1 KiB
Markdown
90 lines
3.1 KiB
Markdown
---
|
|
catalog_title: Sprites
|
|
catalog_description: Persistent, stateful Linux sandboxes with checkpoint and restore for agent code execution
|
|
catalog_icon: /integrations/assets/sprites.png
|
|
catalog_tags: ["code"]
|
|
---
|
|
|
|
# Sprites plugin for ADK
|
|
|
|
<div class="language-support-tag">
|
|
<span class="lst-supported">Supported in ADK</span><span class="lst-python">Python</span>
|
|
</div>
|
|
|
|
The [Sprites ADK plugin](https://github.com/superfly/sprites-adk) connects your
|
|
ADK agent to [Sprites](https://sprites.dev) — persistent, stateful Linux
|
|
sandboxes from [Fly.io](https://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](https://sprites.dev) account
|
|
- A Sprites API token (set as the `SPRITES_TOKEN` environment variable)
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install sprites-adk
|
|
```
|
|
|
|
## Use with agent
|
|
|
|
```python
|
|
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)
|
|
|
|
## Additional resources
|
|
|
|
- [sprites-adk on PyPI](https://pypi.org/project/sprites-adk/)
|
|
- [sprites-adk on GitHub](https://github.com/superfly/sprites-adk)
|
|
- [Sprites documentation](https://docs.sprites.dev)
|