Skip to content
SupaCloud Docs
Select themeSelect language

Run a coordinator with worker subtasks

A coordinator is an ordinary agent task whose profile may delegate work. Instead of implementing everything itself, it splits an issue stream into worker subtasks — each a real task with its own agent, branch, cost attribution and event feed — and runs the loop: plan capacity, delegate, wait, answer questions, steer, review, open PRs, report.

Everything below happens through the agent’s own MCP tools; you configure nothing beyond the profiles.

  1. Give the coordinator a delegation-capable profile. In Settings → Agent profiles, the coordinator’s profile needs the ops tier (supacloud.ops.*) so delegate_subtask and the hub tools are on its surface. Create a second, cheaper profile for the workers (its slug is what the coordinator passes when delegating). Workers can stay read-only.

  2. Plan before fanning out. A good coordinator prompt starts with the two read tools built for this:

    • capacity.get — the workspace’s used/free concurrency, the runner fleet’s slots, and the active children of the coordinator’s own tree. On a single-slot instance, delegating five workers at once only queues four.
    • limits.get — remaining per-task/per-hour tool budgets (per-profile overrides applied), the workspace money budget, and the free subtask slots (children per parent, descendants per root, delegation depth).

  3. Delegate and wait — blocking, not busy-looping. delegate_subtask(profile_slug, prompt) starts a worker; get_subtask_result(sub_task_id, wait_seconds) holds the answer server-side until the child finishes or the wait expires (wait_seconds up to 600, honoured in full unless the operator lowered the ceiling). On expiry the call returns wait_timed_out: true — the coordinator just calls it again. subtask.list is the streams overview between waits: every task in the tree with status, branch, linked issue and cost.

  4. Let the coordinator answer its workers’ questions. When a worker raises a question-class gate, the coordinator sees it via subtask.pending_gates and answers it itself with subtask.answer_gate — the worker resumes without a human in the loop. This is deliberately narrow: only questions. Tool, visual, danger and tier-change gates stay human-only, and a human still sees every gate in the approvals inbox — the escalation is additive, never exclusive.

  5. Steer a running worker. subtask.intervene(sub_task_id, message) delivers a message into a running child — a scope reminder, a course correction, an early stop hint. Only ancestors on the delegation chain may do this, and every delivery writes an audit row.

  6. Trust the continuation guard. A long stream means many wait rounds, and a model can drift into narrating instead of calling tools — which would end the session while workers still run. The runner’s continuation guard catches exactly that: a coordinator whose subtree is still active is resumed with a nudge to keep polling (bounded — after the cap it ends loudly as interrupted-and-resumable, never as a silent success).