Skip to main content
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]'
This pulls in openai>=2.30 and openai-agents>=0.14.7.

​
Tools (ShellTool + ApplyPatchTool)

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.resource.ram import RAMResource

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

agent = Agent(
    name="Mirage RAM Agent",
    model="gpt-5.5-mini",
    instructions=build_system_prompt(
        mount_info={"/": "In-memory filesystem (read/write)"},
    ),
    tools=[
        ShellTool(executor=MirageShellExecutor(ws)),
        ApplyPatchTool(editor=MirageEditor(ws)),
    ],
)

​
Sandbox Agent

For the new SandboxAgent API, use MirageSandboxClient: 
from agents.sandbox import SandboxAgent
from mirage.agents.openai_agents import MirageSandboxClient

client = MirageSandboxClient(ws)
agent = SandboxAgent(name="...", model="gpt-5.5", instructions=ws.file_prompt)

​
Exports

SymbolPurpose
MirageShellExecutorDrop-in ShellTool executor, runs inside Workspace.execute().
MirageEditorDrop-in ApplyPatchTool editor, patches go through Mirage FS ops.
MirageSandboxClientAdapter for agents.sandbox.SandboxAgent.
MirageSandboxSessionPer-conversation session bound to a workspace.
build_system_promptGenerates a system prompt that describes mounted paths to the model.

​
Examples