Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.neoagent.io/llms.txt

Use this file to discover all available pages before exploring further.

The Dispatch Subagents tool lets an agent split a workload into N parallel slices, hand each to a fresh subagent, and resume automatically when all the subagents have finished. Each subagent runs its own agent loop in its own ephemeral sandbox — they don’t see each other or the parent’s conversation, only the instructions they were given. Use this when you have a workload that’s naturally parallel — generating one SOP per cluster of similar tickets, summarizing one company at a time, or any task where the slices don’t need to be stylistically consistent with each other. Don’t use it for work where the slices have to fit together (a coherent app build, a single long-form essay, a refactor that spans many files) — parallel subagents make independent decisions and produce conflicting outputs.
This tool is off by default per agent. Turn it on with the Subagent fan-out switch in the agent’s settings (Agent Settings → Subagent fan-out). It’s also gated by tool tier — every dispatch counts as Advanced because each subagent is a full agent run with its own LLM and sandbox.

​
What It Does

ToolWhat it doesTier
Dispatch SubagentsStart N parallel subagents (5–10 typical, 20 max), pause until they all finish, then resume with a summary per subagentAdvanced
Typical uses:
  • Bulk per-entity generation — produce one tailored output per company / per ticket cluster / per device, in parallel rather than sequentially.
  • Independent research — ask multiple subagents to investigate different angles of the same question and aggregate their findings.
  • Breadth-first audits — sweep N systems for the same condition, each in its own sandbox, without serial waits.

​
How It Works

When the parent agent calls Dispatch Subagents:
  1. The agent provides a list of specs — each spec has a spec_id (short label, e.g. clusters-1-32) and detailed instructions for that slice. Subagents do not see the parent’s conversation; the instructions must be self-contained.
  2. The parent pauses. Up to max_in_flight subagents (default 5) run at a time; the rest queue.
  3. Each subagent has its own sandbox, its own conversation thread, and its own copy of the parent’s toolbox. It runs the standard agent loop on the instructions it was given.
  4. When all subagents finish (success or failure), the parent resumes automatically. It sees a list of results — one entry per spec, with a short summary and a status (success / failed).
The parent never calls Dispatch Subagents again to “check” on running subagents — the resume happens once, and the next turn already has the aggregated results.

​
Safety

ControlBehavior
Off by defaultThe tool is hidden unless Subagent fan-out is on in the agent’s settings. Existing agents are unaffected until you opt in.
Hard cap of 20 subagents per dispatchAn agent that asks for more is rejected — multi-agent systems get expensive fast when over-spawned. Split into multiple dispatches if you genuinely need more.
Runtime ceiling per subagentDefault 30 minutes per slice. Subagents that run past their ceiling are stopped and surface a TIMEOUT status to the parent — they don’t quietly consume sandbox-minutes.
Token budget per subagentOptional. When set, a subagent halts its own loop once it has spent the budget. Useful for keeping per-dispatch cost predictable when the workload is open-ended.
No recursionSubagents themselves don’t get the Dispatch Subagents tool — there’s no fanning out from inside a fanned-out subagent. This caps the worst-case cost and complexity.

​
When NOT to Use It

Workload shapeWhy fan-out hurts
Building a coherent app or documentThe slices have to fit together. Parallel subagents make conflicting choices (different styling, different naming) and the result doesn’t compose.
Sequential workflowsIf step 2 depends on step 1’s output, there’s nothing to parallelize. Use the regular agent loop.
A handful of leaf callsIf the work is “make 10 API calls and aggregate,” a single agent with the right tools is cheaper than 10 subagents. Fan-out adds value when each slice has its own reasoning loop.
Anything write-heavy with shared stateTwo subagents updating the same ticket or the same document can step on each other. Keep writes single-threaded.