New to Agent Flows? Read Agent Flows for the canvas basics (creating, publishing, enabling a flow as a chat sub-agent). For end-to-end example flows you can copy, see the Agent Flows Cookbook. This page is the reference for the individual nodes those recipes use.
How data flows between nodes
Two different things connect your nodes, and it helps to keep them separate in your head:- Edges = order. An edge (the line you draw from one node to the next) decides when a node runs.
start → A → B → endmeans run A, then B. Reading another node’s value counts toward that order too (see the note below), but the edge is what you should rely on. - Bindings = data. A binding decides what value feeds a node’s input port. You bind an input to one of these sources:
A node with two incoming edges waits for both before it runs. That’s how you fan two parallel branches back into one node (e.g. a Knowledge Graph branch and a Web research branch both feeding one
LLM generate). You only need the explicit Join node when you fanned out with Map.Reading another node’s output counts as a dependency too — whether you bound it ($.nodes.<id>.outputs.<port>) or spliced it into a prompt ({{ nodes.<id>.outputs.<port> }}) — which pushes the reading step later in the run. Treat that as a safety net, not a guarantee: when the reader and the node it reads are both waiting on other branches, they can still end up running together, and the reader gets nothing. Draw the edge as well — it’s the only reliable way to express the order, and the canvas won’t flag the missing one for you when you validate or publish.If a step fails, the steps that read its output don’t run on empty input — the run stops with an error naming the source that failed, instead of carrying on and producing a hollow answer that still reports success.Control nodes
The plumbing: where a flow starts and ends, and how it branches, repeats, and fans out. Control nodes don’t call a model — they’re fast and deterministic.
Condition (
control.condition) — set Value path to the value you’re testing (e.g. $.nodes.kg.outputs.row_count), an Operator (eq, ne, gt, gte, lt, lte, in, not_in, contains, truthy, falsy), and a Comparison value when the operator needs one. The edges leaving a Condition decide which branch runs on true vs false.
Map (control.map) — set Body node to the node that runs once per item, and Join node to the control.join that collects the results. Inside the body, read the current item with $.nodes.<map_id>.outputs.item (and .index). The list you bind to items is fanned out in parallel.
Loop (control.loop) — set Max iterations (1–1000). Every cycle must pass through the Loop node; once the count hits the max, exhausted flips to true so you can route out of the loop.
Start, End, Merge, and Join have no settings to fill in — they just need to be wired. End is where the flow’s answer comes from, so always bind its
result to whatever produced the final value.Data nodes
These work with your content: query the knowledge graph, read the conversation a run came from, index uploaded files, and render documents.
Knowledge Graph Query (
knowledge_graph) — the workhorse for answering from your own data. Key settings:
- Output mode —
datareturns rows only;reportadditionally synthesizes a cited narrative on thetextoutput (withevidence). Pickreportwhen you want a written answer, not just a table. - Query — the question. Leave it templated or bind the
queryinput to Chat message so the user’s question drives it. - On clarify — what to do when the question is too vague to scope:
fail(stop),interrupt(pause for a human), orskip(continue with empty rows). - Fail on empty, Include graph context, Custom instructions, and report-tuning options (Output instructions, preview/token caps) are available for finer control.
kg.data) — the same scope-and-query as Knowledge Graph Query, minus the report writer. Set the Query and optional Custom instructions, and choose an On clarify policy (fail / interrupt / skip) exactly as above; Fail on empty, Include graph context, and Document search K (how many parallel document searches run during scope — default 3, 0 to disable) tune the retrieval. It exposes the scope and retrieval outputs directly — resolved_entities, intent, validated_cypher, graph_context, scope_recommendation, clarification_question, plus rows/row_count/retrieval_quality — with the same automatic CSV export on rows_file for large results. Reach for it when a downstream node consumes the graph data itself. When you also want a written narrative, you have two routes: keep the data step and wire a Knowledge Graph Display node after it (below), or collapse both into a single Knowledge Graph Query in report mode.
Knowledge Graph Display (kg.display) — the report half of the pair. Wire kg.data → kg.display and it runs the deep agent’s report writer over the rows kg.data already retrieved — no second query — to synthesize a main-agent-quality, cited narrative on text (with an evidence index). The canvas auto-wires the ports it reads from kg.data (rows, resolved_entities, intent, validated_cypher, graph_context, scope_recommendation, clarification_question); rows is the only required input. Configure the Query it answers (falls back to the upstream intent when left blank), optional Output instructions (formatting and guidance for the report writer — the report-only Display node has no scope phase, so it takes no separate custom instructions), the report’s row budget and token budget (report_data_preview_limit, default 300; report_max_data_tokens, default 50,000), and an optional model override for the writer. To surface the answer, finish the pattern start → kg.data → kg.display → end and bind end.result ← kg.display.text — the evidence index rides along with the text, so the grounded [evidence:…] citations render as clickable source chips in the run output panel (document chips link out to the source; graph-entity chips show the entity by name).
Time limits. The knowledge-graph nodes are capped on wall-clock time, and a node that runs past its cap fails with a timeout instead of returning partial results: Knowledge Graph Query and Knowledge Graph data get 600s, Knowledge Graph Display 300s. The cap applies to every run of the flow, including versions published before it existed. You can’t see or change these from the Inspect panel — its Budget editor only appears on the agent nodes — but you can raise one through Edit as JSON by setting
budget.max_wall_seconds on the node.data.index_files) — bind message file ids to an uploaded file slot ($.files.<slot>). It indexes the files and also emits short text previews on documents that downstream LLM nodes (like llm.extract) can read directly.
Read conversation (data.channel_history) — nothing to bind: it reads the chat the run was launched from. Set Messages to read (how many of the most recent messages to take — default 20, up to 200; they come back oldest-first), Whose messages to include (all, user for only what the person typed, or assistant for only the agent’s replies), a Per-message character cap (default 40,000; 0 disables truncation), and Fail when the conversation is empty (on by default — leave it on when a downstream node depends on the transcript, since an empty transcript renders as an empty prompt and yields a hollow document that still reports success). transcript is the plain-text User: … / Assistant: … version to feed an LLM node; messages is the same turns structured as {message_id, role, text, truncated, created}, with message_count alongside.
Read conversation only works on a run launched from a chat. A run started from the canvas Run tab (or the REST API) has no conversation to read, so the node fails with a “requires a channel-scoped run” error. It also only ever reads a conversation the person who started the run can open — one they own, or one shared with them directly or through a folder. Anything else fails with an authorization error rather than being read — distinct from the empty-conversation failure above, so you can tell the two apart in the run’s step log.
data.generate_docx) — bind sections (a list of structured {heading, content} objects) for a multi-section document, or bind text for a single-section body (e.g. a Knowledge Graph report). Set the Document title, optionally Include table of contents, and choose a Theme from the eight built-in ones. To brand the output, pick a Document Template by name (one of your registered Document Templates); the document then inherits that template’s styles, headers/footers, and logo.
Generate PPTX (data.generate_pptx) — the slide equivalent of Generate DOCX: bind sections (one slide each) or text, set the Title, and optionally pick a PPTX template by name for branded slide masters. (A Theme is accepted for parity with DOCX but does not currently affect slide styling — use a template to brand slides.)
Read Excel template (data.inspect_xlsx) and Fill Excel template (data.generate_xlsx) — a pair for filling a spreadsheet you already have. Unlike the Generate nodes, which build a document from scratch, these edit an existing workbook in place: only the cells you fill change, and the file keeps its images, styles, conditional formatting and formulas.
Point both at the same Template name (an Excel Document Template) and, optionally, list the Sheets to limit them to.
Read Excel template produces a plain-English description of the form on text — the labels it prints, the columns of its line-item table, and, for any column the workbook looks up (a commodity code, say), the exact set of values that will resolve. Bind that to an LLM node’s context and the model drafts using the form’s own wording instead of guessing.
Fill Excel template takes that draft back:
- fields — single-value fields, as
{label, value}entries or a{label: value}object. Matched against the labels the form prints, soE-Mail Addressandemail addressboth land. - blocks — multi-line boxes, as
{label, lines}. For a caption printed inside its own box (aTO:address block), the lines go in the rows beneath it and the caption is left alone. - rows — line items, each keyed by the table’s own column headers.
- cells — exact overrides as
{sheet: {A1: value}}, when you already know where a value goes.
Both blocks stop the run rather than hand back a workbook that only looks filled. Fail if nothing was filled is checked per region — filling the header is not evidence the line items filled — and a value outside the workbook’s allowed set is an error, not a silent skip, because a blank there leaves every computed column empty.
data.generate_file) — a single node with a format chooser: Word (.docx), PowerPoint (.pptx), PDF, or HTML. It reuses the same generators as the dedicated DOCX/PPTX nodes. The Document Template selector appears only for the docx and pptx formats. For pdf/html, bind content to the format-native source (LaTeX for PDF, HTML for HTML); for docx/pptx, bind sections (or text) as you would for the dedicated nodes.
Markdown that shows up in generated content —
#/##/### headings, **bold**/*italic*, -/1. lists, and pipe tables (| Col | Col | with a |---|---| separator row) — is rendered as real Word/PPTX styling rather than left as literal markers in the document. A pipe table becomes a proper Word table with a header row and borders; in PPTX, where slides have no table layout, each row is rendered as a line.The hidden phases of Knowledge Graph Query —
kg.scope, kg.retrieve, kg.report — are covered under Advanced / hidden nodes below. You don’t need them for normal flows.LLM nodes
Single-call language-model steps. Each makes one model call from a prompt (plus optionalcontext input) — predictable cost, no looping. All three accept {{ params.* }}, {{ inputs.* }}, and {{ nodes.<id>.outputs.* }} templates in their prompts.
LLM generate (
llm.generate) — set the Prompt (required) and optionally a System prompt. Bind context to whatever you want appended to the prompt (e.g. a Knowledge Graph report). Output lands on text.
LLM extract (llm.extract) — set the Prompt plus an Output schema: a map of {name: {type, description, required}} where type is string | number | integer | boolean | array | object. The model is forced to return exactly that shape on the data output. Example schema:
llm.classify) — set the Prompt and a list of Categories (at least two, unique). The output category is guaranteed to be one of your labels, with a one-line reasoning. Wire category into a Condition to route.
All three take an optional Model (defaults to the global reasoning model), an Output format hint, and Include graph schema (adds a compact knowledge-graph schema to the prompt when the step reasons over graph data).
Agent nodes
These run a bounded, model-driven loop — the model decides its own steps using tools until it finishes or hits its budget. Because they loop, every agent node has a budget (max model calls, tool calls, tokens, wall-seconds) so it can never run unchecked. Unset budget fields fall back to sensible defaults.
Knowledge research agent (
agent.deep_research) — set the Research goal (templatable; use {{ params.message }} to use the chat message). By default it uses the proven internal-knowledge tool set (knowledge graph + Cypher); you can override Tool groups or add one MCP server. Report format structured returns a typed {title, summary, sections} report. Defaults: 40 model calls / 80 tool calls / 1800s.
Web research agent (agent.web_research) — set the Research goal. It runs live web searches via Tavily and grounds every claim in cited URLs. Leave Tavily API key blank to use the org-level TAVILY_API_KEY configuration setting (recommended). Defaults are lighter than internal research: 30 model calls / 60 tool calls / 900s.
Orchestrator agent (agent.orchestrator) — set the Goal and Allowed nodes (the registry node types it may call as tools, e.g. knowledge_graph, agent.web_research, data.generate_docx). At runtime it plans with a todo list and chooses which nodes to call. Outputs include the final text, the plan it followed, and evidence (citations from report-mode node tools). Optional Require plan approval pauses for a human to approve the plan first. Defaults: 20 model calls / 30 tool calls / 900s.
MCP action (mcp.action) — set the MCP server and a Task instruction. Choose Auth source (user = the run-user’s connection, org = organization integration, auto = user first then org), optionally whitelist tools, and set Allow writes if the task should mutate external systems. Write-capable tools are flagged in the tool list; when Allow writes is off, the builder warns which selected write tools would be dropped at run time — they are stripped so a read-only step can never mutate anything, and the run is reported as a failure rather than a false success if the task then can’t complete. On error controls failure handling: fail (halt), error_port (emit the error envelope for conditional routing on status), or continue. Defaults: 10 model calls / 15 tool calls / 300s.
Human nodes
Human review (
human.review) — bind payload to the data you want the reviewer to see (e.g. a draft). When the run reaches this node it pauses and surfaces the item wherever the run is being watched: for a sub-agent run that means the flow-run panel in the conversation itself (the reviewer never has to leave chat), and for every run it is also listed in the Agent Inbox for staff. On approval the flow resumes; on rejection you can route back to a revise step. Set a Review title and Reviewer message for context, and choose the Review layout (inline_summary or artifact_download).
Reviewer note. On the review card — whether it appears in the canvas Run panel, the in-chat flow-run panel, or the Agent Inbox (it’s one shared card) — the reviewer can add a note. The note is optional when approving and required when rejecting, so a rejection always comes back with a reason.
Outputs. Alongside the existing approved (boolean) and response (object), the node exposes two first-class ports for the reviewer’s decision:
Downstream nodes consume the note by binding
{{ nodes.<review_id>.outputs.comment }} into a prompt — e.g. a revise / LLM step that applies the feedback — and can route on {{ nodes.<review_id>.outputs.decision }} (or the existing approved). This feeds the reviewer’s feedback straight into the revise loop or the next LLM node.
Human review requires a checkpointed run (the engine has to be able to pause and resume) — this is the default when a flow is published and run.
Choosing the right node
A few decisions come up again and again. Here’s how to pick.Which LLM node — classify, extract, or generate?
Rule of thumb: classify when you’ll branch on the result, extract when a downstream node (Map, Generate DOCX, a table) needs typed values, and generate for anything that should read as prose.
Map (parallel) vs Loop (sequential)
- Map runs the same step over many items at the same time — fast, and each branch is independent (e.g. author every section of a document in parallel). Always pair it with Join to collect the results.
- Loop repeats a step one pass at a time, up to a max count, where each pass can depend on the last (e.g. revise-until-approved, or a fixed number of retries).
Condition + Merge (branch, then rejoin)
Use them as a pair: a Condition evaluates a value and routes the run down one of several branches; each branch does its own work; a Merge converges them back to a single path (it forwards the one branch that actually ran). Bind one input on the Merge per upstream branch. A common shape: classify → Condition → (branch A | branch B) → Merge → end.Knowledge Graph Query vs Knowledge research vs Web research vs Orchestrator
All four can “answer a question,” but they trade off determinism, depth, and source:
Rule of thumb: deterministic single question → Knowledge Graph Query; deep internal investigation → Knowledge research agent; external/current → Web research agent; unpredictable, multi-tool → Orchestrator agent. For a fixed “graph and web” answer that always runs both, prefer two parallel nodes feeding one
LLM generate (deterministic, predictable cost) over an Orchestrator — see Cookbook Recipe 3.
Advanced / hidden nodes
kg.scope, kg.retrieve, and kg.report are the internal phases of Knowledge Graph Query, split into separate nodes. They’re hidden from the palette — new flows can’t add them — because the single Knowledge Graph Query node does all three phases for you. They remain registered and runnable only so older published flows that referenced them keep working. You won’t need them: use Knowledge Graph Query instead.
Where to next
- Agent Flows Cookbook — validated, end-to-end example flows (and the patterns behind them) built from these nodes.
- Agent Flows — the canvas basics: creating, validating, publishing, and enabling a flow as a chat sub-agent.