OpenAI Agents SDK

Run agents built with the OpenAI Agents SDK inside upstream sandboxes. upstream plugs in as the SDK's sandbox client, so an agent's shell commands and file edits happen in a Firecracker microVM instead of on your machine.

Install#

The integration ships with the Python SDK as an extra. It needs openai-agents 0.14 or later.

$ pip install "upstm-py[openai-agents]"

Run an agent in a sandbox#

import asyncio, os
from agents import Runner, RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig
from upstream.openai_agents import UpstreamSandboxClient, UpstreamSandboxClientOptions

agent = SandboxAgent(name="coder", instructions="You write and run Python.")

run_config = RunConfig(
    sandbox=SandboxRunConfig(
        client=UpstreamSandboxClient(api_key=os.environ["UPSTREAM_API_KEY"]),
        options=UpstreamSandboxClientOptions(template="python"),
    )
)

async def main():
    result = await Runner.run(agent, "Write fizzbuzz.py and run it", run_config=run_config)
    print(result.final_output)

asyncio.run(main())

Each session gets a fresh sandbox from the template you choose. Swap template="python" for "claude-code" or one of your custom templates to change what the agent has to work with.

UpstreamSandboxClient#

UpstreamSandboxClient(api_key, base_url="https://api.upstream.build", timeout=30.0)

The sandbox client to pass as SandboxRunConfig.client. api_key is your ak_… key.

UpstreamSandboxClientOptions#

UpstreamSandboxClientOptions(template="python", metadata=None)

What's supported#

Session state records the sandbox's ID and token, so a session can be resumed after your process restarts.