openai-agents-opsen

Run OpenAI Agents SDK sandboxes on opsen — with machine, model and tool spend on one bill and a budget the runtime enforces mid-run.

pip install openai-agents-opsen

from agents import Runner, RunConfig
from agents.sandbox import SandboxAgent
from openai_agents_opsen import OpsenSandboxClient

agent = SandboxAgent(name="Worker", instructions="...")

result = await Runner.run(
    agent,
    "read the repo and summarise it",
    run_config=RunConfig(
        sandbox={"client": OpsenSandboxClient(
            task_id="code-review",
            budget_usd=2.00,
        )}
    ),
)

Set OPSEN_API_KEY, or pass api_key=. Get one here:

https://opsen.dev/keys

What this adds

The SDK ships with Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop and Vercel. Every one of them bills you for the machine and leaves the model bill with a different vendor, on a different invoice, with no shared identifier. Two bills, reconciled by hand, and no answer to "what did that agent cost".

opsen sits in both paths:

session.cost()
# {'total_usd': 0.41, 'compute_usd': 0.02, 'tokens_usd': 0.39,
#  'calls': 34, 'input_tokens': 84120, 'output_tokens': 9310,
#  'task_id': 'code-review'}

budget_usd is a ceiling enforced during the run. An agent that would cross it is refused mid-flight rather than noticed afterwards.

Behaviour worth knowing

Exit codes pass through. The SDK decides whether a step failed from the exit code, so it is returned unchanged rather than flattened.

Commands are quoted, not joined. The SDK hands over argv; " ".join() would turn ("sh", "-c", "exit 3") into a different command that quietly succeeds.

Ports depend on the runtime. getHost-style port exposure works on E2B, works on Modal when the port was declared at sandbox creation, and raises on the local runtime with a message naming the limitation.

Resume carries opsen's own session id. SandboxSessionState.session_id is typed as a UUID and opsen's ids are not, so the state subclasses to keep the real id — the same approach the SDK's own UnixLocalSandboxSessionState takes.

Configuration

Why a separate package

The SDK maintainers do not take third-party provider implementations into the repo — see PR #3469, where a fully tested NVIDIA OpenShell provider was closed with a preference for "a separate package maintained by the provider team". This is that package.

Licence

Apache-2.0