> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Agents SDK

> Run openai-agents against a Mirage workspace using MirageShellExecutor, MirageEditor, MirageSandboxClient, and MirageCapability.

The OpenAI Agents Python SDK ([openai-agents](https://github.com/openai/openai-agents-python)) 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

```bash theme={null}
uv add 'mirage-ai[openai]'
```

## Tools (`ShellTool` + `ApplyPatchTool`)

```python theme={null}
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:

```python theme={null}
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`](https://github.com/strukto-ai/mirage/blob/main/examples/python/agents/openai_agents/ram_agent.py), RAM-only sandbox.
* [`examples/python/agents/openai_agents/sandbox_agent.py`](https://github.com/strukto-ai/mirage/blob/main/examples/python/agents/openai_agents/sandbox_agent.py), `SandboxAgent` over RAM + S3 + Slack.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.