> ## 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 with shell, editor, file-reading tools, and a SandboxAgent client.

The OpenAI Agents SDK ([@openai/agents](https://github.com/openai/openai-agents-js)) ships `shellTool` and `applyPatchTool` primitives that take pluggable `Shell` and `Editor` backends. Mirage provides `MirageShellExecutor` and `MirageEditor` implementations that route every command and patch through your `Workspace` instead of the host shell. `mirageReadFileTool` adds agent-initiated file reads with structured model input for text, images, and PDFs.

## Install

`@struktoai/mirage-openai-agents` is runtime-agnostic. Pair it with `@struktoai/mirage-node` for Node or `@struktoai/mirage-browser` for the browser.

```bash Node theme={null}
pnpm add @struktoai/mirage-openai-agents @struktoai/mirage-node @openai/agents
```

```bash Browser theme={null}
pnpm add @struktoai/mirage-openai-agents @struktoai/mirage-browser @openai/agents
```

## Usage

```ts theme={null}
import { MountMode, RAMVFS, Workspace } from '@struktoai/mirage-node'
import { Agent, applyPatchTool, run, shellTool } from '@openai/agents'
import {
  MirageEditor,
  MirageShellExecutor,
  buildSystemPrompt,
  mirageReadFileTool,
} from '@struktoai/mirage-openai-agents'

const ws = new Workspace({ '/': new RAMVFS() }, { mode: MountMode.WRITE })

const agent = new Agent({
  name: 'Mirage RAM Agent',
  model: 'gpt-5.5-mini',
  instructions: await buildSystemPrompt({
    mountInfo: { '/': 'In-memory filesystem (read/write)' },
  }),
  tools: [
    mirageReadFileTool(ws),
    shellTool({ shell: new MirageShellExecutor(ws) }),
    applyPatchTool({ editor: new MirageEditor(ws) }),
  ],
})

await run(agent, "Create /hello.txt with 'hi from mirage' and cat it.")
```

For an OpenAI-compatible provider without the Responses API, give the agent `mirageTools(ws)`, Mirage's seven function tools, instead of the hosted shell and editor tools.

## 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. The client also needs `@openai/agents-core`, at the same version as `@openai/agents`.

```ts theme={null}
import { run } from '@openai/agents'
import { Capabilities, SandboxAgent } from '@openai/agents/sandbox'
import { MirageCapability, MirageSandboxClient } from '@struktoai/mirage-openai-agents'

const agent = new SandboxAgent({
  name: 'Mirage Sandbox Agent',
  model: 'gpt-5.5',
  capabilities: [...Capabilities.default(), new MirageCapability()],
})
const result = await run(agent, 'Summarize /data/report.csv into /notes.md.', {
  sandbox: { client: new MirageSandboxClient(ws) },
})
```

How the session behaves:

* Every command starts at the manifest root, `/` unless you configure a `Manifest`, or at the model's `workdir`, 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. Its commands run in it side by side, so one left running in the background does not hold up the next.
* 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`).
* Relative paths resolve against the manifest root. Manifest `file` and `dir` entries are written into the workspace; other entry types raise `SandboxUnsupportedFeatureError`.
* A run paused for tool approval resumes on the same workspace and keeps the files the agent wrote.

## Exports

| Symbol | Purpose |
| - | - |
| `MirageCapability` | Tell a SandboxAgent's model which Mirage mounts it is working in. |
| `MirageEditor` | An `Editor` that applies patches through the workspace's file operations; pass it to `applyPatchTool({ editor })`. |
| `mirageTools` | Returns Mirage's tools (`shell`, `read`, `write`, `edit`, `ls`, `grep`, `glob`) as OpenAI Agents function tools, limited to what the session's profile allows. |
| `mirageReadFileTool` | Returns a `read_file` function tool: text comes back as text, images as image input and PDFs as file input the model can see. |
| `MirageReadFileOutput` | What the `read_file` tool returns: text, an image, or a file such as a PDF, as the model receives it. |
| `MirageSandboxClient` | The OpenAI Agents SDK sandbox client over an in-process Mirage workspace. |
| `MirageSandboxSession` | One SDK sandbox session, backed by its own Mirage shell session. |
| `MirageSandboxSessionState` | The serializable state of a `MirageSandboxSession`: the SDK's sandbox state plus `mirageSessionId`, the Mirage session it runs in. |
| `MirageShellExecutor` | A `Shell` that runs each command in the workspace's shell; pass it to `shellTool({ shell })`. |
| `MIRAGE_SYSTEM_PROMPT` | The default system prompt: how the Mirage filesystem differs from a plain one. |
| `buildSystemPrompt` | Returns `MIRAGE_SYSTEM_PROMPT` followed by a description of the mounted paths and any extra instructions, ready to use as an agent's system prompt. |
| `BuildSystemPromptOptions` | Options for `buildSystemPrompt`: which mounts to describe and what to append. |

Unsupported binary formats return a metadata description instead of being decoded as corrupt text. The tool reads raw workspace bytes, so files mounted from RAM, S3, and other Mirage mounts use the same model-input path.

## Examples

* [`examples/typescript/agents/openai_agents/ram_agent.ts`](https://github.com/strukto-ai/mirage/blob/main/examples/typescript/agents/openai_agents/ram_agent.ts), RAM-only sandbox.
* [`examples/typescript/agents/openai_agents/multi_vfs_agent.ts`](https://github.com/strukto-ai/mirage/blob/main/examples/typescript/agents/openai_agents/multi_vfs_agent.ts), RAM + S3 mounts.
* [`examples/typescript/agents/openai_agents/sandbox_agent.ts`](https://github.com/strukto-ai/mirage/blob/main/examples/typescript/agents/openai_agents/sandbox_agent.ts), `SandboxAgent` over a RAM workspace with a read-only data mount.
* [`examples/typescript/agents/openai_agents/snapshot.ts`](https://github.com/strukto-ai/mirage/blob/main/examples/typescript/agents/openai_agents/snapshot.ts), branch & roll back agent state.


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