Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Protocol

Clients drive episodes over a WebSocket at /ws, in OpenEnv frames. Agents can also call the tools over MCP at /mcp, and a harness can start and end their episodes over HTTP. The Python client speaks the WebSocket for you.

Frames

Every frame is a JSON object with a type and, for most, data:

{"type": "reset", "data": {"task_id": "pay-invoice"}}
FramedataReply
resetwhich task, and options (below)observation: the task the agent starts on
stepan action (below)observation: the tool list or the call’s result
statenonestate: episode_id, step_count, task_id, done, reward, success
recordepisode_id, optionalrecord: the finished episode’s record
coworkers{}coworkers: the turns coworkers owe
coworker_replycoworker, textcoworker_reply: the app’s HTTP status
closenonethe server closes the socket

An error comes back as {"type": "error", "data": {"code": "...", "message": "..."}}. The codes are INVALID_JSON, VALIDATION_ERROR, UNKNOWN_TYPE, EXECUTION_ERROR, SESSION_ERROR and CAPACITY_REACHED.

Reset

FieldWhat
task_idthe task to run; wins over the others
splitthe split to draw from; train by default
indexthe split’s task at this index, in id order
seedthe split’s task at seed mod the number of tasks
episode_idan id for the episode, 1 to 255 characters; a UUID by default
max_secondsafter this many seconds, the next call ends the episode as it stands
coworkerstrue if the client answers coworkers

With neither task_id, index nor seed, the task is drawn at random. Draws leave out tasks with coworkers unless coworkers is true.

The reply:

{"type": "observation", "data": {
  "observation": {
    "task_id": "pay-invoice",
    "instruction": "The customer on invoice INV-04001 asked us to charge their card...",
    "persona": {"name": "sales_manager", "description": "Dana Lee, sales manager at Acme"},
    "now": "2026-11-10T09:30:00Z",
    "max_steps": 20,
    "metadata": {"reset_s": {"kill": 0.05, "restore": 0.1, "total": 0.9}}
  },
  "reward": null,
  "done": false
}}

Step

A step lists the tools or calls one:

{"type": "step", "data": {"type": "list_tools"}}
{"type": "step", "data": {"type": "call_tool", "tool_name": "api_request",
  "arguments": {"method": "GET", "path": "/invoices?number=INV-04001"},
  "metadata": {"episode_id": "..."}}}

The reply carries the observation, the reward and done:

{"type": "observation", "data": {
  "observation": {"tool_name": "api_request", "error": null, "metadata": {},
                  "result": {"status": 200, "headers": {"content-type": "application/json"},
                             "body": [{"id": 4001, "number": "INV-04001", "status": "open"}]}},
  "reward": 0.0,
  "done": false
}}

A failed call has result: null and an error with an error_type (invalid_args, execution_error, transport_error, tool_not_found or timeout) and a message. The agent can go on after an error.

The step that ends the episode has done: true, the reward, and the episode’s metadata. The reward is null when the episode could not be graded. See Grading.

Pass the reset’s episode_id in each call’s metadata: a call for an earlier episode is refused instead of acting on the current one. Arguments set to null are dropped.

Coworker frames

coworkers returns {"turns": [{"coworker": "priya", "messages": [...]}]}, where messages is a chat to send to a model: a system message, then user and assistant messages. Send the model’s answer back:

{"type": "coworker_reply", "data": {"coworker": "priya", "text": "It's qualified."}}

MCP

POST /mcp speaks MCP over JSON-RPC (protocol 2025-06-18 or 2025-03-26): initialize, ping, tools/list and tools/call. Its query string takes:

ParameterWhat
surfaceapi (default): api_request, api_docs, wait, submit; code: run_code in place of api_request; mcp: the app’s MCP tools, wait and submit. wait is listed only for tasks with a clock
episode_idthe episode the calls are for
tokenthe bearer token, for clients that can’t send headers

MCP calls step the same episode as the WebSocket session, or as POST /episode, which does the reset. A tools/call result is the step’s observation, with MCP’s content and isError, and done and reward.

Episodes over HTTP

A harness whose agent speaks MCP alone, such as Claude Code or Codex, can run an episode with two HTTP requests in place of the WebSocket session:

curl -X POST http://127.0.0.1:8000/episode -H 'Authorization: Bearer secret' \
  --json '{"task_id": "pay-invoice"}'
# The agent works through http://127.0.0.1:8000/mcp ...
curl -X POST http://127.0.0.1:8000/episode/end -H 'Authorization: Bearer secret'
RouteBodyAnswer
POST /episodea reset frame’s data; empty draws a taskthe reset’s observation, reward and done, and the episode_id
POST /episode/endnonethe episode’s record

POST /episode holds the env as a session does: until POST /episode/end, /health says leased, and a second POST /episode or a WebSocket session is refused. POST /episode/end submits for the agent if the episode still runs, as the Python client’s finish() does, then answers the record and frees the env. Unlike a session, which ends when its socket closes, the episode holds the env until someone ends it: a harness that stops first leaves it held, and POST /episode/end frees it. Tasks with coworkers need the WebSocket session, whose frames answer for them.

Errors answer {"detail": "..."}: 400 for data the reset refuses, 409 when the env is held, or when no episode started over HTTP is running, and 500 when the reset or the end fails.

Give the agent MIROIR_AGENT_TOKEN, not MIROIR_TOKEN: it opens /mcp alone, so the agent can’t end its episode or start another. See Serve an env.