OpenAI Agents SDK

Runta serves as sandbox backend and lets OpenAI Agents SDK workflows run in governed, persistent sandboxes. Its durable runner helps resume interrupted agent work without starting from scratch.

The provider import path is:

agents_runta.sandbox:RuntaSandboxClient

The durable runner import path is:

agents_runta.durable:run
agents_runta.durable:DurableRunConfig

Install

This requires Python 3.10 or later.

pip

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install openai-agents-runta

uv

uv venv --python <compatible_python_version>
source .venv/bin/activate
uv pip install openai-agents-runta

This installs the Runta sandbox provider, the OpenAI Agents SDK, and the Runta Python SDK into the same Python environment.

Set your OpenAI and Runta credentials:

export OPENAI_API_KEY=sk-...
export RUNTA_TOKEN=rt_...

Run a Sandbox Agent

Create a SandboxAgent and pass a Runta-backed sandbox through RunConfig.

import asyncio

from agents import RunConfig, Runner
from agents.sandbox import SandboxAgent, SandboxRunConfig

from agents_runta.sandbox import RuntaSandboxClient, RuntaSandboxClientOptions


async def main() -> None:
    agent = SandboxAgent(
        name="Runta Builder",
        instructions=(
            "Use the sandbox filesystem and shell tools to complete the task."
        ),
    )

    run_config = RunConfig(
        sandbox=SandboxRunConfig(
            client=RuntaSandboxClient(),
            options=RuntaSandboxClientOptions(
                name_prefix="openai-agent",
                root="/workspace",
                vcpus=2,
                memory_mib=2048,
                pause_on_exit=True,
            ),
        ),
    )

    result = await Runner.run(
        agent,
        "Create /workspace/hello.txt with a short message.",
        run_config=run_config,
        max_turns=8,
    )
    print(result.final_output)


asyncio.run(main())

This keeps the normal OpenAI Agents SDK runner flow. The sandbox client creates a Runta runtime, executes shell commands in that runtime, and persists workspace files through the Runta file APIs.

Manage a Sandbox Session

Create a session directly when your application needs explicit resume or cleanup control.

import asyncio
import json
from pathlib import Path

from agents import RunConfig, Runner
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import File

from agents_runta.sandbox import RuntaSandboxClient, RuntaSandboxClientOptions


STATE_FILE = Path("runta_agents_session.json")


async def main() -> None:
    client = RuntaSandboxClient()
    session = await client.create(
        manifest=Manifest(
            root="/workspace",
            entries={
                "input/request.md": File(
                    content=b"Write a short report and save it as report.md.\n"
                )
            },
        ),
        options=RuntaSandboxClientOptions(
            name_prefix="openai-agent",
            pause_on_exit=True,
        ),
    )

    agent = SandboxAgent(
        name="Runta Writer",
        instructions="Use sandbox tools. Create the requested files.",
    )

    try:
        result = await Runner.run(
            agent,
            "Read input/request.md and create report.md.",
            run_config=RunConfig(sandbox=SandboxRunConfig(session=session)),
        )
        print(result.final_output)

        STATE_FILE.write_text(
            json.dumps(client.serialize_session_state(session.state), indent=2),
            encoding="utf-8",
        )
    finally:
        await session.stop()


asyncio.run(main())

With pause_on_exit=True, session.stop() persists the workspace and pauses the Runta runtime. Use the serialized session state with RuntaSandboxClient.resume(state) when you want to reconnect to the same runtime. Call RuntaSandboxClient.delete(session) when the runtime should be removed.

Durable Runner

The integration also includes a local durable runner for resumable workflows. It combines the OpenAI Agents SDK SQLiteSession with a local JSON pointer to the Runta sandbox session state.

import asyncio

from agents import RunConfig
from agents.sandbox import SandboxAgent

from agents_runta.durable import DurableRunConfig, run
from agents_runta.sandbox import RuntaSandboxClientOptions


async def main() -> None:
    agent = SandboxAgent(
        name="Durable Runta Agent",
        instructions="Use sandbox tools and keep workspace artifacts current.",
    )

    result = await run(
        agent,
        "Maintain /workspace/durable.txt and summarize its contents.",
        run_config=RunConfig(),
        durable=DurableRunConfig(
            sandbox_options=RuntaSandboxClientOptions(
                name_prefix="openai-durable",
                pause_on_exit=True,
            ),
        ),
    )
    print(result.final_output)


asyncio.run(main())

By default, durable state is written under ./.runta_<script-name>/. Re-running the same script resumes unfinished work when the original Runta runtime still exists.

The durable runner persists three pieces of state:

• Agents SDK conversation history in a local SQLiteSession.
• A local JSON pointer to the Runta sandbox session state.
• Workspace changes in the paused Runta runtime.

That means recovery is a resume path, not a replay engine. If the local state directory is removed, or the original Runta runtime is deleted, start a new run or restore from a separate Runta checkpoint.

What Runta Handles

RuntaSandboxClient implements the Agents SDK sandbox client contract:

• create creates a Runta runtime and returns an Agents SDK sandbox session.
• resume reconnects to the original Runta runtime from serialized state.
• delete removes the underlying Runta runtime.
• Sandbox exec runs commands through runtime.exec.
• Sandbox read and write map to runtime.files.
• Workspace persistence and hydration use tar archives moved through Runta file APIs.
• Declared exposed_ports become HTTP ingress specs on the Runta runtime.
• pause_on_exit=True pauses the runtime on session close so the workspace can be resumed later.

Normal OpenAI Agents SDK sandbox workflows can use Runta for shell execution, filesystem tools, workspace snapshots, session serialization, runtime resume, and explicit runtime cleanup.

Current Limitations

• PTY sessions are not implemented.
• Browser automation, mounts, and Agents SDK secrets-manager integration are not implemented.
• Public port URL resolution depends on Runta runtime metadata exposing an endpoint URL for the declared port.
• Resume requires the original Runta runtime to still exist.
• delete(session) is explicit. Stopping or closing a session preserves the runtime when pause_on_exit=True.

Troubleshooting

If Python fails with No module named 'agents_runta', the Python environment running your script does not have openai-agents-runta installed. Activate the same virtual environment where you installed the package and rerun the script.

If a run fails before creating a Runta runtime, check OPENAI_API_KEY, RUNTA_TOKEN, and optional RUNTA_ENDPOINT. The Runta token is read by the Runta Python SDK unless you pass it explicitly in RuntaSandboxClientOptions.

If exposed port resolution fails with endpoint_unavailable, the runtime was created with the requested ingress spec but the current runtime metadata did not include a public endpoint URL for that port.