/subagent-dag-orchestration

name: subagent-dag-orchestration
description: Use when a task breaks into several distinct steps that a separate sub-agent could each carry out. A DAG node dispatches to an agent on the roster and 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 - 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 request assigns the work that way, it clears the bound like any other. For work that clears it, test three things before running the steps one at a time: are two or more steps independent (they can run at once), does a step hand its result to the next (a graph wires that handoff with no turn of yours in between), do the steps want different specialists (the tool lists the roster). If any of the three holds, orchestrate the whole task as one run_subagent_dag call. Iteration is graphs in series, one graph per round, driven by you.
metadata: {"raven":{"emoji":"🕸️","always":true,"inject":"description","requires":{"tools":["run_subagent_dag"]}}}

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.

If none of the three holds, the graph buys you nothing — dispatch the work as a single `spawn`, which is the right call exactly when the task is genuinely one sub-agent doing one thing. The work you do yourself is the work that never cleared the bound above, not this.

Every install can run a graph: raven's own agents are on the roster whether or not any third-party agent is configured, so `run_subagent_dag` is always available. Which agents exist is still the tool description's answer, not this file's — read the roster there.

Write the brief as the owner gave it

A node sees only its prompt. Whatever the owner asked for, and whatever the owner allowed the node to change, reaches the node only if the prompt carries it -- and the prompt is where a whole run's search space gets narrowed without anyone deciding to narrow it. Three rules, each from a measured loss on 2026-09-08, where a two-round search left the one knob worth most of the result untouched:

• **The owner's words and scope go in as written; your steer is marked as yours.** Quote

the owner's request in every node's brief, not only the first round's. Your own reading of where the gains are is welcome as a suggestion, and it stays a suggestion: "gains can only come from ..." is a boundary the owner never drew. That day the owner allowed "training configuration, data mix, architecture, algorithm"; the round-one brief added "the hyperparameters are exhausted, so gains can only come from three classes outside the falsified list", and the round-two brief to the experiment runner opened with "you change no case". The runner changed nothing in 26 scored runs. One plain training setting, the kind the runner owned, was worth most of the gap to the best known result. It was never tried.

• **A list of tried things stays a list; it does not become a category.** When a handover

names settings already swept, pass the list itself and ask the node to check what is *not* on it before it picks directions. Eighteen named hyperparameter groups became "the hyperparameters are exhausted"; the setting that mattered was on neither.

• **Each role's brief states the whole of its role, not this round's chores.** If the owner

gave the experiment runner the training configuration, the runner's brief says so every round, whether or not you expect it to matter this round. A duty left out of the brief is a duty the node takes to be someone else's.

How it works

You submit a flat list of `nodes`. A scheduler runs every node whose dependencies are met,