Metadata-Version: 2.4
Name: openai-agents-opsen
Version: 0.1.6
Summary: Run OpenAI Agents SDK sandboxes on opsen - machine, model and tool spend on one bill.
Author: opsen
License: Apache-2.0
Project-URL: Homepage, https://opsen.dev
Project-URL: Source, https://github.com/md322613/opsen
Keywords: openai,agents,sandbox,opsen,openai-agents
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: opsen>=0.1.0
Provides-Extra: test
Requires-Dist: openai-agents>=0.14; extra == "test"

# openai-agents-opsen

Run [OpenAI Agents SDK](https://github.com/openai/openai-agents-python)
sandboxes on [opsen](https://opsen.dev) — with machine, model and tool
spend on one bill and a budget the runtime enforces mid-run.

```bash
pip install openai-agents-opsen
```

```python
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:

```python
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](https://github.com/openai/openai-agents-python/pull/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
