> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SDKs and frameworks

These adapters let an application use Sprites as the execution environment for an agent.

## Before you begin

* Use an account with Sprites access and [create a token](https://sprites.dev/account). Replace the `'...'` placeholders below with your credentials.
* Install the Python or Node.js version required by your chosen integration below.
* Set the exact Sprites token variable shown for that integration; the variable names are not interchangeable.
* For examples that call a model, configure the model provider's credentials separately from the Sprites token.

## Hugging Face OpenEnv

[`openenv-sprites`](https://github.com/superfly/openenv-sprites) is an experimental Python provider that starts an OpenEnv environment in a fresh Sprite. It requires Python 3.10 or newer. Run the following commands in a Python project managed by `uv`.

```sh theme={null}
uv add openenv-sprites
env_url='git+https://huggingface.co/spaces/openenv/echo_env'
uv add "openenv-echo-env @ $env_url"
export SPRITES_API_TOKEN='...'
```

`SPRITE_TOKEN` is accepted as a legacy fallback. Save this Hugging Face Space example as `openenv_echo.py`:

```python theme={null}
from echo_env import EchoEnv
from openenv_sprites import SpritesProvider

provider = SpritesProvider(source="hf://openenv/echo_env")

with provider:
    base_url = provider.start_container()
    provider.wait_for_ready(base_url)

    with EchoEnv(base_url=base_url).sync() as env:
        result = env.reset()
        print(result)
```

Run `uv run python openenv_echo.py`; it should print the environment's reset result and exit without an error.

The provider accepts `hf://`, `https://`, and `git+https://` source identifiers, not arbitrary OCI images. It deletes the Sprite when the provider closes by default.

<Warning>
  This adapter is alpha software. Environment source and dependencies execute inside the Sprite, so only run sources you trust and do not put credentials in source URLs.
</Warning>

## Google ADK

The [`sprites-adk`](https://github.com/superfly/sprites-adk) package gives Google Agent Development Kit agents command, code, file, checkpoint, and restore tools backed by Sprites.

```sh theme={null}
pip install sprites-adk
export SPRITES_TOKEN='...'
```

This setup-only snippet adds the plugin's tools to an agent and registers its lifecycle callbacks on the runner. It does not send a prompt:

```python theme={null}
from google.adk.agents import Agent
from google.adk.runners import InMemoryRunner
from sprites_adk import SpritesPlugin

plugin = SpritesPlugin()

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

runner = InMemoryRunner(agent=root_agent, plugins=[plugin])
```

To send a prompt, follow the [runnable persistent-environment example](https://github.com/superfly/sprites-adk/blob/main/examples/persistent_environment.py). For a first check, ask it to run `pwd` and confirm the agent reports the sandbox's working directory. That example retains its named Sprite.

`SpritesPlugin()` creates an ephemeral Sprite. Pass `sprite_name="my-project"` to reuse a named Sprite across sessions. Model credentials, such as `GOOGLE_API_KEY`, remain separate from the Sprites token.

See the [official ADK integration page](https://adk.dev/integrations/sprites/) for the current tool list and examples.

## OpenAI Agents SDK

[`sprites-openai-agents`](https://github.com/superfly/sprites-openai-agents) implements the OpenAI Agents SDK sandbox provider interface. It requires Python 3.10 or newer.

```sh theme={null}
pip install sprites-openai-agents
export OPENAI_API_KEY='...'
export SPRITES_API_TOKEN='...'
```

Save this as `sprite_agent.py`. It creates a sandbox session and asks the agent to report its working directory:

```python theme={null}
import asyncio

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig
from agents.sandbox.capabilities import Shell
from sprites_openai_agents import SpritesSandboxClient, SpritesSandboxClientOptions


async def main():
    agent = SandboxAgent(
        name="Sprite assistant",
        instructions="Use the sandbox shell to inspect the workspace.",
        capabilities=[Shell()],
    )
    client = SpritesSandboxClient()
    sandbox = await client.create(options=SpritesSandboxClientOptions())

    async with sandbox:
        result = await Runner.run(
            agent,
            "Run pwd in the sandbox and report the working directory.",
            run_config=RunConfig(sandbox=SandboxRunConfig(session=sandbox)),
        )
        print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())
```

Run it with:

```sh theme={null}
python sprite_agent.py
```

A successful run prints the agent's report of the sandbox's working directory.

By default, cleanup deletes the ephemeral Sprite. Pass a `sprite_name` through `SpritesSandboxClientOptions` to attach to an existing persistent Sprite.

<Info>
  The Agents SDK sandbox provider API evolves quickly. The adapter declares a tested dependency range, so let your package manager resolve a compatible OpenAI Agents SDK version instead of overriding that range.
</Info>

## OpenRouter Agent SDK

The [Sprites adapter for OpenRouter Agent SDK](https://github.com/superfly/sprites-openrouter-sdk) is experimental and source-only. It requires Node.js 24 or newer and ESM.

<Warning>
  `@fly/sprites-openrouter` is only a proposed package name and is not published to npm. Clone and build the repository instead.
</Warning>

```sh theme={null}
git clone https://github.com/superfly/sprites-openrouter-sdk.git
cd sprites-openrouter-sdk
npm ci
npm run build
export SPRITES_TOKEN='...'
export OPENROUTER_API_KEY='...'
```

Save this as `sprite-agent.mjs` in the cloned repository's root. It connects a persistent workspace's tools to an OpenRouter model call:

```js theme={null}
import { SpritesClient } from '@fly/sprites'
import { OpenRouter, stepCountIs } from '@openrouter/agent'
import { createSpriteWorkspace } from './dist/index.js'

const sprites = new SpritesClient(process.env.SPRITES_TOKEN)
const openrouter = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY })

const workspace = await createSpriteWorkspace({
  target: {
    client: sprites,
    name: 'coding-project-123',
    create: 'if-missing',
    createOptions: { runtime: 'dev' },
  },
  cwd: '/workspace',
})

try {
  const result = openrouter.callModel({
    model: 'openai/gpt-5-mini',
    input: 'Run pwd in the sandbox and report the working directory.',
    tools: workspace.tools({ preset: 'minimal' }),
    stopWhen: stepCountIs(5),
  })
  console.log(await result.getText())
} finally {
  await workspace.close()
}
```

Run it from that repository root with Node.js 24 or newer:

```sh theme={null}
node sprite-agent.mjs
```

A successful run prints the agent's report of the sandbox's working directory.

`workspace.close()` releases adapter-local resources but preserves the Sprite. `workspace.destroy()` is the explicit infrastructure deletion operation.

## TanStack AI

TanStack AI provides a published Sprites sandbox provider with a durable filesystem, resume-by-ID, in-place checkpoints, and one proxied HTTP port. It requires Node.js 22.4 or newer.

```sh theme={null}
npm install @tanstack/ai @tanstack/ai-sandbox @tanstack/ai-sandbox-sprites
export SPRITES_API_KEY='...'
```

This setup-only snippet creates the provider; it does not start a sandbox or run an agent:

```ts theme={null}
import { spritesSandbox } from '@tanstack/ai-sandbox-sprites'

const sprites = spritesSandbox({
  apiKey: process.env.SPRITES_API_KEY,
})
```

For a complete app, follow [TanStack's runnable sandbox-web example](https://github.com/TanStack/ai/blob/main/examples/sandbox-web/README.md). It starts with Docker; use its "Swapping the stack" instructions and the Sprites port and bridge notes below when adapting it. On a successful first run, agent output streams and the generated app's preview opens.

Use it as the `provider` in a sandbox definition from `@tanstack/ai-sandbox`. A Sprite exposes one public HTTP port through the provider, defaulting to port 8080. Checkpoints belong to the existing Sprite and do not survive Sprite deletion.

Because the Sprite is remote, tools bridged from an application running on your laptop cannot call laptop `localhost` directly; use the bridge tunnel described in the [TanStack AI provider documentation](https://tanstack.com/ai/latest/docs/sandbox/providers#sprites).