> ## 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, and MirageSandboxClient.

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]'
```

This pulls in `openai>=2.46` and `openai-agents>=0.18.3`.

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

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

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

| Symbol                 | Purpose                                                              |
| ---------------------- | -------------------------------------------------------------------- |
| `MirageShellExecutor`  | Drop-in `ShellTool` executor, runs inside `Workspace.execute()`.     |
| `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.                       |
| `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.