Skip to main content
A dagraph workflow lives in a single YAML file. The file declares a set of named nodes, their dependencies, and the inputs they accept. When you run the file, dagraph validates the structure, resolves all dependency edges, and executes nodes in parallel waves — running every node whose dependencies have already completed.

​
Top-level structure

A minimal DAG file needs only a name and a nodes list. Every other top-level field is optional and adds progressively more behaviour.

​
Fields reference

​
string
required
The identifier for this workflow. Used in run logs and trace spans. Must be unique across your workflow library.
​
string
A human-readable summary of what the workflow does. Shown by agentgraph validate and in run listings.
​
list
required
The ordered list of node specifications. Node execution order is determined by dependency edges, not list order. See Node types for all available types and their fields.
The inputs map declares the parameters your workflow accepts from the CLI or a webhook call. Each key is the input name; the value is a schema object.
​
string
One of string, integer, number, or boolean. Defaults to string. dagraph coerces the raw CLI string to this type before the first node runs, so a typo like --input count=three fails immediately with a clear error.
​
boolean
Whether the input must be provided. Defaults to true. Set to false and provide a default for optional parameters.
​
string | integer | number | boolean
Default value used when the input is absent and required: false.
​
string
Documents the parameter. Displayed by agentgraph validate to self-document the DAG.
Pass inputs at run time:
The budget block sets a hard upper limit on the entire run. If either limit is reached, dagraph stops all in-flight nodes immediately and marks the run as failed.
​
integer
Maximum number of billable tokens (input + output) across all nodes. Cache-creation overhead from the claude_code backend is excluded.
​
float
Maximum equivalent API cost in US dollars. Useful when mixing models with different per-token prices.
You can also set a per-node budget on any individual node using the same budget: field. See Node types for details.
The outputs map writes the text output of specific nodes to files on disk after a successful run. Nothing is written for paused or failed runs.
​
string
Maps an output file path (relative to the working directory) to a node ID. The node’s text output is written to that path when the run completes successfully. Parent directories are created automatically.
The hooks map attaches callbacks to DAG lifecycle events. Hook failures never fail the DAG itself.
​
list
Supported events: on_dag_start, on_dag_complete, on_dag_paused, on_dag_failed. Each value is a list of hook specifications — either a webhook (JSON POST) or a shell command.

​
Template variables

dagraph uses Jinja2 to render prompts and commands at run time. Two scopes of variables are available inside any prompt or command string.

​
Input variables

Reference any declared input by name:

​
Upstream node outputs

Reference the text output of any completed upstream node by its id:
When a node’s output is a JSON array (such as from a map node), you can iterate over it:
dagraph’s Jinja environment uses StrictUndefined, so a typo in a variable name will fail the node immediately with a clear error message rather than silently inserting an empty string.

​
Externalising prompts with prompt_file and system_file

Long prompts are easier to read, review, and diff when stored in separate text files. Use prompt_file instead of prompt, and system_file instead of system. Paths resolve relative to the directory containing the YAML file.
You cannot set both prompt and prompt_file on the same node — dagraph will reject the file at validation time.

​
Complete annotated example

The following example is taken from the dagraph examples directory. It defines three parallel research agents followed by a synthesizer that fans in their outputs.
Run it with: