> ## 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 `MirageShell` 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-agents/openai` is runtime-agnostic. Pair it with `@struktoai/mirage-node` for Node or `@struktoai/mirage-browser` for the browser.

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

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

## Usage

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

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 MirageShell(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-agents/openai'

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, 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`).
* 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 |
| - | - |
| `mirageTools(ws, options?)` | Mirage's seven function tools (`shell`, `read`, `write`, `edit`, `ls`, `grep`, `glob`), the same table MCP serves; `read` hands images and PDFs over as model input. Works with Chat Completions and Responses. |
| `mirageReadFileTool(ws)` | Adds a `read_file` function tool. Text becomes `input_text`, images become `input_image`, and PDFs become `input_file`. |
| `MirageShell` | `Shell` implementation; pass to `shellTool({ shell })`. |
| `MirageEditor` | `Editor` implementation; pass to `applyPatchTool({ editor })`. |
| `MirageSandboxClient` | `SandboxClient` for `SandboxAgent`; pass as `run(agent, input, { sandbox: { client } })`. |
| `MirageSandboxSession` | Per-conversation session bound to a workspace. |
| `MirageCapability` | `SandboxAgent` capability that lists the workspace's mounts in the agent's instructions. |
| `buildSystemPrompt` | Generates a system prompt that describes mounted paths to the model. |
| `MIRAGE_SYSTEM_PROMPT` | The default system prompt template (used by `buildSystemPrompt`). |

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


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