Agentflow (v12.0.0+)

An agentflow diagram describes an agentic workflow: the agents that do the work, the flows they run, the tasks and tools inside those flows, and how control and data move between them.

Warning Agentflow is in beta. The diagram type is selected with the agentflow-beta keyword, and the syntax may still change in a backwards-incompatible way before it is declared stable.

Introduction

A flowchart tells you what happens next. An agentflow tells you who is doing it, with which tool, and what contract holds at each step. It keeps the familiar flowchart feel — nodes, arrows, containers — but adds a small vocabulary aimed at describing systems built out of language-model agents:

• Containers (flow … end) group work and nest to any depth.
• Shapes carry meaning: a task is not a tool is not a decision.
• Edges carry meaning: sequence, reference, and failure are three different arrows.
• Metadata (@{ … }) attaches the non-visual detail — the model, the instruction, the parameter and return types, the connector a tool is bound to.

Basic example

Code:

Ctrl + Enter|

Default theme, look and layout (v12.0.0+)

Agentflow diagrams use the redux-color theme and the neo look by default, and are laid out by ELK rather than Dagre. Not every diagram type does — see Per-diagram defaults for the list and for the order in which Mermaid decides.

The same diagram, drawn both ways:

With the defaults

Code:

Ctrl + Enter|

The previous appearance

Both are only defaults, so anything you set yourself wins. Naming the previous theme and look in a diagram's front matter draws it the way Mermaid did before:

Code:

Ctrl + Enter|

Passing the same three keys to mermaid.initialize() does it for every diagram on the page, and scoping the theme and look to one diagram type — mermaid.initialize({ layout: 'dagre', agentflow: { theme: 'default', look: 'classic' } }) — does it for that type alone. layout is a top-level option, so it applies to every diagram.

Declaring a diagram

Every diagram starts with the agentflow-beta keyword, optionally followed by a direction — TB, TD, BT, LR, or RL.

agentflow-beta LR

Nodes and shapes

Nodes are declared exactly as in a flowchart: an id, optionally followed by a label in brackets.

research["Research the topic"]

The shape is chosen with the shape key in an @{ … } block. Agentflow provides domain-facing aliases on top of the standard Mermaid shape names:

Alias	Meaning	Underlying shape
task	A unit of work an agent performs	roundedRect
tool	A callable capability — a function, an API, a subroutine	subroutine
input	Data entering the workflow	lean-right
decision	A branch point	diamond
refdoc	Reference material an agent consults	lin-doc
action	A side-effecting step — sending, writing, publishing	hexagon

Any canonical Mermaid shape name also works, so the aliases are a convenience rather than a restriction.

Code:

Ctrl + Enter|

Edges

Agentflow uses three edge operators, each with a distinct meaning:

Operator	Semantic	Reads as
-->	sequence	Control or data flows from source to target
-.-	reference	The source consults the target; no control passes
--x	failure	The failure path out of the source

Labels are written in the middle of the arrow, as in a flowchart:

Code:

Ctrl + Enter|

Chained edges work too: a --> b --> c.

Containers

A flow … end block groups nodes into a container. Containers nest, and a node referenced inside a container belongs to it.

Code:

Ctrl + Enter|

The global block

Sometimes a node is shared by several flows and should not be pulled into whichever one happens to mention it first. Declare it inside a global … end block and it stays at the top level no matter where it is referenced:

Code:

Ctrl + Enter|

global takes no id, label, or metadata, renders nothing itself, and may appear anywhere in the diagram — including nested inside a flow, as an escape hatch.

Collapsing a container

@{ view: collapsed } folds a container down to a single summary node while keeping its edges. Edges that crossed the boundary terminate at the collapsed node instead of disappearing.

Code:

Ctrl + Enter|

Metadata

Any node, edge, or container can carry an @{ … } block. The contents are YAML, so both the single-line form and a multi-line block work:

researcher@{ model: "claude-sonnet-4-20250514", instruction: "Research and cite sources." }

fetch@{
  shape: tool
  params: "city :: String"
  returns: "Report"
  retry: 2
}

Mermaid itself acts on a small, fixed set of keys:

Key	Applies to	Effect
shape	nodes	Selects the node shape (see the table above)
label, labelType	nodes	Overrides the node's label and how it is parsed
view	containers	collapsed folds the container down to a summary node
algorithm	containers	Per-container ELK algorithm
curve, animate, animation	edges	Edge interpolation and animation

Everything else is carried through untouched and surfaced to consumers, so the vocabulary below is a convention rather than a closed list — an unknown key is preserved, never rejected.

The one exception is prototype-shaped keys: __proto__, constructor, and prototype are stripped from parsed metadata, at every level of nesting. They are dropped rather than carried so that a consumer merging node.metadata into its own object cannot be made to pollute a prototype.

Key	Applies to	Purpose
description	anything	Free-text description
instruction	agents, flows	The system prompt or standing instruction
model	agents, flows	The model the agent runs on
params	tools, containers	Input contract, e.g. "city :: String"
returns	tools, containers	Output contract
value	input nodes	A concrete value
example	input nodes	An example value
connectorRef	tools, actions	The connector capability this node is bound to

Connectors

A connector describes an external system a tool talks to. Declare it with the connector keyword and configure it with metadata; tools then point at one of its capabilities with connectorRef.

Code:

Ctrl + Enter|

A connectorRef value may be a bare node id, a dotted connector.capability form, or a URL. The dotted and URL forms are treated as opaque.

A worked example

Code:

Ctrl + Enter|

Configuration

Agentflow has its own config namespace, so it can be tuned without moving flowcharts on the same page.

Option	Description	Default
titleTopMargin	Margin above the diagram title	25
diagramPadding	Padding around the diagram as a whole, in pixels	8
nodeSpacing	Spacing between nodes on the same level	50
rankSpacing	Spacing between nodes on different levels	50
useMaxWidth	Scale the diagram to the available width	true

Code:

Ctrl + Enter|

Theme variables

Containers are themed with flowContainerStroke, defined by every theme mermaid registers; it falls back to secondaryBorderColor when unset. Everything else on an agentflow diagram uses the standard node, edge, and cluster theme variables.

Layout

Agentflow renders through the unified renderer, so it works with any registered layout engine. ELK is the default, and an individual container can also select its own ELK algorithm:

Code:

Ctrl + Enter|

For tool builders

Two accessors on the diagram DB are meant for programs rather than people:

• getSemanticModel() returns the diagram with presentation-only controls (view, class, style, icon, img, w, h) stripped, so downstream consumers get a stable semantic view that does not shift when someone restyles the diagram.
• getDiagnostics() returns structured warnings — unresolved references, misapplied metadata keys, containment violations, unsatisfied capability requirements — each with a source position. Diagnostics are warnings; they never block a render.