# OpenAI Agents

Use Sandbox0 as the backend for OpenAI Agents SDK `SandboxAgent` runs through
the Sandbox0 Python SDK adapter. The adapter maps the OpenAI workspace to
`/workspace` on the sandbox writable rootfs.

<Callout variant="info">
OpenAI Agents SDK Sandbox Agents are currently beta. The Sandbox0 adapter uses
Sandbox0 rootfs snapshots for durable workspace references.
</Callout>

## Requirements

- Python 3.10 or later
- `sandbox0[openai-agents]`
- `SANDBOX0_TOKEN`
- optional `SANDBOX0_BASE_URL` for a self-hosted deployment

```bash
pip install "sandbox0[openai-agents]"
```

## Basic Usage

```python
import asyncio

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig

from sandbox0_openai_agents import Sandbox0SandboxClient, Sandbox0SandboxClientOptions


async def main() -> None:
    client = Sandbox0SandboxClient()
    agent = SandboxAgent(
        name="sandbox0-demo",
        instructions="Use the sandbox for filesystem and command execution tasks.",
    )

    result = await Runner.run(
        agent,
        "Create hello.txt in the workspace, print it, and summarize what you did.",
        run_config=RunConfig(
            sandbox=SandboxRunConfig(
                client=client,
                options=Sandbox0SandboxClientOptions(template="default"),
            ),
            workflow_name="Sandbox0 OpenAI Agents demo",
        ),
    )
    print(result.final_output)


asyncio.run(main())
```

## Lifecycle And Persistence

For a fresh session, the adapter claims a sandbox and uses its `/workspace`
directory directly. `start()` reconnects to a running sandbox or resumes a
paused one. `stop()` creates a best-effort named rootfs snapshot by default and
stores its ID in `Sandbox0SandboxSessionState`.

If the original sandbox is unavailable, the adapter can claim a replacement
from `rootfs_snapshot_id`. This creates a new isolated writable rootfs from the
saved workspace state.

Runner-owned cleanup deletes the sandbox and, by default, the adapter-created
rootfs snapshot. Preserve the snapshot when serialized run state must resume
after cleanup:

```python
options = Sandbox0SandboxClientOptions(
    template="default",
    delete_sandbox_on_delete=True,
    delete_rootfs_snapshot_on_delete=False,
)
```

Start directly from a known workspace snapshot:

```python
options = Sandbox0SandboxClientOptions(
    template="default",
    rootfs_snapshot_id="snap_abc123",
)
```

## Options

| Option | Default | Description |
|--------|---------|-------------|
| `template` | `default` | Template used for a fresh or replacement sandbox. |
| `workspace_mount_path` | `/workspace` | Workspace root; must match `Manifest.root`. |
| `rootfs_snapshot_id` | `None` | Named Sandbox0 rootfs snapshot used to initialize a replacement workspace. |
| `sandbox_ttl_sec` | `None` | Optional sandbox TTL. |
| `delete_sandbox_on_delete` | `True` | Delete the sandbox when `client.delete(session)` runs. |
| `delete_rootfs_snapshot_on_delete` | `True` | Delete the saved rootfs snapshot during client cleanup. |
| `create_rootfs_snapshot_on_stop` | `True` | Create a best-effort rootfs snapshot during `stop()`. |
| `exposed_ports` | `()` | Ports exposed in the OpenAI sandbox session state. |
| `poll_interval_sec` | `0.1` | Poll interval for status and command completion. |
| `start_timeout_sec` | `60.0` | Timeout for sandbox startup and reconnect. |

Adapter file operations use the live sandbox file API, and shell commands run
through a Sandbox0 CMD context with `/workspace` as the working directory.
Generic OpenAI SDK snapshot specs are not accepted; use
`rootfs_snapshot_id` for Sandbox0 workspace persistence.

## Next Steps

<CardGroup>
  <Card title="Files" href="/docs/sandbox/files" cta="Continue">
    Use the live sandbox file API while a session is running.
  </Card>

  <Card title="Snapshot And Restore" href="/docs/sandbox/snapshot-restore" cta="Continue">
    Understand rootfs snapshot, restore, claim, and fork semantics.
  </Card>
</CardGroup>