Agent Run Groups

Agent Run Groups are the durable control-plane object for multi-agent fanout. Use a group when one user request creates many related Agent Runs across sandboxes, computers, or custom runtimes.

Base path: /api/v1/agent-run-groups

Endpoints

Create

POST /api/v1/agent-run-groups
Authorization: Bearer msk_live_...
Content-Type: application/json

{
  "name": "clinic-iq-browser-checks",
  "workspace_id": "ws_123",
  "project_id": "proj_123",
  "concurrency_limit": 25,
  "expected_runs": 100,
  "metadata": {
    "user_task_id": "task_123"
  }
}

Dispatch

Dispatch accepts a runs array. Each entry uses the same fields as Agent Runs, plus optional orchestration_role and parent_agent_run_id.

POST /api/v1/agent-run-groups/{id}/dispatch
Authorization: Bearer msk_live_...
Content-Type: application/json

{
  "runs": [
    {
      "sandbox_id": "sbx_code_1",
      "provider": "claude-code",
      "cwd": "/workspace",
      "prompt": "Implement the pricing page and export /workspace/report.html",
      "orchestration_role": "coder",
      "metadata": {
        "artifact_paths": ["/workspace/report.html"]
      }
    },
    {
      "computer_id": "cmp_browser_1",
      "provider": "osa",
      "prompt": "Open the preview, test signup, and capture screenshots.",
      "orchestration_role": "browser-qa"
    }
  ],
  "async": true
}

Set async to true when the group should queue entries and return before the child Agent Runs are created. MIOSA creates one durable entry per manifest item, then dispatcher workers claim entries under the group’s concurrency_limit.

Current dispatch batches are capped at 100 entries per request. For larger fleets, shard logical work into multiple groups or dispatch batches from your backend.

Response

{
  "data": {
    "group": {
      "id": "grp_123",
      "name": "clinic-iq-browser-checks",
      "status": "running",
      "concurrency_limit": 25,
      "expected_runs": 100,
      "counts": {
        "total": 2,
        "running": 0,
        "succeeded": 2,
        "failed": 0,
        "canceled": 0
      },
      "entry_counts": {
        "total": 2,
        "queued": 0,
        "running": 0,
        "succeeded": 2,
        "failed": 0,
        "canceled": 0
      }
    },
    "results": [
      {
        "index": 0,
        "ok": true,
        "run": {
          "id": "run_123",
          "agent_run_group_id": "grp_123",
          "orchestration_role": "coder",
          "status": "succeeded"
        }
      }
    ],
    "entries": []
  }
}

Async dispatch returns entries immediately and usually returns an empty results array:

{
  "data": {
    "group": {
      "id": "grp_123",
      "status": "running",
      "concurrency_limit": 25,
      "entry_counts": {
        "total": 2,
        "queued": 2,
        "running": 0,
        "succeeded": 0,
        "failed": 0,
        "canceled": 0
      }
    },
    "results": [],
    "entries": [
      {
        "id": "agre_123",
        "agent_run_group_id": "grp_123",
        "index": 0,
        "status": "queued",
        "attempts": 0
      }
    ]
  }
}

Events

Use group events when your UI needs one stream for an entire multi-agent task. MIOSA records child Agent Run events and replays them through the group in sequence order. This lets your product render progress from the coder, tester, browser QA agent, and deployment verifier without opening one stream per child run.

Replay existing events as JSON:

GET /api/v1/agent-run-groups/{id}/events
Authorization: Bearer msk_live_...

Stream existing events plus live events with SSE:

GET /api/v1/agent-run-groups/{id}/events?stream=true
Accept: text/event-stream
Authorization: Bearer msk_live_...

Event payloads include the group id, child run id, event sequence, event type, message, payload, and timestamp:

{
  "data": [
    {
      "id": "ev_123",
      "agent_run_group_id": "grp_123",
      "agent_run_id": "run_123",
      "sequence": 4,
      "type": "command_finished",
      "message": "Command completed",
      "payload": {
        "exit_code": 0
      },
      "created_at": "2026-06-15T21:20:00Z"
    }
  ]
}

Terminal group states close the SSE response after replay. Running groups keep the stream open and emit heartbeat comments while waiting for new child events.

SDK

CLI

miosa agent-run-groups create 
  --name "clinic-iq-browser-checks" 
  --workspace ws_123 
  --concurrency 25 
  --expected-runs 100 
  --json

miosa agent-run-groups dispatch grp_123 
  --run '{"sandbox_id":"sbx_code_1","provider":"claude-code","prompt":"Build and export report","metadata":{"artifact_paths":["/workspace/report.html"]}}' 
  --async 
  --json

miosa agent-run-groups show grp_123 --runs --json
miosa agent-run-groups events grp_123 --json
miosa agent-run-groups events grp_123 --stream --limit 100
miosa agent-run-groups cancel grp_123 --json

Next