OpenAI Agents SDK

The OpenAI Agents Python SDK (openai-agents) ships built-in ShellTool and ApplyPatchTool primitives, plus the newer SandboxAgent. Mirage provides drop-in replacements that route every shell command, patch, and sandbox call through your Workspace instead of the host.

Install

uv add 'mirage-ai[openai]'

Tools (`ShellTool` + `ApplyPatchTool`)

import asyncio

from agents import Agent, ApplyPatchTool, Runner, ShellTool

from mirage import MountMode, Workspace
from mirage.agents.openai_agents import (
    MirageEditor,
    MirageShellExecutor,
    build_system_prompt,
)
from mirage.vfs.ram import RAMVFS

ws = Workspace({"/": RAMVFS()}, mode=MountMode.WRITE)


async def main() -> None:
    agent = Agent(
        name="Mirage RAM Agent",
        model="gpt-5.5-mini",
        instructions=await build_system_prompt(
            mount_info={"/": "In-memory filesystem (read/write)"},
        ),
        tools=[
            ShellTool(executor=MirageShellExecutor(ws)),
            ApplyPatchTool(editor=MirageEditor(ws)),
        ],
    )
    result = await Runner.run(agent, "Create /hello.txt with 'hi' and cat it.")
    print(result.final_output)


asyncio.run(main())

Sandbox Agent

SandboxAgent runs the SDK’s own exec_command, apply_patch and view_image tools against a sandbox session. MirageSandboxClient makes that session a Mirage workspace, and MirageCapability adds the workspace’s mounts (backend, mode, commands) to the agent’s instructions:

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import SandboxAgent, SandboxRunConfig
from agents.sandbox.capabilities import Capabilities

from mirage.agents.openai_agents import MirageCapability, MirageSandboxClient

agent = SandboxAgent(
    name="Mirage Sandbox Agent",
    model="gpt-5.5",
    capabilities=[*Capabilities.default(), MirageCapability()],
)
result = await Runner.run(
    agent,
    "Summarize /data/report.csv into /notes.md.",
    run_config=RunConfig(sandbox=SandboxRunConfig(
        client=MirageSandboxClient(ws))),
)

How the session behaves:

Every command starts at the manifest root, / unless you configure a Manifest, and a cd or export ends with its command, as in the SDK’s other sandboxes. Commands see the manifest’s environment. Each sandbox session has its own Mirage session, and its commands, file reads, writes and patches run in it one at a time.
A command still running after exec_command’s yield time keeps running. The model polls it with write_stdin and stops it with Ctrl-C (\u0003). A direct exec(..., timeout=...) raises ExecTimeoutError.
Relative paths resolve against the manifest root, and writes create missing parent directories.
A run paused for tool approval resumes on the same workspace and keeps the files the agent wrote.
exec("ls", "-la", path, shell=False) quotes each argument. A single string with shell=False is one program name, as in the SDK’s other sandboxes.

Exports

Symbol	Purpose
`MirageShellExecutor`	Drop-in `ShellTool` executor, runs inside `Workspace.shell()`.
`MirageEditor`	Drop-in `ApplyPatchTool` editor, patches go through Mirage FS ops.
`MirageSandboxClient`	Adapter for `agents.sandbox.SandboxAgent`.
`MirageSandboxSession`	Per-conversation session bound to a workspace.
`MirageCapability`	`SandboxAgent` capability that lists the workspace’s mounts in the agent’s instructions.
`build_system_prompt`	Generates a system prompt that describes mounted paths to the model.

Examples

examples/python/agents/openai_agents/ram_agent.py, RAM-only sandbox.
examples/python/agents/openai_agents/sandbox_agent.py, SandboxAgent over RAM + S3 + Slack.

Getting Started

Access

AI Agents

VFS

CLIs

Watch

Runtimes

OpenAI Agents SDK

Install

Tools (`ShellTool` + `ApplyPatchTool`)

Sandbox Agent

Exports

Examples

​Install

​Tools (ShellTool + ApplyPatchTool)

​Sandbox Agent

​Exports

​Examples

Install

Tools (`ShellTool` + `ApplyPatchTool`)

Sandbox Agent

Exports

Examples