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

Getting Started

Agents

Resources

CLIs

Watch

Runtimes

OpenAI Agents SDK

Install

Usage

Exports

Examples

​Install

​Usage

​Exports

​Examples

Install

Usage

Exports

Examples