subagent-dag-orchestration

Sub-Agent DAG Orchestration

When to use

The trigger is a task that breaks into several distinct steps — not a task you have already decided needs sub-agents.

First, the hard bound. A DAG node dispatches only to a configured third-party sub-agent; it cannot call your own tools. So steps that are just your own tool calls — reading files, small edits, running commands — are not a DAG for being many or independent: do those yourself. The bound is about who can carry the work, not what kind of work it is: when the roster carries a specialist for it (a coding agent for code changes, an on-call agent for long runs) and the owner's request assigns the work that way, it clears the bound like any other. Only work a sub-agent on the roster could carry out gets as far as the tests below.

For work that clears that bound, test three things before running the steps one at a time:

• Independence — can two or more steps run at the same time? Independent nodes are scheduled concurrently, up to the shared sub-agent cap (max_concurrent_subagents — spawn draws on the same allowance).
• Handoff — does a step hand its result to the next one? A node's output is written to a file the downstream node reads, and the graph wires that handoff itself. A spawn can hand its result on too — it takes a node_id and a later task names it the same way a node does — but only across a turn of yours; a graph needs none.
• Specialism — do the steps want different sub-agents? The tool's own description lists the roster and what each one is for.

If any of the three holds, express the whole task as one run_subagent_dag call rather than dispatching sub-agents one at a time. Persistence is not one of the reasons: every node's prompt and output is written to disk, and so is every spawn's.

Iteration is graphs in series, not a cycle in one graph. A graph is acyclic and runs once. When the work loops — code changes feeding experiment rounds feeding the next code change — dispatch one graph per round and drive the loop yourself: each graph's outputs come back to you, and the next round's nodes reuse the same instance handles, so each side keeps its context across rounds.