> ## 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 API

> Make a Mirage workspace the self-hosted environment of an agent on OpenAI's Agents API.

OpenAI's [Agents API](https://developers.openai.com/api/docs/guides/agents-api/overview) runs the agent on OpenAI's servers. With a `self_hosted` environment, its shell commands, file reads and patches run in a Mirage workspace, under the workspace's profile and mount modes. No sandbox holds the files.

The workspace connects through Codex's exec-server relay, set up on the [Codex page](/typescript/agents/codex#exec-server-forward). The Agents API is in beta.

## Install

```bash theme={null}
npm install -g @struktoai/mirage-cli
npm install openai
```

## Workspace

`/workspace`, where OpenAI's examples work, is scratch space in memory. `/redis` keeps what the agent saves there after the workspace closes, which needs a Redis server and the `redis` package next to the CLI:

```yaml workspace.yaml theme={null}
mode: write
mounts:
  /workspace:
    vfs: ram
  /redis:
    vfs: redis
    config:
      url: redis://localhost:6379/0
```

```bash theme={null}
docker run -d -p 6379:6379 redis
npm install -g redis
mirage workspace create workspace.yaml --id demo
printf 'customer,item,amount\nacme,widget,120\nglobex,gadget,75\nacme,gizmo,30\ninitech,widget,60\nglobex,widget,45\n' \
  | mirage shell -w demo -c 'cat > /workspace/orders.csv'
```

## Create a session

```ts theme={null}
import OpenAI from 'openai'

const client = new OpenAI()
const session = await client.beta.agents.sessions.create({
  agent: { model: 'gpt-6-luna' },
  environment: { type: 'self_hosted', workspace_directory: '/workspace' },
})
console.log(session.environment.id, session.environment.remote_url)
```

## Connect the workspace

Hand the session's `environment.id` and `environment.remote_url`, with an [environment key](https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted#authentication), to [`codex exec-server forward`](/typescript/agents/codex#exec-server-forward) pointed at workspace `demo`. The agent's commands then run in the workspace, and what it writes lands in its mounts.

## Run a task

Open the session's event stream, then send the task. The agent's reply streams back while its commands run in the workspace:

```ts theme={null}
import { randomUUID } from 'node:crypto'

const stream = await client.beta.agents.sessions.events.stream(session.id)
await client.beta.agents.sessions.events.create(session.id, {
  events: [
    {
      type: 'agent.session.input.message',
      input: [
        {
          role: 'user',
          content: [{ type: 'input_text', text: 'Total the amount per customer in /workspace/orders.csv and save the totals as a markdown table to /redis/report.md.' }],
        },
      ],
    },
  ],
  'Idempotency-Key': randomUUID(),
})
for await (const event of stream) {
  if (event.type === 'agent.session.turn.output_text.delta') process.stdout.write(event.delta)
  else if (event.type === 'agent.session.turn.completed' || event.type === 'agent.session.turn.failed') break
}
```

The report stays in Redis after the session ends:

```bash theme={null}
mirage shell -w demo -c 'cat /redis/report.md'
```

## Example

[`examples/typescript/agents/openai_agents_api/redis_report.ts`](https://github.com/strukto-ai/mirage/blob/main/examples/typescript/agents/openai_agents_api/redis_report.ts) runs the whole flow: it seeds `/workspace/orders.csv`, starts `mirage codex-exec` and `codex exec-server forward`, sends the task and prints the report.


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