OpenAI Agents API

OpenAI’s Agents API 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. The Agents API is in beta.

Install

uv tool install 'mirage-ai[ssh]'
uv add 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 extra:

workspace.yaml

mode: write
mounts:
  /workspace:
    vfs: ram
  /redis:
    vfs: redis
    config:
      url: redis://localhost:6379/0

docker run -d -p 6379:6379 redis
uv tool install 'mirage-ai[ssh,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

from openai import OpenAI

client = OpenAI()
session = client.beta.agents.sessions.create(
    agent={"model": "gpt-6-luna"},
    environment={"type": "self_hosted", "workspace_directory": "/workspace"},
)
print(session.environment.id, session.environment.remote_url)

Connect the workspace

Hand the session’s environment.id and environment.remote_url, with an environment key, to 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:

import uuid

with client.beta.agents.sessions.events.stream(session.id) as stream:
    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=str(uuid.uuid4()),
    )
    for event in stream:
        if event.type == "agent.session.turn.output_text.delta":
            print(event.delta, end="")
        elif event.type in ("agent.session.turn.completed", "agent.session.turn.failed"):
            break

The report stays in Redis after the session ends:

mirage shell -w demo -c 'cat /redis/report.md'

Example

examples/python/agents/openai_agents_api/redis_report.py 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.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

OpenAI Agents API

Install

Workspace

Create a session

Connect the workspace

Run a task

Example

​Install

​Workspace

​Create a session

​Connect the workspace

​Run a task

​Example

Install

Workspace

Create a session

Connect the workspace

Run a task

Example