Sub-Agent DAG Orchestration

When to use

The trigger is delegated work that breaks into several tasks.

The host's role decides what to delegate; this guide decides how to group the work. A DAG node dispatches to an agent on the roster, including Raven-General; it cannot call the host's tools. Choose from that tool's subagent parameter enum: agent names on ordinary turns, worker labels when a Worker Table is bound. A worker label selects the underlying agent together with that worker's brief. The roster describes the underlying agents' capabilities; its names are not dispatch values on a worker turn. The host's own coordination calls, such as reading a brief or checking task status, are not delegated tasks and do not need a graph just because there are several of them.

For the delegated tasks, test three things before dispatching them 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 roster at the end of the tool list says what each agent is for. When a Worker Table is bound, the subagent parameter also describes each worker's brief; choose a label that fits.

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.