Flow

The flow block defines the execution order of agents in your topology. Arrows (->) connect agents into chains, and edge attributes add conditions, parallelism, and loop bounds.

Basic Syntax

flow {
  researcher -> writer -> reviewer
}

This creates a pipeline: researcher runs first, then writer, then reviewer.

Chaining

Chain multiple agents with arrows. Each arrow means "then run":

flow {
  planner -> researcher -> writer -> editor -> publisher
}

Conditional Edges

Add a when condition in brackets to make an edge conditional:

flow {
  researcher -> writer -> reviewer
  reviewer -> writer  [when reviewer.verdict == "revise"]
}

The second edge only fires when the reviewer's verdict output equals "revise". If the condition is not met, the flow ends.

Fan-Out (Parallel Execution)

Use a list to send work to multiple agents in parallel:

flow {
  planner -> [frontend-dev, backend-dev, qa-engineer]
  [frontend-dev, backend-dev, qa-engineer] -> integrator
}

All three agents run simultaneously. The integrator waits for all of them to finish.

Bounded Loops

Add max N to prevent infinite loops:

flow {
  writer -> reviewer
  reviewer -> writer  [when reviewer.verdict == "revise", max 3]
}

The reviewer can send work back to the writer at most 3 times. After that, the flow continues forward regardless.

Edge Attributes

Edge attributes appear in brackets after the target agent. When multiple attributes are used, they follow a fixed order:

Combined example:

flow {
  reviewer -> writer  [when reviewer.verdict == "revise", max 2, per phase]
}

Unconditional Edges

Edges without brackets always fire:

flow {
  a -> b
  b -> c
}

This is equivalent to a -> b -> c.

Full Example

topology code-review : [pipeline, fan-out] {
  agent planner    { model: sonnet  tools: [Read, Grep] }
  agent analyzer   { model: sonnet  tools: [Read, Grep] }
  agent security   { model: opus    tools: [Read, Grep] }
  agent writer     { model: sonnet  tools: [Read, Write] }
  agent reviewer   { model: opus    tools: [Read] }

  flow {
    planner -> [analyzer, security]
    [analyzer, security] -> writer -> reviewer
    reviewer -> writer  [when reviewer.verdict == "revise", max 2]
  }
}

Tips

• Every agent referenced in flow must be declared as an agent block in the same topology.
• Fan-out requires the topology to declare the fan-out pattern.
• Bounded loops prevent runaway costs. Always set max on conditional back-edges.
• The per attribute is useful when your topology has multiple phases and you want loop counters to reset per phase.