Prime is your Chief of Staff Qor. It listens to your message, decides whether it can answer directly, and if not, delegates to a specialist Qor. The specialist runs its own agent loop, uses its own tools, and returns a result. Prime composes the final answer.

​
The delegation triad

​
Three tools make it happen

delegate_to_soul

Fire-and-forget. Kicks off a specialist’s loop in the background, Prime keeps chatting. Results stream back as they complete.

manage_agents

Spawn a new Qor on the fly. “Create a specialist called ‘Inbox Triage’ whose job is…” — Prime calls this when no existing Qor fits.

room

Multi-Qor collaboration. Prime opens a room, invites 3 specialists, they iterate. Good for tasks that need back-and-forth between agents.

​
When Prime delegates vs. answers directly

Prime’s system prompt tells it to delegate when any of these are true:
  • The task needs a specialised toolset (code IDE, browser, email, calendar)
  • The task will take >30 seconds
  • The task is parallelisable (research multiple topics, call multiple APIs)
  • An existing specialist already handles this domain
Prime answers directly when:
  • The request is conversational (“what’s your status?”, “summarise what we’ve discussed”)
  • The answer is in context or memory already
  • Delegation would be slower than just answering
You can tune this by editing Prime’s system prompt. Customising Prime →

​
The lifecycle

1

User message arrives

Web UI / channel webhook → POST /v1/chat/completions → Prime’s agent loop.
2

Prime decides to delegate

LLM emits a tool call like:
{
  "tool": "delegate_to_soul",
  "args": {
    "agent_name": "Researcher",
    "task": "find flights BOM → SIN next Friday"
  }
}
3

Specialist spawns

If Researcher exists → loaded. If not → manage_agents creates one with a default system prompt + Prime’s task.
4

Specialist runs its own loop

Uses its tools (here: flight_search, web_fetch). Writes to its own memory. Streams progress events to the delegation_card widget in the web UI so you can watch.
5

Report flows back

The specialist’s final message becomes a tool-result appended to Prime’s conversation. Prime resumes with that result in context.
6

Prime composes the final answer

Prime wraps the specialist’s output in a conversational response, formats it, sends to you.

​
What you see in the UI

Delegation card in the chat
The card shows:
  • Who Prime delegated to
  • The task text
  • Live status: delegating → running → done / failed
  • Live tool calls from inside the specialist (expandable)
  • Final output
Every delegation is also recorded in the audit log.

​
Async delegation — fire and forget

delegate_to_soul is non-blocking by default. Prime can dispatch three tasks in parallel and continue chatting with you. Results arrive via WebSocket events as each specialist finishes. 
You:     plan my week
Prime:   Delegating to 3 specialists…
         → Calendar Qor (reading this week's events)
         → Priority Qor (scoring tasks by urgency)
         → Brief Qor (drafting the summary)

Prime:   Here's your week. [result from Calendar, Priority, Brief all merged]

​
When Prime spawns vs. reuses

Prime uses list_souls first. If there’s a Qor whose role or title matches the task, Prime picks it. No spawning cost.
manage_agents(action="create", template="researcher") creates a Qor from the researcher built-in template. 10 built-in templates: researcher, coder, email_triage, writer, analyst, ops, reviewer, scheduler, social, support.
Prime can specify a completely custom system prompt, toolset, and model. “Create an agent called ‘CFO’ whose job is to…” with full control.
Spawned specialists default to persistent — they live in agents and can be re-used. If Prime passes ephemeral=true they’re deleted after the task completes. Default is persistent so you accumulate a useful specialist roster over time.

​
Rooms: when delegation isn’t enough

Sometimes a task needs specialists to talk to each other, not just report to Prime independently. That’s what rooms are for. Example — “produce a competitive analysis deck”:
  • Researcher investigates each competitor
  • Writer drafts the narrative
  • Reviewer critiques for accuracy
  • Writer revises based on critique
  • Reviewer approves
  • Prime takes the final deck and presents it
Rooms are created with the room tool, then specialists room_post messages to each other and room_decide when they reach consensus.

​
Safeguards

By default, specialists cannot delegate deeper than 3 levels (you → Prime → specialist → sub-specialist). Prevents runaway delegation chains. Configure in config.toml:
[limits]
max_delegation_depth = 3
A single Qor can’t be handling more than 5 tasks simultaneously (default). New delegations queue. Prevents a popular specialist from getting overwhelmed.
Each delegation has a token and tool-call budget. When exceeded, the specialist must wrap up — prevents one task burning your entire monthly API budget.
If a specialist tries to call a destructive tool (exec rm -rf, send_email, delete_file) and the Qor is in approval_required mode, the call pauses and shows you an approval prompt in Prime’s chat. Approvals →

​
Where next

delegate_to_soul tool

Full parameter reference and examples.

manage_agents tool

Spawn, configure, delete specialists.

Rooms

Multi-Qor collaboration patterns.

Approvals

Gating destructive operations.