# OpenAI Agents SDK

Run the shell and file tools of an OpenAI Agents SDK sandbox agent in a WBX sandbox – an isolated Linux microVM – instead of on your own machine. One package, one line in the run configuration.

## Install

```
pip install openai-agents-wbxsandbox
export WBXSANDBOX_API_KEY=YOUR_API_KEY        # Settings → API keys
export OPENAI_API_KEY=…
```

Tested with `openai-agents` 0.25 and Python 3.10–3.13. The package uses the [Python SDK](https://sandbox.wbx.cz/docs/sdk.md) for every call.

## Quickstart

```
import asyncio

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig
from openai_agents_wbxsandbox import WBXSandboxClient, WBXSandboxClientOptions

agent = SandboxAgent(name="Workspace assistant", instructions="Use the shell to answer.")

run_config = RunConfig(
    sandbox=SandboxRunConfig(
        client=WBXSandboxClient(),                      # API key from WBXSANDBOX_API_KEY
        options=WBXSandboxClientOptions(template="base"),
    ),
)

async def main():
    result = await Runner.run(agent, "Which Python version is installed?", run_config=run_config)
    print(result.final_output)

asyncio.run(main())
```

The runner creates a sandbox, the agent works in its `/workspace` and the sandbox is deleted when the run ends. You pay only for the seconds it ran.

## Options

| Option | Default | Meaning |
| --- | --- | --- |
| `template` | `"base"` | Base image – see [Templates](https://sandbox.wbx.cz/docs/templates.md) |
| `name` | `–` | Named sandbox: an existing one with this name is reused and its workspace kept |
| `timeout_s` | `3600` | Lifetime in seconds (your plan’s maximum applies) |
| `on_exit` | `"kill" ("sleep" with a name)` | `"kill"` deletes the sandbox after the run, `"sleep"` keeps its files for later |
| `idle_timeout_s` | `–` | With `on_exit="sleep"`: fall asleep after this many idle seconds |
| `compute_class` | `account default` | [Compute class](https://sandbox.wbx.cz/docs/jobs/compute.md) |
| `vcpu, mem_mb` | `template` | Size of the VM |
| `internet, allow, block` | `full internet` | No network, an allowlist or extra blocked destinations – see [Network](https://sandbox.wbx.cz/docs/sandboxes/network.md) |
| `ip` | `team default` | `"ipv4"`, `"dual"` or `"ipv6"` with its own public IPv6 address |
| `env` | `–` | Non-secret environment variables |
| `exposed_ports` | `–` | Ports that can get a [public HTTPS URL](https://sandbox.wbx.cz/docs/sandboxes/urls.md) |

> **Secrets go to the client, not the options.** Options can be saved in the run state. Put API tokens for the agent’s commands into `WBXSandboxClient(env={...})` – they are sent to the sandbox but never serialized.

## Keep the workspace between runs

```
options = WBXSandboxClientOptions(name="report-builder", on_exit="sleep")
```

After the run the sandbox [falls asleep](https://sandbox.wbx.cz/docs/sandboxes/sleep.md) instead of being deleted: files stay, running programs stop and no compute is billed. The next run with the same name – or a resume from saved run state – wakes it up in a few seconds and continues in the same workspace.

## Resume and snapshots

- **Resume** reconnects to the sandbox from the saved run state and wakes it up. If the sandbox no longer exists, a new one is created and its workspace restored from the snapshot you configured (e.g. `LocalSnapshotSpec`).
- A saved state can only reconnect to sandboxes of the account behind your API key.
- Import `openai_agents_wbxsandbox` in every process that restores saved run state.

## Not supported yet

- Manifest mounts (S3, GCS, R2, Azure Blob, Box) – the run fails with a clear error before a sandbox is created. Copy the data into the workspace instead.
- Interactive input – commands have no terminal, so prompts and REPLs get end-of-file. Long commands (builds, installs) are fine: they keep running and the agent polls their output.
- Command output is text (UTF-8) up to 16 MB per stream; read binary results as files.

Examples (fix failing tests, CSV to chart) and source: [github.com/WBX-Sandbox/openai-agents-wbxsandbox](https://github.com/WBX-Sandbox/openai-agents-wbxsandbox) · package: [pypi.org/project/openai-agents-wbxsandbox](https://pypi.org/project/openai-agents-wbxsandbox/).

Source: https://sandbox.wbx.cz/docs/integrations/openai-agents
