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

Argument	Default	Meaning
`api_key`	`$OPSEN_API_KEY`	From opsen.dev/keys
`task_id`	`"agents-sdk"`	Groups this agent's spend
`budget_usd`	none	Hard ceiling, enforced mid-run
`labels`	`{}`	Arbitrary tags to group spend by
`base_url`	`https://opsen.dev`	For self-hosted deployments

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

openai_agents_opsen-0.1.4.tar.gz (5.9 kB view details)

Uploaded Sep 8, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

openai_agents_opsen-0.1.4-py3-none-any.whl (6.2 kB view details)

Uploaded Sep 8, 2026 Python 3

File details

Details for the file openai_agents_opsen-0.1.4.tar.gz.

File metadata

Download URL: openai_agents_opsen-0.1.4.tar.gz
Upload date: Sep 8, 2026
Size: 5.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for openai_agents_opsen-0.1.4.tar.gz
Algorithm	Hash digest
SHA256	`d5aa7e420009e8c63be2003db600aa7cc12c14bce595445c9f5f75cf2dbd4243`
MD5	`a78af370975310f4647e7205d3727cf2`
BLAKE2b-256	`d6b4ef97759ec035a78aa39d6517e24702e14761b9683c4a074c50ce80491fc8`

See more details on using hashes here.

Provenance

The following attestation bundles were made for openai_agents_opsen-0.1.4.tar.gz:

Publisher: release.yml on md322613/opsen

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: openai_agents_opsen-0.1.4.tar.gz
- Subject digest: d5aa7e420009e8c63be2003db600aa7cc12c14bce595445c9f5f75cf2dbd4243
- Sigstore transparency entry: 2754451911
- Sigstore integration time: Sep 8, 2026
Source repository:
- Permalink: md322613/opsen@c1f831ea612c86822c0556481d2b1de7639855b0
- Branch / Tag: refs/tags/v0.1.4
- Owner: https://github.com/md322613
- Access: private
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@c1f831ea612c86822c0556481d2b1de7639855b0
- Trigger Event: push