feat: add Sprites as a sandbox provider

docs/ref/extensions/sandbox/sprites/sandbox.md

@@ -0,0 +1,3 @@
+# `Sandbox`
+
+::: agents.extensions.sandbox.sprites.sandbox

docs/sandbox/clients.md

@@ -96,6 +96,7 @@ For provider-specific setup notes and links for the checked-in extension example
 | `E2BSandboxClient` | `openai-agents[e2b]` | [E2B runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/e2b_runner.py) |
 | `ModalSandboxClient` | `openai-agents[modal]` | [Modal runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/modal_runner.py) |
 | `RunloopSandboxClient` | `openai-agents[runloop]` | [Runloop runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/runloop/runner.py) |
+| `SpritesSandboxClient` | `openai-agents[sprites]` | [Sprites runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/sprites_runner.py) |
 | `VercelSandboxClient` | `openai-agents[vercel]` | [Vercel runner](https://github.com/openai/openai-agents-python/blob/main/examples/sandbox/extensions/vercel_runner.py) |
 
 </div>
@@ -113,6 +114,7 @@ Hosted sandbox clients expose provider-specific mount strategies. Choose the bac
 | `DaytonaSandboxClient` | Supports rclone-backed cloud storage mounts with `DaytonaCloudBucketMountStrategy`; use it with `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, and `BoxMount`. |
 | `E2BSandboxClient` | Supports rclone-backed cloud storage mounts with `E2BCloudBucketMountStrategy`; use it with `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, and `BoxMount`. |
 | `RunloopSandboxClient` | Supports rclone-backed cloud storage mounts with `RunloopCloudBucketMountStrategy`; use it with `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, and `BoxMount`. |
+| `SpritesSandboxClient` | Supports rclone-backed cloud storage mounts with `SpritesCloudBucketMountStrategy`; use it with `S3Mount`, `GCSMount`, `R2Mount`, `AzureBlobMount`, and `BoxMount`. The strategy lazy-installs `rclone` and `fuse` via `sudo apt-get` if the sprite image does not preinstall them. Sprites exposes at most one external HTTP port per sprite (declared as a service in the sprite image); other ports must be reverse-proxied inside the VM. |
 | `VercelSandboxClient` | No hosted-specific mount strategy is currently exposed. Use manifest files, repos, or other workspace inputs instead. |
 
 </div>
@@ -130,6 +132,7 @@ The table below summarizes which remote storage entries each backend can mount d
 | `DaytonaSandboxClient` | ✓ | ✓ | ✓ | ✓ | ✓ | - |
 | `E2BSandboxClient` | ✓ | ✓ | ✓ | ✓ | ✓ | - |
 | `RunloopSandboxClient` | ✓ | ✓ | ✓ | ✓ | ✓ | - |
+| `SpritesSandboxClient` | ✓ | ✓ | ✓ | ✓ | ✓ | - |
 | `VercelSandboxClient` | - | - | - | - | - | - |
 
 </div>

examples/sandbox/extensions/README.md

@@ -7,7 +7,7 @@ They intentionally keep the flow simple:
 
 1. Build a tiny manifest in memory.
 2. Create a `SandboxAgent` that inspects that workspace through one shell tool.
-3. Run the agent against E2B, Modal, Daytona, Cloudflare, Runloop, Blaxel, or Vercel.
+3. Run the agent against E2B, Modal, Daytona, Cloudflare, Runloop, Blaxel, Sprites, or Vercel.
 
 All of these examples require `OPENAI_API_KEY`, because they call the model through the normal
 `Runner` path. Each cloud backend also needs its own provider credentials.
@@ -328,6 +328,52 @@ the default home and working directory become `/root`, so the example also uses
 `/root` as its manifest workspace root. If you configure root launch in your
 own code, either rely on that root-mode default or explicitly choose a
 `manifest.root` under `/root`.
+## Sprites
+
+### Setup
+
+Install the repo extra:
+
+```bash
+uv sync --extra sprites
+```
+
+Create a Sprites organization and API token at [sprites.dev](https://sprites.dev/),
+and export the required environment variables:
+
+```bash
+export OPENAI_API_KEY=...
+export SPRITES_API_TOKEN=...
+# Optional, defaults to https://api.sprites.dev:
+# export SPRITES_API_URL=https://api.sprites.dev
+```
+
+### Run
+
+```bash
+uv run python examples/sandbox/extensions/sprites_runner.py --stream
+```
+
+Useful flags:
+
+- `--sprite-name <name>` — attach to an existing sprite instead of creating an
+  ephemeral one. The example skips delete-on-exit when this is set.
+- `--skip-snapshot-check` — skip the tar workspace persistence verification.
+- `--question "..."` — override the default prompt.
+
+The Sprites client resolves the API token from `SPRITES_API_TOKEN` (override via
+`SpritesSandboxClient(token=...)`) and supports exec, filesystem read/write,
+PTY-mode interactive exec, and tar-based workspace snapshots. Sprites exposes
+at most one external HTTP port per sprite — declare it as a service with
+`--http-port` in the sprite image, then reference it via
+`SpritesSandboxClientOptions(exposed_ports=(<port>,))`.
+
+For cloud-bucket mounts, attach `SpritesCloudBucketMountStrategy` from
+`agents.extensions.sandbox.sprites` to any rclone-compatible mount type
+(`S3Mount`, `R2Mount`, `GCSMount`, `AzureBlobMount`, `BoxMount`). The strategy
+lazy-installs `rclone` and the `fuse` package via `sudo apt-get` on first use
+if the sprite image does not preinstall them.
+
 ## Blaxel
 
 ### Setup

examples/sandbox/extensions/sprites_runner.py

@@ -0,0 +1,225 @@
+"""
+Minimal Sprites-backed sandbox example for manual validation.
+
+This example creates a small in-memory workspace, lets the agent inspect it
+through one shell tool, and prints a short answer. By default an ephemeral
+sprite is created and deleted at the end; pass ``--sprite-name <name>`` to
+attach to an existing sprite instead.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import io
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import cast
+
+from openai.types.responses import ResponseTextDeltaEvent
+
+from agents import ModelSettings, Runner
+from agents.run import RunConfig
+from agents.sandbox import LocalSnapshotSpec, Manifest, SandboxAgent, SandboxRunConfig
+from agents.sandbox.session import BaseSandboxSession
+
+if __package__ is None or __package__ == "":
+    sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
+
+from examples.sandbox.misc.example_support import text_manifest  # noqa: E402
+from examples.sandbox.misc.workspace_shell import WorkspaceShellCapability  # noqa: E402
+
+try:
+    from agents.extensions.sandbox import (
+        SpritesSandboxClient,
+        SpritesSandboxClientOptions,
+    )
+except Exception as exc:  # pragma: no cover - import path depends on optional extras
+    raise SystemExit(
+        "Sprites sandbox examples require the optional repo extra.\n"
+        "Install it with: uv sync --extra sprites"
+    ) from exc
+
+
+DEFAULT_QUESTION = "Summarize this sandbox workspace in 2 sentences."
+SNAPSHOT_CHECK_PATH = Path("snapshot-check.txt")
+SNAPSHOT_CHECK_CONTENT = "sprites snapshot round-trip ok\n"
+
+
+def _build_manifest() -> Manifest:
+    return text_manifest(
+        {
+            "README.md": (
+                "# Sprites Demo Workspace\n\n"
+                "This workspace exists to validate the Sprites sandbox backend manually.\n"
+            ),
+            "handoff.md": (
+                "# Handoff\n\n"
+                "- Customer: Northwind Traders.\n"
+                "- Goal: validate Sprites sandbox exec and persistence flows.\n"
+                "- Current status: v1 backend slice (exec + fs + PTY) is wired and under test.\n"
+            ),
+            "todo.md": (
+                "# Todo\n\n"
+                "1. Inspect the workspace files.\n"
+                "2. Summarize the current status in two sentences.\n"
+            ),
+        }
+    )
+
+
+def _require_env(name: str) -> None:
+    if os.environ.get(name):
+        return
+    raise SystemExit(f"{name} must be set before running this example.")
+
+
+async def _read_text(session: BaseSandboxSession, path: Path) -> str:
+    data = await session.read(path)
+    text = cast(str | bytes, data.read())
+    if isinstance(text, bytes):
+        return text.decode("utf-8")
+    return text
+
+
+async def _verify_stop_resume(*, sprite_name: str | None) -> None:
+    """Round-trip a workspace through tar persistence and reattach.
+
+    With ``sprite_name=None`` an ephemeral sprite is created, persisted, and
+    then resumed against itself. With a named sprite the same flow runs
+    against the existing sprite (no create/delete on the API).
+    """
+
+    client = SpritesSandboxClient()
+    options = SpritesSandboxClientOptions(sprite_name=sprite_name)
+
+    with tempfile.TemporaryDirectory(prefix="sprites-snapshot-example-") as snapshot_dir:
+        sandbox = await client.create(
+            manifest=_build_manifest(),
+            snapshot=LocalSnapshotSpec(base_path=Path(snapshot_dir)),
+            options=options,
+        )
+
+        try:
+            await sandbox.start()
+            await sandbox.write(
+                SNAPSHOT_CHECK_PATH,
+                io.BytesIO(SNAPSHOT_CHECK_CONTENT.encode("utf-8")),
+            )
+            await sandbox.stop()
+        finally:
+            await sandbox.shutdown()
+
+        resumed = await client.resume(sandbox.state)
+        try:
+            await resumed.start()
+            restored = await _read_text(resumed, SNAPSHOT_CHECK_PATH)
+            if restored != SNAPSHOT_CHECK_CONTENT:
+                raise RuntimeError(
+                    f"Snapshot resume verification failed: expected "
+                    f"{SNAPSHOT_CHECK_CONTENT!r}, got {restored!r}"
+                )
+        finally:
+            await resumed.aclose()
+            if sprite_name is None:
+                # Ephemeral sandbox should clean up the sprite created by ``resume``.
+                await client.delete(resumed)
+
+    print("snapshot round-trip ok")
+
+
+async def main(
+    *,
+    model: str,
+    question: str,
+    sprite_name: str | None,
+    skip_snapshot_check: bool,
+    stream: bool,
+) -> None:
+    _require_env("OPENAI_API_KEY")
+    _require_env("SPRITES_API_TOKEN")
+
+    if not skip_snapshot_check:
+        await _verify_stop_resume(sprite_name=sprite_name)
+
+    manifest = _build_manifest()
+    agent = SandboxAgent(
+        name="Sprites Sandbox Assistant",
+        model=model,
+        instructions=(
+            "Answer questions about the sandbox workspace. Inspect the files before answering "
+            "and keep the response concise. Cite the file names you inspected."
+        ),
+        default_manifest=manifest,
+        capabilities=[WorkspaceShellCapability()],
+        model_settings=ModelSettings(tool_choice="required"),
+    )
+
+    client = SpritesSandboxClient()
+    sandbox = await client.create(
+        manifest=manifest,
+        options=SpritesSandboxClientOptions(sprite_name=sprite_name),
+    )
+
+    run_config = RunConfig(
+        sandbox=SandboxRunConfig(session=sandbox),
+        tracing_disabled=True,
+        workflow_name="Sprites sandbox example",
+    )
+
+    try:
+        async with sandbox:
+            if not stream:
+                result = await Runner.run(agent, question, run_config=run_config)
+                print(result.final_output)
+                return
+
+            stream_result = Runner.run_streamed(agent, question, run_config=run_config)
+            saw_text_delta = False
+            async for event in stream_result.stream_events():
+                if event.type == "raw_response_event" and isinstance(
+                    event.data, ResponseTextDeltaEvent
+                ):
+                    if not saw_text_delta:
+                        print("assistant> ", end="", flush=True)
+                        saw_text_delta = True
+                    print(event.data.delta, end="", flush=True)
+
+            if saw_text_delta:
+                print()
+    finally:
+        await client.delete(sandbox)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--model", default="gpt-5.5", help="Model name to use.")
+    parser.add_argument("--question", default=DEFAULT_QUESTION, help="Prompt to send to the agent.")
+    parser.add_argument(
+        "--sprite-name",
+        default=None,
+        help=(
+            "Existing sprite to attach to. When omitted, an ephemeral sprite is "
+            "created and deleted automatically."
+        ),
+    )
+    parser.add_argument(
+        "--skip-snapshot-check",
+        action="store_true",
+        default=False,
+        help="Skip the tar workspace persistence verification before the agent run.",
+    )
+    parser.add_argument("--stream", action="store_true", default=False, help="Stream the response.")
+    args = parser.parse_args()
+
+    asyncio.run(
+        main(
+            model=args.model,
+            question=args.question,
+            sprite_name=args.sprite_name,
+            skip_snapshot_check=args.skip_snapshot_check,
+            stream=args.stream,
+        )
+    )

pyproject.toml

@@ -52,6 +52,7 @@ cloudflare = ["aiohttp>=3.12,<4"]
 e2b = ["e2b==2.20.0", "e2b-code-interpreter==2.4.1"]
 modal = ["modal==1.3.5"]
 runloop = ["runloop_api_client>=1.16.0,<2.0.0"]
+sprites = ["sprites-py>=0.0.1rc37,<0.2"]
 vercel = ["vercel>=0.5.6,<0.6"]
 s3 = ["boto3>=1.34"]
 temporal = [
@@ -164,6 +165,10 @@ ignore_missing_imports = true
 module = ["vercel", "vercel.*"]
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+module = ["sprites", "sprites.*"]
+ignore_missing_imports = true
+
 [tool.coverage.run]
 source = ["src/agents"]
 omit = [

src/agents/extensions/sandbox/__init__.py

@@ -109,6 +109,26 @@
 except Exception:  # pragma: no cover
     _HAS_VERCEL = False
 
+try:
+    from .sprites import (
+        DEFAULT_SPRITES_API_URL as DEFAULT_SPRITES_API_URL,
+        DEFAULT_SPRITES_CONTEXT_PATH as DEFAULT_SPRITES_CONTEXT_PATH,
+        DEFAULT_SPRITES_WAIT_FOR_RUNNING_TIMEOUT_S as DEFAULT_SPRITES_WAIT_FOR_RUNNING_TIMEOUT_S,  # noqa: E501
+        DEFAULT_SPRITES_WORKSPACE_ROOT as DEFAULT_SPRITES_WORKSPACE_ROOT,
+        SpritesCheckpoints as SpritesCheckpoints,
+        SpritesCloudBucketMountStrategy as SpritesCloudBucketMountStrategy,
+        SpritesPlatformContext as SpritesPlatformContext,
+        SpritesSandboxClient as SpritesSandboxClient,
+        SpritesSandboxClientOptions as SpritesSandboxClientOptions,
+        SpritesSandboxSession as SpritesSandboxSession,
+        SpritesSandboxSessionState as SpritesSandboxSessionState,
+        SpritesUrlAccess as SpritesUrlAccess,
+    )
+
+    _HAS_SPRITES = True
+except Exception:  # pragma: no cover
+    _HAS_SPRITES = False
+
 __all__: list[str] = []
 
 if _HAS_E2B:
@@ -207,3 +227,21 @@
             "RunloopUserParameters",
         ]
     )
+
+if _HAS_SPRITES:
+    __all__.extend(
+        [
+            "DEFAULT_SPRITES_API_URL",
+            "DEFAULT_SPRITES_CONTEXT_PATH",
+            "DEFAULT_SPRITES_WAIT_FOR_RUNNING_TIMEOUT_S",
+            "DEFAULT_SPRITES_WORKSPACE_ROOT",
+            "SpritesCheckpoints",
+            "SpritesCloudBucketMountStrategy",
+            "SpritesPlatformContext",
+            "SpritesSandboxClient",
+            "SpritesSandboxClientOptions",
+            "SpritesSandboxSession",
+            "SpritesSandboxSessionState",
+            "SpritesUrlAccess",
+        ]
+    )