> ## 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 in Python

> 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 loop on OpenAI's servers. With a `self_hosted` environment, Mirage serves that environment: the agent's shell commands, file reads and patches run in a Mirage workspace, under its profile and mount modes, and what the agent writes lands in its mounts. The workspace connects through Codex's exec-server relay, set up on the [Codex page](https://docs.mirage.strukto.ai/home/agents/codex.md#exec-server-forward). The Agents API is in beta.

## Install

```bash theme={null}
uv tool install 'mirage-ai[ssh,redis]'
uv add openai
npm install -g @openai/codex@alpha
```

## Usage

### Workspace

`/workspace`, where OpenAI's examples work, is scratch space in memory. `/redis` keeps what the agent saves there after the workspace closes:

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

```bash theme={null}
docker run -d -p 6379:6379 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`](https://docs.mirage.strukto.ai/home/agents/codex#exec-server-forward) pointed at workspace `demo`. The agent's commands then run in the workspace.

### Run a task

Open the session's event stream, then send the task. The reply streams back while the agent's 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",
            "agent.session.turn.cancelled",
        ):
            break
```

The report stays in Redis after the session ends:

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

## Tools

The agent keeps the Agents API's own tools. Its shell commands, file reads and patches arrive through the exec-server and run in the workspace as Mirage shell lines and file operations, held to the session's profile and the mounts' modes.

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