> ## 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](/python/agents/codex#exec-server-forward). The Agents API is in beta.

## Install

```bash theme={null}
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:

```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
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

```python theme={null}
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](https://developers.openai.com/api/docs/guides/agents-api/environments/self-hosted#authentication), to [`codex exec-server forward`](/python/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:

```python theme={null}
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:

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

## Example

[`examples/python/agents/openai_agents_api/redis_report.py`](https://github.com/strukto-ai/mirage/blob/main/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.


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