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. 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 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.

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:

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.

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.

Google ADK

The sprites-adk package gives Google Agent Development Kit agents command, code, file, checkpoint, and restore tools backed by Sprites.

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:

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. 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 for the current tool list and examples.

OpenAI Agents SDK

sprites-openai-agents implements the OpenAI Agents SDK sandbox provider interface. It requires Python 3.10 or newer.

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:

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:

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.

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.

OpenRouter Agent SDK

The Sprites adapter for OpenRouter Agent SDK is experimental and source-only. It requires Node.js 24 or newer and ESM.

Source installation for now

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

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:

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:

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.

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:

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. 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.