OpenAI Agents SDK

The OpenAI Agents SDK (@openai/agents) 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.

pnpm add @struktoai/mirage-openai-agents @struktoai/mirage-node @openai/agents

pnpm add @struktoai/mirage-openai-agents @struktoai/mirage-browser @openai/agents

Usage

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.

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, RAM-only sandbox.
examples/typescript/agents/openai_agents/multi_vfs_agent.ts, RAM + S3 mounts.
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, branch & roll back agent state.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

OpenAI Agents SDK

Install

Usage

Sandbox Agent

Exports

Examples

​Install

​Usage

​Sandbox Agent

​Exports

​Examples

Install

Usage

Sandbox Agent

Exports

Examples