OpenAI Agents SDK

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

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

pnpm add @struktoai/mirage-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,
  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.

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, RAM-only sandbox.
examples/typescript/agents/openai/multi_vfs_agent.ts, RAM + S3 mounts.
examples/typescript/agents/openai/sandbox_agent.ts, SandboxAgent over a RAM workspace with a read-only data mount.
examples/typescript/agents/openai/snapshot.ts, branch & roll back agent state.

Getting Started

Access

AI Agents

VFS

CLIs

Watch

Runtimes

OpenAI Agents SDK

Install

Usage

Sandbox Agent

Exports

Examples

​Install

​Usage

​Sandbox Agent

​Exports

​Examples

Install

Usage

Sandbox Agent

Exports

Examples