feat: OpenAI Agents SDK sandbox provider as external integration package

Problem Statement

The OpenAI Agents SDK (openai-agents-python) supports pluggable sandbox providers via BaseSandboxClient / BaseSandboxSession. This lets agent frameworks execute code in sandboxed environments. OpenShell is a natural fit — it provides policy-enforced, GPU-capable sandboxes with declarative network controls — but the SDK maintainers have a clear policy: third-party sandbox providers must ship as external packages, not in-tree extensions.

We submitted PR openai/openai-agents-python#3469 with a working in-tree implementation (4 classes, 27 tests, docs, example). The maintainer's response:

"We're not actively adding new third-party sandbox provider implementations directly to the SDK. We would prefer provider-specific integrations like this one to live in a separate package maintained by the provider team, so they can evolve and be released alongside the underlying service."

Without this integration, users who want to run OpenAI Agents in OpenShell sandboxes must write the adapter themselves — bridging async/sync, handling gateway discovery, file I/O via exec+base64, and workspace persistence.

Proposed Design

Package: openshell-openai-agents

A standalone Python package that adapts the existing openshell Python SDK (sync gRPC client) to the OpenAI Agents sandbox protocol. Published on PyPI, maintained in the OpenShell repo.

Location

integrations/openai-agents/ in this repo. Keeping it in-repo ensures the integration evolves with gRPC API changes and CI catches breakage immediately.

Package Structure

integrations/openai-agents/
  pyproject.toml                          # openshell-openai-agents
  src/openshell_openai_agents/
    __init__.py                           # Re-exports public API
    sandbox.py                            # OpenShellSandboxClient, OpenShellSandboxSession
    py.typed                              # PEP 561 marker
  tests/
    test_sandbox.py                       # Unit tests (mock gRPC layer)
  examples/
    openshell_runner.py                   # Integration example
  README.md

Key Classes

Class	Extends	Purpose
OpenShellSandboxClient	BaseSandboxClient	Gateway discovery, sandbox lifecycle
OpenShellSandboxSession	BaseSandboxSession	exec, file I/O, workspace persistence
OpenShellSandboxClientOptions	dataclass	Endpoint, TLS, OIDC, workspace config
OpenShellSandboxSessionState	dataclass	Sandbox ref + tar snapshot for resume

Integration Pattern

1. Async wrapping: The openshell SDK is synchronous gRPC. All blocking calls wrapped with asyncio.to_thread(), following the same pattern as the closed PR.

2. Gateway discovery: Uses SandboxClient.from_active_cluster() for zero-config local development, or explicit endpoint for CI/production.

3. File I/O: Via exec + base64 encoding (OpenShell has no native file transfer API). The sandbox enforces its own filesystem policy.

4. Workspace persistence: Tar-based workspace snapshots for session resume.

5. Command validation: Local path normalization since OpenShell rejects certain characters (newlines) in command arguments.

Dependencies

[project]
dependencies = [
    "openai-agents>=0.18.2,<0.19",
    "openshell>=0.1.0",
]

Tight upper bound on openai-agents because the sandbox API is beta and breaks between minors. The openshell SDK dependency ensures gRPC proto compatibility.

Usage

from openshell_openai_agents import OpenShellSandboxClient, OpenShellSandboxClientOptions
from agents import Agent, Runner

client = OpenShellSandboxClient(
    options=OpenShellSandboxClientOptions(workspace="my-workspace")
)

agent = Agent(
    name="code-runner",
    instructions="Execute code in the sandbox",
    sandbox_client=client,
)

result = await Runner.run(agent, "Write and run a Python hello world")

Prior Work

The implementation from PR openai/openai-agents-python#3469 is the starting point — 4 classes, 27 passing tests, a runnable example, and docs. The work is to repackage it as a standalone package rather than an in-tree extension.

Alternatives Considered

1. Separate repository (openshell-openai-agents repo)

A standalone repo decouples release cycles but adds coordination overhead. When the OpenShell gRPC API changes (new proto fields, new RPCs), the integration must be updated in lockstep. Keeping it in-repo means CI catches breakage immediately and contributors see the full picture.

Rejected because externalizing components outside of NVIDIA/OpenShell requires broader alignment across the team.

2. Contribute to a community integrations repo

No such repo exists for the OpenAI Agents SDK. The official guidance is provider-maintained packages.

Not viable at this time.

3. Ship inside the openshell Python SDK package itself

Adding openai-agents as an optional dependency of the core SDK would couple the core package to OpenAI's release cadence. The core SDK should remain framework-agnostic.

Rejected to keep the core SDK clean and avoid transitive dependency sprawl.

Agent Investigation

• Reviewed the existing python/openshell/ SDK: sync gRPC client with SandboxClient, SandboxSession, ExecResult, gateway discovery via from_active_cluster(), OIDC token refresh, workspace management. All primitives needed for the adapter exist.
• Reviewed the closed PR #3469: 4 classes, 27 tests, example runner, docs. Implementation is complete and tested against a live gateway. Needs repackaging, not rewriting.
• No integrations/ directory exists in the repo yet — this would be the first.

Start by reading the existing python/openshell SDK, especially SandboxClient, SandboxSession, ExecResult, and from_active_cluster(), then review the implementation from openai/openai-agents-python#3469. Create the specified integrations/openai-agents package with its sandbox adapter, mocked tests, example, and README. Done means the package builds with the stated dependencies and its tests cover lifecycle, async wrapping, file I/O, and workspace persistence.