Use the OpenAI Agents SDK

The OpenAI Agents SDK calls a sandbox client whenever an agent needs a shell. BoxRouterSandboxClient is that client: each agent run gets its own BoxRouter sandbox, and BoxRouter picks the route. For OpenAI’s hosted Agents API, see Agents API. Before You Begin: A BoxRouter API key, a connected provider key or Credits, and Python 3.11 or later.

Install

The package installs the BoxRouter Python SDK as a dependency.

python -m pip install boxrouter-openai-agents

Open a Session

Set your BoxRouter API key as in the quickstart. This script prints a unique run label before creating a sandbox, so you can find it if creation is uncertain. It needs no model key. Save it as session.py:

import asyncio
import io
from pathlib import Path
from uuid import uuid4

from agents.sandbox.manifest import Manifest
from boxrouter_openai_agents import BoxRouterSandboxClient, BoxRouterSandboxClientOptions


async def main() -> None:
    run_label = f"openai-agents-{uuid4().hex}"
    print(f"Run label: {run_label}", flush=True)
    session = await BoxRouterSandboxClient().create(
        manifest=Manifest(root="/tmp/boxrouter-workspace"),
        options=BoxRouterSandboxClientOptions(lifetime_seconds=300, labels={"run": run_label}),
    )
    async with session:
        await session.write(Path("hello.py"), io.BytesIO(b"print('hello from OpenAI Agents')\n"))
        result = await session.exec("python3 hello.py")
        if result.exit_code != 0:
            raise RuntimeError(result.stderr.decode())
        print(result.stdout.decode(), end="")


asyncio.run(main())

python session.py

Leaving the async with block requests sandbox destruction. If the script dies first, the sandbox can run past the end of its lifetime_seconds lifetime (300 in this example; 900 when unset). If you don’t know whether the sandbox was created, list sandboxes by the run label before retrying. The label helps you find and destroy a sandbox that may have started. root is the directory the SDK treats as the workspace. Choose a directory the sandbox user can write to, such as /tmp/boxrouter-workspace. Files there last for the sandbox session.

Run an Agent in It

For a model-driven run, pass the same client and options in RunConfig. Set OPENAI_MODEL and the model provider’s key, such as OPENAI_API_KEY. Save this as agent.py:

import asyncio
import os
from uuid import uuid4

from agents import RunConfig, Runner
from agents.sandbox import SandboxAgent
from agents.sandbox.capabilities import Shell
from agents.sandbox.manifest import Manifest
from boxrouter_openai_agents import BoxRouterSandboxClient, BoxRouterSandboxClientOptions


async def main() -> None:
    run_label = f"openai-agents-{uuid4().hex}"
    print(f"Run label: {run_label}", flush=True)
    agent = SandboxAgent(
        name="worker",
        instructions="Use the sandbox shell for the requested task.",
        model=os.environ["OPENAI_MODEL"],
        capabilities=[Shell()],
        default_manifest=Manifest(root="/tmp/boxrouter-workspace"),
    )
    sandbox = {
        "client": BoxRouterSandboxClient(),
        "options": BoxRouterSandboxClientOptions(lifetime_seconds=300, labels={"run": run_label}),
    }
    result = await Runner.run(
        agent, "Run python3 --version and report it.", run_config=RunConfig(sandbox=sandbox)
    )
    print(result.final_output)


asyncio.run(main())

python agent.py

The agent prints its report of the sandbox’s Python version. When the run ends, the runner closes the session and requests sandbox destruction. If the process dies first, the sandbox can run past the end of its lifetime_seconds lifetime (300 in this example). Use the printed run label to find it, then destroy it. The Agents SDK sandbox guide covers building the SandboxAgent.

Limits

Manifest mounts are refused before a sandbox is created, and PTY sessions are not supported.
If the recorded sandbox is gone when the SDK resumes a session, the client creates a new one. It restores the workspace from the SDK’s snapshot; processes and files outside the workspace do not carry over.
Errors carry the BoxRouter code, request_id and outcome. Only rate_limited and overloaded with outcome not_started are marked retryable; for anything else, check the sandbox before you replay the call.
If creation fails with no_eligible_route, no route met your request; Sandboxes shows how to read the refusal.

Next Steps

Use the OpenAI Agents API

OpenAI’s hosted Agents API instead.

Create a Sandbox

What a sandbox request can ask for.

Run Commands

Exit codes, timeouts, and output limits.

Launch an Agent

Integrations