> ## 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, and multimodal file-reading tools.

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, OpsRegistry, RAMResource, Workspace } from '@struktoai/mirage-node'
import { Agent, applyPatchTool, run, shellTool } from '@openai/agents'
import {
  MirageEditor,
  MirageShell,
  buildSystemPrompt,
  mirageReadFileTool,
} from '@struktoai/mirage-agents/openai'

const ram = new RAMResource()
const ops = new OpsRegistry()
for (const op of ram.ops()) ops.register(op)
const ws = new Workspace({ '/': ram }, { mode: MountMode.WRITE, ops })

const agent = new Agent({
  name: 'Mirage RAM Agent',
  model: 'gpt-5.5-mini',
  instructions: 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.")
```

The examples also support OpenAI-compatible providers. Set `OPENAI_API_KEY`, `OPENAI_BASE_URL`, and `OPENAI_MODEL`; a custom base URL defaults to Chat Completions, uses `mirageExecuteTool`, and disables OpenAI tracing so the third-party key stays with that provider. Set `OPENAI_API=responses` when a compatible endpoint implements the Responses API and the examples will use OpenAI's hosted shell and editor tools instead.

## Exports

| Symbol                   | Purpose                                                                                                                 |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `mirageExecuteTool(ws)`  | Adds an `execute` function tool backed by `ws`; 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 })`.                                                          |
| `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 resources 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_resource_agent.ts`](https://github.com/strukto-ai/mirage/blob/main/examples/typescript/agents/openai/multi_resource_agent.ts), RAM + S3 mounts.
* [`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.