Pipelines let you define multi-stage AI workflows as directed graphs using Graphviz DOT syntax. Each node in the graph is a task — an LLM call, a human review gate, a conditional branch, or a parallel fan-out — and edges define the flow between them.

Pipelines are declarative: you describe what the workflow looks like, and the execution engine decides how and when to run each stage.

A pipeline is a digraph block in a workflow file. Here is a minimal pipeline that searches for literature, summarizes findings, and drafts a report:

Key elements:

Every node represents a task in the pipeline. The node's shape determines what kind of task it is. In practice, you rarely need to set shape explicitly — the shorthand conventions below (node ID prefixes and property shortcuts) cover most use cases and are more readable.

The recommended approach is to use node ID prefixes (e.g. Review, CheckQuality, FanOut) or property shortcuts (e.g. ask="...", branch="...", shell="...") instead of explicit shape= attributes. These shorthands are self-documenting and reduce boilerplate.

The table below shows the underlying shape mechanism for reference:

To reduce boilerplate, the pipeline engine recognizes certain node IDs and attribute names as implying a handler type. You do not need to set shape explicitly when using these conventions.

The first three are exact ID matches; the rest are prefix matches (e.g. FanOutSearch, FanInResults, ReviewDraft, CheckQuality). A node with a fan-out attribute also implies shape=component (parallel fan-out), regardless of its ID.

An explicit shape attribute always takes precedence over ID-based inference. If a node has a prompt or agent attribute, it is treated as an LLM task (box), overriding prefix-based ID inference — so ReviewData [prompt="Summarize the reviews"] stays a codergen node, not a human gate. Reserved structural IDs (Start/End/Exit/Fail) are exempt: they always receive their structural shape.

Additionally, a node with an interview attribute (typically set via interview-ref) is inferred as shape=hexagon (a human gate).

Property shortcuts never override an explicitly set shape, label, type, or shell_command. All sugar keys (ask, workflow, shell, branch) are always normalized on the node, even when a higher-precedence shortcut wins.

When a node has no explicit shape, the engine applies the first matching rule:

Example — the combined example from below can be written more concisely:

Here CheckQuality is automatically a conditional node and Review is automatically a human gate — no shape= needed.

When a node references an agent via agent="name", you can override specific agent properties inline using agent.* dotted-key attributes:

This lets you use a shared agent definition while customizing its behavior per-node — for example, running a particular stage with a more capable model or a different provider.

The override precedence order (highest to lowest):

Use the workflow node attribute to run another workflow as a child workflow.

In this example, Implement does not execute a prompt directly. Instead, it resolves and runs the code-implementation workflow and maps the child workflow's result back into the parent pipeline.

Composition is most useful when:

Prefer a normal node with prompt, agent, or shell when the stage is simple and unlikely to be reused.

When a child workflow runs:

So, after a composed node completes, downstream parent nodes can continue using normal variables such as $last_output.

This means child workflows can usually keep using $goal whether they run standalone or as a composed subprocess.

If goal is omitted, the child goal falls back to the composed node's resolved input.

The parent also receives workflow-scoped context updates including:

Workflow composition should remain acyclic. A workflow should not compose itself directly or indirectly through another workflow.

Current validation rejects direct self-reference within the same workflow definition. Avoid indirect composition cycles as well, even if they are not yet detected statically.

Use $-prefixed variables in prompt attributes to inject dynamic values:

$goal is expanded once before the pipeline starts. The other variables are expanded at execution time, so each stage sees the outputs of the stage that ran before it.

Example using runtime variables:

Use $KEY to reference any value stored in the pipeline context. The key can contain letters, digits, underscores, and dots. Missing keys resolve to an empty string.

For example, a short inline reference to a stored context value:

However, for iterative workflows where the interpolated content may be long (full drafts, detailed reviews), prefer using the workflow_get_output and workflow_get_context tools instead — see Workflow context tools below.

Context values can come from several sources:

Instead of escaping long prompts, shell scripts, or human questions inside DOT strings, you can define them in fenced code blocks or code chunks with ids and reference them from node attributes.

Recommended style:

Supported reference attributes:

Example:

References resolve only against code blocks and code chunks in the same WORKFLOW.md. It is an error if a referenced id does not exist, if ids are duplicated, or if a node sets both a literal attribute and its corresponding *_ref attribute.

Edges define transitions between nodes. They can carry labels, conditions, and weights to control routing.

For authored workflows, the recommended style is to keep outgoing edges close to their source node: define the node, then place its outgoing edge or edges immediately after it. A small exception is the initial Start -> … entry edge, which is often kept near the top of the graph.

After a node completes, the engine selects the next edge using this priority order:

You can chain edges as shorthand:

This creates individual edges between each consecutive pair.

Edge conditions use a simple expression language to gate transitions:

Supported syntax:

Available variables:

Keys starting with internal. are reserved and cannot be written by agents.

When an agent node has outgoing edges with labels, the engine automatically provides routing instructions so the agent can make a structured routing decision instead of relying on text output matching.

For sessions with tool support, the agent receives a workflow_set_route tool and calls it with the chosen label. For sessions without tool support, the agent is instructed to end its response with a <preferred-label> XML tag, which the engine parses.

For example, this review node gives the agent two labeled branches:

The agent sees both labels and signals its choice — via a tool call or XML tag — with either Accept or Revise. The engine matches the chosen label against outgoing edge labels (case-insensitive) and follows the corresponding edge.

This is more reliable than prompting the agent to reply with a specific word and matching against context.last_output, because routing is decoupled from the agent's text response. The agent can provide detailed feedback in its text output while separately signaling the routing decision.

Note that edge conditions (Step 1 in the edge selection algorithm) take priority over preferred labels (Step 2).

The simplest pattern: stages execute one after another.

Use conditions on edges to route based on outcomes.

The Check prefix and branch attribute both imply a conditional (diamond) routing point. The engine evaluates edge conditions against the current outcome and context to decide which path to take.

Nodes can retry automatically on failure using max-retries:

max-retries=2 means up to 3 total executions (1 initial + 2 retries).

For more control, use edge-based retry loops that route back to an earlier stage on failure:

Shell nodes run a command and capture its standard output. Use the Shell… or Run… node ID prefix, or the shell property shortcut:

The command's trimmed stdout is stored as shell.output and last_output in the pipeline context.

The store attribute on a shell node writes the command's trimmed stdout into the pipeline context under a named key, in addition to the standard shell.output and last_output keys:

By default, the handler tries to parse the output as JSON. If the output is valid JSON it is stored as a typed value (array, object, number, etc.); otherwise it falls back to storing the raw string. This means a command that emits a JSON array produces a real list in the context, while a command that emits plain text is stored as-is.

The store-as attribute overrides this automatic behavior:

This is primarily useful for producing structured data — like JSON arrays — that downstream nodes can consume as typed values. For example, a shell node can emit a JSON list that a dynamic fan-out node iterates over:

Mark critical stages with goal-gate=true to prevent the pipeline from exiting until they succeed:

If the pipeline reaches the exit node and any goal gate node has not succeeded, the engine looks for a retry-target to jump back to instead of exiting.

Use a Review (or Approve) node ID prefix, or the ask property shortcut, to create a gate that pauses for human input. The choices are derived from the node's outgoing edge labels:

The human is presented with the choices derived from the outgoing edges:

Each outgoing edge from a human gate becomes a selectable option with an accelerator key — a short string the user can type or press to quickly select that option. The engine extracts the key from the edge label using these formats:

The space after the delimiter (], )) is optional — [Y]Yes works the same as [Y] Yes. Brackets support multi-character keys like [OK] Continue or [AB] Option AB. The parenthesis and dash formats are limited to a single character.

Explicit keys are optional. When a label has no recognized prefix, the engine automatically derives the key from the first character of the label (uppercased). For example, these two blocks are functionally equivalent:

When to use explicit keys:

Here is an example with a three-way choice using auto-derived keys:

The engine derives keys S, P, D from the first letter of each label. No brackets are needed because the first letters are already unique.

By default, human nodes derive a multiple-choice question from their outgoing edge labels. You can override this by setting the question-type attribute:

For non-choice types, the node always follows its first outgoing edge — there is no choice-matching step. The node still needs at least one outgoing edge for routing.

The store attribute writes the human's answer into the pipeline context under a named key. Later nodes can reference this value using $KEY in their prompts:

When the human provides an answer, it is stored as a string:

Combining question-type, store, and workflow context tools enables iterative workflows where a human can provide specific feedback that guides subsequent stages.

Here is a complete example of a create–review–revise workflow:

This pipeline:

When a single human pause needs to collect multiple pieces of information — such as a routing decision and detailed feedback — use interview-ref to reference a YAML code block that defines a structured interview.

The YAML block specifies a preamble (optional context shown before the questions) and a questions array. Each question can have a type (defaults to freeform), options (for single-select and multi-select types), a default, and a store key for saving the answer to the pipeline context.

Routing is driven by the first single-select question's answer, matched against outgoing edge labels — the same mechanism as single-question human nodes. When an interview has no single-select question, the node follows its first outgoing edge. An interview node with no outgoing edges succeeds as a terminal node after collecting answers.

Storing answers — each question with a store key writes its answer to the pipeline context. Downstream nodes reference these values using $KEY expansion (e.g., $review.feedback in a prompt). Freeform questions without a store key will trigger a validation warning, since the answer would be collected but never stored.

Conditional questions — use show-if to display a question only when a previous answer matches a condition (e.g., show-if: "decision == Revise"), and finish-if to end the interview early when an answer matches a value (e.g., finish-if: "no" on a yes-no gate question). These can be combined to build branching interviews with early-exit gates.

Use interview-ref when a review step naturally combines routing with structured feedback. Use separate ask / ask-ref nodes when the questions are independent or belong to different pipeline stages.

See Creating Workflows — Multi-question interviews for the full spec format, conditional question examples, and guidance.

Fan out to multiple branches using a FanOut… node ID prefix and collect results with a fan-in node. Branches can be defined statically in the graph (one edge per branch) or dynamically at runtime using the fan-out attribute. You can make the fan-in point explicit using a FanIn… node ID prefix. These prefixes imply shape=component and shape=tripleoctagon respectively, so you don't need to set the shape explicitly:

Branches execute concurrently. The fan-in node waits for all branches to complete before proceeding.

Static fan-out (above) fixes the number of branches at graph-definition time. The fan-out attribute adds dynamic fan-out, where the branch count is determined at runtime from a variable-length list in the pipeline context.

A node with fan-out must have exactly one outgoing edge pointing to the template entry node. The engine spawns one concurrent branch per list item, each executing the same downstream subgraph with per-item context.

The list is typically produced by an upstream shell node with store (see Shell output storage), but any source that writes a JSON array into the context works — for example, an agent node with context-writable=true can call workflow_set_context to store a JSON array (e.g., key items), and the fan-out node references it with fan-out="items".

Attribute forms:

Per-branch context:

Each branch receives the following variables, accessible via $-expansion or workflow context tools:

After all branches complete, results are aggregated into parallel.results (list of per-branch outcomes) and parallel.outputs (list of per-branch outputs). The fan-in successor receives these as context values.

Empty lists: When the resolved list is empty, the handler skips directly to the fan-in successor — no branches are spawned.

Validation rules:

Example — discover repositories with a shell node, then analyze each one in parallel:

This pipeline:

Use this pattern when a single stage in the parent workflow should expand into a reusable internal process:

The Review prefix alone implies a human gate — no shape= needed. The parent graph stays focused on orchestration, while paper-drafting can own the internal research, outlining, drafting, and checking stages.

By default, each agent node in a pipeline starts a fresh conversation — it has no memory of what earlier nodes said. Session persistence lets multiple nodes share a conversation session so that later nodes can recall context from earlier ones, enabling multi-turn interactions across pipeline stages.

This is useful when a pipeline has logically connected steps — for example, an agent that first reads a set of research papers and then synthesizes findings across them. Without session persistence, the synthesis step would not remember what the agent read; with it, the LLM sees the full conversation history and can build on its earlier reasoning.

The simplest way to enable session persistence is the persist attribute, which sets fidelity and thread-id together:

Each node with persist="full" gets fidelity="full" and an auto-generated thread-id of the form persist:{node_id}. Since the thread IDs differ (one per node), these two nodes do not share a session — each starts fresh. To share a session across nodes, use an explicit thread-id (see below) or graph-level defaults.

persist values:

If fidelity is already set explicitly on the node, persist does not override it or generate a thread-id. If thread-id is already set, it is preserved. The persist attribute is always removed after processing — it never appears in the final graph.

For full control, set fidelity and thread-id directly. The key concept: nodes that share the same thread-id with fidelity="full" reuse the same conversation session, so the LLM sees the full message history from all prior nodes on that thread.

In this example:

The fidelity attribute controls how much conversation context is carried over:

Use the default-fidelity and default-thread-id graph attributes to set pipeline-wide defaults. This is the most concise way to make an entire pipeline share a single conversation:

All three nodes inherit fidelity="full" and thread-id="main", sharing a single conversation session throughout the pipeline. The Assess step remembers which studies Search found, and Synthesize remembers both the studies and the quality assessment — so the final review can reference specific papers and their limitations without restating them.

Session persistence is not needed when nodes are independent or when the relevant context is already passed via $-variable expansion or workflow context tools. Use it when the full conversation history matters — not just a single output value.

Centralize agent property overrides with CSS-like rules instead of setting agent.model on every node:

Selectors and specificity:

Explicit agent.* attributes on a node always override values from the overrides rules.

Here is a more complete pipeline combining several patterns:

This pipeline:

Nodes communicate through a shared key-value context. After each node executes, its outcome and any context_updates are merged into the context. Subsequent nodes can reference these values in edge conditions (e.g., context.citations_valid=true), in prompt variables (e.g., $last_stage), or by calling workflow context tools.

Context values come from several sources:

The engine also saves a checkpoint after each node completes. If the pipeline crashes, it can resume from the last checkpoint.

Agent nodes in a pipeline automatically receive workflow context tools that let them query pipeline state on demand via tool calls. This is the recommended way for agents to access prior outputs and stored values in iterative workflows, because the content is fetched in the background rather than being interpolated into the prompt text.

Available tools:

The engine appends usage instructions to each agent's prompt when these tools are available. Agents are told to call workflow_get_output for prior output (e.g., reviewer feedback or a previous draft) and workflow_get_context for stored values (e.g., human.feedback).

Duration attributes like timeout use an integer with a unit suffix:

Subgraphs scope default attributes for a group of nodes:

Nodes inside the subgraph inherit its defaults unless they explicitly override them.