Agent Orchestration Configuration
Agent Orchestration Configuration
The Agent Orchestration ability lets an agent spawn purpose-built helper agents. This article covers every configuration setting and how they interact.
Per-Agent Settings
These settings appear in the agent configuration panel under the Agent Orchestration ability card. Each agent can have its own limits.
Max Concurrent Spawns (default: 3)
How many forked spawns can execute at once. When the orchestrator fires off many helpers in parallel, only this many actually run their full agent loop simultaneously — the rest queue up and start as slots free. Higher values mean faster fan-out but more server load on the host machine.
Important: Blocking spawns (wait=True) bypass this limit entirely — they run inline under the caller and don't count against the concurrency cap.
Max Spawns per Agent (default: 5)
Total number of helper agents this orchestrator can spawn across a single chat session. Once the limit is hit, calls are refused. This prevents an orchestrator from accidentally or deliberately flooding the system with workers.
Counts ALL spawns created in the session — including those that finished, errored, or were stopped. Stopped/finished spawns still count against the cap.
Max Spawns per Spawn (default: 1)
How many sub-helpers a spawned clone is allowed to create. This governs recursion breadth at each level of the tree.
- Set to 0 to forbid spawned clones from spawning anything — even if they have the orchestration ability enabled. The main agent can still spawn normally.
- Default of 1 means each clone makes at most one helper of its own.
- Higher values allow a spawn to fork multiple parallel sub-workers.
Max Spawn Depth (default: 2)
How many levels of spawns-within-spawns are allowed. The main agent is level 0; each spawn increments depth by 1.
- 0 — Only the main agent can spawn direct helpers. All clones are leaf workers (cannot spawn), even if given the orchestration ability.
- 1 — The main agent's direct spawns can also create one more level of helpers.
- 2 (default) — Allows three total levels: main agent → level-1 spawns → level-2 spawns. Level-2 spawns are leaf workers.
- Max is 5.
Auto-Stop on Session End (default: On)
When the orchestrator's chat session ends (user closes the tab or navigates away), automatically stop all running and queued spawns. Turn this off only if you need long-running spawns to outlive the chat session — but be aware they'll consume resources with nobody to receive their results.
Default Spawn Mode (default: Fork)
How spawns run when the orchestrator doesn't explicitly pick:
- Fork (Off) — The spawn queues up and runs in parallel. The orchestrator gets re-woken with an [ORCHESTRATION EVENT] when it finishes. Keeps the conversation moving.
- Wait (On) — The orchestrator blocks inline and waits for the spawn's full reply before continuing. Simpler for sequential chains but pauses the session.
The orchestrator can always override this per-spawn with the parameter.
Not Yet Configurable per Agent
These limits exist in the code but aren't yet exposed as per-agent settings — they use fixed defaults:
Clone Max Turn Count (fixed: 20 turns)
A separate turn limit applied to every spawned clone. Prevents a misdirected clone from looping endlessly on a narrow task. This is separate from the orchestrator's own on the Limits table. Twenty turns is generous for focused tasks while still catching runaway loops.
Clone Wall Clock (fixed: 300 seconds / 5 minutes)
A time cap applied to every spawned clone. Cuts off a spawn that hasn't finished within the window — catches hanging tool calls, slow models, and zombies. Separate from the orchestrator's own .
How Settings Interact
A typical tree under defaults (spawns-per-agent=5, spawns-per-spawn=1, depth=2, concurrent=3):
With spawns-per-spawn=0 or depth=1, the tree stops at level 1 — only 5 spawns total, no grandchildren.
With spawns-per-agent=3 and spawns-per-spawn=2, the tree can go deeper but narrower — 3 level-1 spawns each create 2 sub-spawns for 9 total.
Safety Notes
- A clone with orchestration ability but spawns-per-spawn=0 cannot create sub-helpers regardless of its abilities — the per-spawn cap wins.
- Depth is checked for non-root parents only: the main agent can always spawn direct helpers regardless of max_spawn_depth.
- Concurrent cap is global across all sessions for that agent — spawning in two chats simultaneously shares the same limit.
- Stopped or errored spawns still count against max_spawns_per_agent. Clean them up (or the session) to free slots.',