Agent Flows

Overview

Agent Flows let you compose typed nodes into a flow on a visual canvas. When you publish a flow, Experio compiles it to a LangGraph graph and runs it — orchestrating LLM calls, knowledge graph queries, MCP tools, document generation, and human approvals as a single pipeline. A flow can run on its own from the canvas, or be enabled as a sub-agent that the chat agent launches on a user’s behalf. Navigate to Admin > AI & Agents > Agent Flows.

Agent Flows are distinct from Flows, which orchestrate data-processing jobs (reader, ingestion, enrichment). Agent Flows orchestrate AI agent behavior and compile to LangGraph.

The Admin Copilot is available on both the flows list and the editor — it can explain a flow, validate it, diagnose a failed run, and build or edit a definition from plain text. It only ever proposes; you apply, save and publish.

The Flows List

The Agent Flows page lists every flow with its name, description, tags, and latest published version. A Sub-agent badge column shows whether a flow is exposed to the chat agent, and a filter above the list switches between All flows and Sub-agent enabled. From here you can:

Create a new empty flow (give it a name — the system handles the internal id)
Open a flow to edit it on the canvas
Duplicate a template into a new draft (see Templates)
Delete a flow

Building a Flow

Opening a flow shows the canvas editor. You build a flow by dragging nodes from the palette onto the canvas. Nodes are compact cards — they don’t show input/output ports on the canvas. To connect two nodes, drag from one node onto another; the canvas auto-wires their compatible ports. Edges float between nodes and re-route automatically as you move nodes around. The flow name is editable inline at the top of the editor. A collapsible right-hand pane holds the support panels; it re-opens automatically when you click a node:

Inspect — configure the selected node (its config fields, input bindings, and budget), or the selected edge’s routing. Each node also takes an optional Display name — the human-readable step name end users see in the chat progress view while the flow runs (it falls back to the node’s label or id)
Run — start and watch a run (see Running a Flow)
Versions — review prior published versions and control which one is Live (see Publishing and Versioning)

Config fields

The Inspect panel renders each node’s config from its schema:

Fields that hold prose — Query, Custom instructions, Prompt, System prompt, Output instructions and the like — render as multi-line text areas you can scroll and resize, rather than a single-line box you have to scrub through. Short identifiers (titles, artifact keys, numeric limits) stay single-line.
Fields that point at another record render as a picker rather than asking you to paste an identifier:
- Model (model_id, fallback_model_id, report_model_id) — the configured chat models, with Default model first. See Model Configurations.
- Assistant — whose per-assistant model configuration the node borrows. Leave it on Default models to use the global ones.
- MCP server — the server whose tools the step may call. See MCP Servers.
- Document template — the branding template a generated file is rendered into. See Document Templates.
Fields with a fixed set of values — the document Theme, output modes, error policies — render as dropdowns.
Fields that hold a list — Tool groups, Allowed blocks, an MCP Tool whitelist — render as checklists of the real choices. Leaving one empty is meaningful and the panel says what it means (for a tool whitelist, “all discovered tools”).
A nested configuration (such as the optional MCP enrichment on the research agent) renders as its own small group of controls, including the pickers above.

The pickers read admin lists. An author without permission to read one still sees that field as a plain text box and can edit the value by hand — the rest of the form is unaffected. If a flow holds a value that is no longer in the list, the field flags it rather than quietly showing “none”.

Bindings

Each node has typed input and output ports under the hood. Connecting two nodes auto-wires their compatible ports; to send one specific value, drag from a node’s output port to a target input in the Inspect panel. A binding path looks like $.nodes.<node_id>.outputs.<port>, and inputs can also bind to run parameters ($.params.*), the chat message ($.params.message), and uploaded files ($.files.*). Bindings are validated when you save — type mismatches and missing required inputs are surfaced inline on the canvas. Edges order execution; bindings move the data. Reads count too: reading another node’s output — through a binding, or through a {{ nodes.<node_id>.outputs.<port> }} template in one of the node’s config fields — counts as a dependency, not just the edges you drew. That is a safety net against a node running before the value it reads exists, not a guarantee of order. A node reading its own previous output (a loop body) is not treated as waiting on itself. If a node it reads from fails, the reading node fails too rather than running on an empty input — the branch stops there instead of producing a document out of nothing. An input that carries a default is the exception: it falls back to that default and the reading node still runs — but only because it reads the failed step, not because it follows it. A step you drew an edge from is on the failed branch, and that branch stops at the failure whatever its inputs default to. Drawing the edge is what actually orders the two steps. Validation does check for a node reading the output of a node that isn’t upstream of it, and reports it as a warning: run Validate — or apply an edited definition from Edit as JSON — and every such finding is listed in an amber strip above the canvas, naming the node to fix. Warnings never block publishing, by design, and there is no per-node marker on the canvas or in the Inspect panel, so that strip is the only place you can read the detail. Publish without validating first and nothing surfaces at publish time — the publish dialog lists blocking errors only; the new version’s entry in the Versions tab carries a warning count instead, as a prompt to go back and run Validate.

Declaring run parameters

A flow can carry an optional top-level params declaration — a list of {name, description} entries naming the run parameters ($.params.<name>) it expects a launch to supply, beyond the implicit chat message. It’s descriptive rather than enforced at run time (an undeclared param a definition reads still resolves to an empty string, with no error), but it documents what a run needs, and it’s what the hollow-pattern lints check a proposal against. Edit it from Edit as JSON, alongside the flow’s nodes and edges.

Edit as JSON

The canvas toolbar includes an Edit as JSON action. It opens the flow’s full definition as JSON, where you can export it (copy or download) or paste an edited definition back. Applying a pasted definition runs the same server-side validation as the Validate button — unparseable or structurally-invalid JSON (missing nodes/edges arrays) is rejected before it touches the canvas.

Hollow-pattern checks

Structural validation confirms a definition compiles; it doesn’t confirm the flow produces anything. A handful of shapes compile cleanly, run without error, and still deliver nothing — an unrouted loop that silently ends the run when it exhausts its budget, an exit with no result requirement that’s reachable without ever running its producer, an extraction schema too loose for the model to fill in correctly. Save-time validation now also runs a fixed set of hollow-pattern lints for exactly these shapes:

Lint	Catches
L1 — `loop_exhausted_unrouted`	A `control.loop` with no out-edge that fires on `exhausted: true` (or one that spells the predicate as the string `"true"`, which never matches).
L2 — `hollow_exit`	A `control.end` without `require_result` that’s reachable by a path that never runs the node it binds its result from.
L3 — `extract_array_untyped`	An `llm.extract` output schema with an `array` field that has no typed `items`.
L4 — `orchestrator_allowed_type_unregistered`	An `agent.orchestrator`’s `allowed_node_types` naming an unknown, hidden, test-only, or self-referential type.
L5 — `hidden_or_test_node_type`	Any node using a hidden (deprecated) or test-only node type.
L6 — `mcp_on_research_node`	An MCP server attached to a research agent’s `config.mcp` instead of an `mcp.action` node, bypassing the write-consent check.
L7 — `kg_skip_unread_or_load_bearing`	A knowledge-graph node set to `on_clarify: skip` whose clarification question is never read, or whose (empty) output feeds a review or document node.
L8 — `undeclared_param`	A `{{ params.X }}` / `$.params.X` reference with no matching entry in the top-level `params` block.
L9 — `binding_type_mismatch`	An input binding whose two ends disagree in shape — a list-typed input such as `control.map.items` bound from a string port (`llm.generate.outputs.text` is always text, whatever the prompt asks for), or a string input bound from a list or object. Bind a list-typed port instead: an `llm.extract` array field or a join’s results. A path that digs into a string, number or boolean (`…outputs.text.<field>`, or a review’s `outputs.content.<field>` when the review shows a generate’s text) is the same row whatever the reader’s port: a segment digs into an object or a list, never into a scalar, so the value is `None` on every run.
L10 — `unused_llm_output`	An `llm.generate` / `llm.extract` / `llm.classify` step whose output nothing reads — no input binding, no template, no edge predicate, and no map join collecting it. An edge alone carries no data, so the step still runs on every run (one model call) and delivers nothing; this is the shape a fix leaves behind when it adds a replacement step and keeps the old one wired. Remove the step with its edges, or bind its output.
L11 — `generate_asked_for_json`	An `llm.generate` whose prompt asks for structured output (JSON, an array, a list, a schema) followed by an `llm.extract` that parses its text — two model calls doing one call’s job. Replace the generate with one `llm.extract` whose `output_schema` declares the fields (typed arrays), bind the consumers to `outputs.data.<field>` and remove the generate with its edges; never add a parsing step after it.
L12 — `review_edits_bypassed`	A step that runs after a `human.review` and reads the review’s payload source (`$.nodes.<source>.outputs.<port>…`) — directly, or through a step that derived something from the source (an `llm.extract` parsing the same text, a classifier, a summary) — without the reviewer’s edits: the reviewer edits and approves, and the edit never reaches that step. Judged step by step (one step on `outputs.content` does not excuse another). Bind the step to `outputs.content` (with the same trailing field, `outputs.content.<field>`), a converter’s input to `outputs.content` so it converts the reviewed version, and when the review shows only one field of what the readers dig into, bind its `payload` to the whole object so the reviewer sees what the readers use. A step that derived something before the review (a classifier’s category, a summary’s text — whatever its shape) was computed on the unreviewed text: run it after the review, reading `outputs.content`, on the approved path in front of its readers; when it produced the object the readers dig into (a typed extract of the text), the review’s `payload` can move onto that object instead and the readers onto `outputs.content.<field>`. A step that runs before the review on a revise loop is not a bypass, nor is one that reads `outputs.content` alongside the source (a diff), nor the retry step of a revise loop that reads `outputs.comment` (the source re-runs behind it) — but a step past the review that reads the comment alone beside the source has the note and not the edits, and is one.
L13 — `loop_reentry_ignores_review`	A review loop (a `human.review` that rejects into a `control.loop`, the loop re-entering its body on `exhausted == false` — or on an unconditional edge beside its `exhausted == true` exit, which the router takes the same way) whose body — the steps on the way from the re-entry back to the review — reads neither the review’s `comment` nor its `content`: the second pass runs the identical prompt and the reviewer’s feedback goes nowhere. Put `{{ nodes.<review>.outputs.content }}` (the version as the reviewer left it) and `{{ nodes.<review>.outputs.comment }}` into the re-entered step’s prompt, or bind them; both are empty on the first pass, when the run’s diagnostics show two “resolved to nothing” binding warnings for them — expected.
L14 — `dead_conditional_branch`	Two conditional edges from one node with the same `when` (or a later one whose `when` only adds conditions to an earlier one’s, or a plain second copy of the same edge). The router takes the first match and routes to ONE target, so the second edge can never fire — a whole branch silently never runs. To fan out on a condition, route it once into a `control.condition` anchor and fan out from the anchor with unconditional edges; remove a duplicate edge. Edges out of a `control.map` take no part (its declared edges are replaced by the fan-out router).
L15 — `review_content_unread`	A `human.review` with a bound `payload` whose `outputs.content` no step reads on the approved path — the reviewer’s edits go nowhere. A read by the payload’s own source, or by a step on the loop’s way back to the review, is the next pass, not delivery. A review used as a `control.map` body counts as read when some step reads the map’s join (the join collects the content; a join nobody reads delivers nothing), and so does one whose content an edge predicate tests. Bind the step that uses the reviewed data to `outputs.content`; a review the flow uses for its verdict and note alone says so with Approval only (`config.approval_only`) on the review — the one exemption, and of this check alone: a step past the review that reads the payload’s source directly is still L12.
L16 — `unread_extract_field`	An `llm.extract` with two or more `output_schema` fields, one of whose list or object fields nothing reads — not directly (`outputs.data.<field>`), not through a review whose payload shows the whole object (`<review>.outputs.content.<field>`), and not as part of the whole object reaching a reader that takes it whole (a review’s `payload`, a document node’s object port, an exit, a template — and a spreadsheet’s `rows` or `fields`, which read a `{sheet: [rows]}` map by design). The field is asked for, produced and paid for on every run, for nobody — and a reader that wanted it is usually on a sibling field instead: the demo card that showed the reviewer one list and bound both maps to the review’s bare `content` ran the web research over the KG questions. Behind a whole-object read the same collapse is judged on the readers: two list-typed inputs digging the SAME field (both maps on `content.kg_questions` behind a payload on the whole object) while a sibling list is read by nothing is a row on the second reader, at its binding. A scalar field (a string, number or boolean — a one-sentence `reasoning` the run panel shows) is not judged: it is the person’s to read there. A list-typed input fed the whole object is L9’s row, not a read (each map must dig its own field: `content.<field>`); an extract nothing reads at all is L10’s. Bind the step that needs the field, or drop it.
L17 — `predicate_reads_unrun_node`	An edge gated on a node that does not run before the edge’s source on the first pass — `suggest → review when loop.exhausted == false` with no `loop → suggest` re-entry. On that pass `exhausted` is empty, the condition never matches, the edge never fires, and the review never runs. Gate the edge on a node that is already upstream of `<from>`, or put `exhausted == false` on the loop’s own edge (`loop → producer`). A cycle through a `control.loop` counts as upstream only for edges OUT of the loop; an edge that is the loop’s own re-entry is silent.

Each lint’s severity depends on who’s authoring: for a person on the canvas, every lint but L8 is a warning (nothing here blocks publishing, and every already-published flow keeps working) — L8 is off, since no published flow predates the params block. For a proposal from the Admin Copilot, every lint is an error: an agent can’t come back and open the hollow document afterwards, so the shape is refused before the proposal ever reaches your card. You can run these checks without saving, from three places: the canvas Validate button, POST /api/agent-flows/validate/ (validates a definition sent in the request body against either profile — see REST API), and the validate_agentflow_definition management command (pipenv run python manage.py validate_agentflow_definition <file.json> --profile ai) for checking a definition on disk.

Node palette

Node	Type	Description
Start	`control.start`	Flow entry point; exposes run params and uploaded files.
End	`control.end`	Flow exit point; collects bound inputs as the flow result.
Condition	`control.condition`	Evaluate a predicate over flow state and route on the result.
Merge	`control.merge`	Converge conditional branches; outputs the branch that ran.
Map	`control.map`	Fan a list out over a body node in parallel (one branch per item).
Join	`control.join`	Collect map branch results after every branch settles.
Loop	`control.loop`	Bounded loop guard; every cycle passes through it.
Knowledge Graph Query	`knowledge_graph`	Scope and retrieve from the knowledge graph. Returns rows in `data` mode, or additionally synthesizes a cited narrative in `report` mode.
Knowledge Graph data	`kg.data`	Scope and query the knowledge graph and return the structured results directly — no report writer. The simpler, data-only surface of Knowledge Graph Query.
Knowledge Graph Display	`kg.display`	Write a cited narrative report from an upstream `kg.data` node’s rows (the deep agent’s report writer, no re-query). Wire `kg.data → kg.display`.
MCP action	`mcp.action`	Run a task with the tools of one MCP server.
Orchestrator agent	`agent.orchestrator`	Give the agent a goal plus a set of allowed blocks and a budget; the LLM picks the path.
Knowledge research agent	`agent.deep_research`	A bounded research agent over the internal knowledge graph + documents (and optionally one MCP server).
Web research agent	`agent.web_research`	A bounded research agent over the live web (Tavily), with cited sources.
LLM generate	`llm.generate`	Generate text from a templated prompt plus optional context.
LLM extract	`llm.extract`	Extract structured fields from context against a per-node schema.
LLM classify	`llm.classify`	Classify the input into one of the configured categories.
Generate DOCX	`data.generate_docx`	Produce a Word document artifact from structured sections, optionally branded with a registered Document Template.
Generate PPTX	`data.generate_pptx`	Produce a PowerPoint presentation artifact (one slide per section), optionally branded with a registered PPTX template.
Generate file	`data.generate_file`	Produce a document artifact in a chosen format — Word (`.docx`), PowerPoint (`.pptx`), PDF, or HTML — reusing the agent’s existing generators.
Index uploads	`data.index_files`	Parse, chunk, and embed uploaded files so downstream nodes can use them.
Read conversation	`data.channel_history`	Read the recent messages of the conversation the run was launched from — a plain transcript plus the structured turns — so the flow can act on what the user and the agent already established.
Human review	`human.review`	Pause the flow for a reviewer; resume when approved or edited.

The Knowledge Graph Query and Knowledge Graph data nodes share an on_clarify policy that controls what happens when scope needs clarification: fail the node, pause for human input (interrupt), or continue with empty rows. To get a cited narrative from a data-only Knowledge Graph data node, wire it into a Knowledge Graph Display node (kg.data → kg.display) and bind end.result to the Display node’s text output — its evidence citations render as source chips in the run output.

The Read conversation node only works on a run launched from a conversation. A canvas or API run has no conversation to read, so the node fails and says so rather than handing an empty transcript to the rest of the flow, and it only ever reads a conversation the person who started the run can open — their own, or one shared with them — and fails with an authorization error on anything else rather than reading it. Its config sets how many of the most recent messages to read (Messages to read, default 20, returned oldest-first), whose messages to include (all, only the user’s, or only the assistant’s), a per-message character cap (default 40,000 characters; 0 disables truncation), and whether an empty conversation fails the node — left on by default, so a downstream step never quietly drafts a document out of an empty transcript.

The Generate DOCX and Generate PPTX nodes each expose a Document Template selector — pick a registered template by name (managed under Document Templates) to brand the output. The Generate file node adds a format chooser (Word, PowerPoint, PDF, or HTML); the template selector is shown only for the docx and pptx formats. Markdown in generated content (## headings, **bold**, bullets) is rendered as real Word/PPTX styling instead of literal markers.

Budgets

Agent nodes (orchestrator, knowledge research, web research, MCP action) run a model-driven loop and must be bounded. Each exposes a budget so a single node can never run unchecked:

Limit	What it counts
Max model calls	Times the agent may call the model
Max tool calls	Tool invocations it may make
Max tokens	Total tokens across the whole loop
Max wall seconds	Total time the step may run

Each box shows that node’s own default — leave it empty to use it. Reaching the call or token limits ends the agent’s loop and returns what it has so far; it does not fail the run, so a budget set too low shows up as truncated work rather than an error. Max wall seconds is a hard deadline rather than a soft one. The knowledge research, web research and Orchestrator agent steps stop at it and hand on the work they already have; the MCP action step reports a timeout through its own error policy. Every other step that has a time limit is failed when it overruns: the step is cut off, whatever it had produced by then is discarded, and the failure is reported like any other step error, so an unresponsive step can no longer hold a run open indefinitely. Steps that carry a built-in time limit — the knowledge graph steps, for example — are now actually held to it; a step with no time limit of its own and no built-in default still runs unbounded. Those built-in limits also apply to flow versions you published before the limit existed — a knowledge-graph step that used to take as long as it needed is now failed at its cap. Raise a step’s Max wall seconds if it legitimately needs longer — from the Budget editor on an agent node, or through Edit as JSON (budget.max_wall_seconds on the node) for a knowledge-graph step, whose Budget editor the canvas doesn’t render.

Publishing and Versioning

A flow you are editing is a draft. Publishing snapshots the current draft into an immutable version:

Click Publish. The draft is validated first — publishing is blocked if validation reports errors. Validation also checks MCP action nodes: an unknown or disabled MCP server, or Allow writes enabled on a server that doesn’t support writes, blocks publishing; whitelisted write tools that would be stripped because Allow writes is off are surfaced as a warning. A Join is checked against the map body it collects: a Body output port set explicitly to a port that body does not produce blocks publishing, because every branch would then count as failed, and a Minimum body length set on a Join whose body produces no default text port blocks publishing too, because the floor could never fire on any branch. Both are errors rather than warnings, and both are fixable only in the draft — a published version is immutable.
A new AgentFlowVersion is created with an incrementing version number. Published versions are immutable.
The flow’s latest published version pointer advances to the new version.

The live version

Every run of a flow uses its live version — the version the chat agent launches, and the default for a canvas or API run. The Versions panel marks the current one with a Live badge. By default a flow follows the latest published version: each time you publish, the newest version automatically becomes live. To roll back or hold on an older version, click Set as live on any validated version in the panel — this pins the live version there, and publishing no longer changes what’s live. Click Follow latest to clear the pin and return to auto-advancing on publish. Either action also loads the now-live version onto the canvas, so the editor shows what actually runs — it arrives as an unsaved change, and your saved draft is untouched until you save. If your canvas already holds unsaved changes, you are asked first: loading replaces them and there is no undo, so you can keep editing instead. The pin is applied either way — declining only leaves the canvas alone. While live is pinned to something other than the latest published version, the editor header carries a Live badge naming the pinned version, as a reminder that the newest published version is not the one running. Only a version that passes validation can be set as live. Existing runs always stay on the version they started with; changing the live version only affects new runs. You can review prior versions from the Versions panel. Use Validate at any time to run save-time validation on the draft without publishing.

AI provenance and publish warnings

When you apply one or more proposals from the Admin Copilot, the draft carries that forward as provenance — which proposals were applied, and the model, brief, and rule-set version behind each one. A draft with any AI-origin content shows a compact AI-drafted badge in the editor; hand-editing the flow further doesn’t clear it, since the AI content is still there until you change it. Publishing an AI-origin draft re-validates it under the stricter ai profile — the same one the copilot’s own proposals must pass — before you ever see the Publish button, and surfaces any AI-profile warnings that turn up under that profile but not under the normal one you publish with. The publish dialog shows the most recent proposal’s model, rule-set hash, and brief, lists those warnings, and requires you to explicitly acknowledge them (a checkbox, not a default) before Publish is enabled — a hand-made draft skips this entirely. This is a warning gate, not a blocking one: publishing itself still runs under the normal human profile, so an AI-profile-only warning doesn’t stop you, it just makes sure you’ve seen it.

Letting the chat agent run a flow

You don’t wire a flow to a dedicated assistant. Instead, you let the normal chat agent discover and launch it as a background sub-agent:

Open the flow and turn on the Sub-agent toggle in the editor header. The flow becomes available to the chat agent.
Write a clear flow description in the editor next to the toggle. The chat agent reads this description to decide when to run the flow, so describe what the flow does and the kind of request it handles. A sub-agent flow with no description shows an amber nudge — the agent can’t route to a flow it can’t recognize.

Once enabled, the chat agent can launch the flow during a normal conversation. When a user asks for something a flow covers — for example, “prepare a response for this RFP” — the agent confirms once (“I can run RFP Response Pipeline — proceed?”), then launches the flow in the background. The conversation stays fully usable while the flow runs. Users can also launch a sub-agent flow directly from the chat composer’s Launch a flow menu, which skips the matching step and starts the chosen flow immediately. The agent maps the user’s request onto the flow’s parameters automatically (flows read them as $.params.<name> / {{ params.<name> }}, and $.params.message is typically the user’s core request forwarded at launch) and binds the conversation’s uploaded files to the flow’s file slots. File slots the agent doesn’t fill explicitly fall back to what the user actually attached in that conversation, newest first — a single slot takes the most recent upload; several slots are matched by label and order. So “here’s the RFP, draft a response” fills the flow’s rfp_document slot from the attachment on that very message. Only user uploads are eligible for this fallback: a document produced by an earlier run in the same conversation is bindable when something names it, but is never picked up implicitly as the next run’s input. If a required file slot is still unfilled, no run is created, and a message is posted into the conversation naming each missing input by its readable label (plus its description, and whether it takes more than one file) and asking the user to attach it and send again. That message is written by the platform, not left to the model to relay, so the user is always told why the flow didn’t start — it is posted at most once per turn. While a sub-agent flow runs, a live flow-run view opens in the chat’s right-hand panel. It is deliberately minimal: a single status line naming the step in flight (“Working on Draft the response”, by the step’s Display name) and a Stop control; the conversation pulses in the sidebar until the run finishes. Closing the panel leaves a View progress control (above the message box) to reopen it while the run is still going. When the flow pauses for a human, the panel shows the review card there instead — see the note below. When the run finishes the panel closes itself — unless the user has a file the run produced open in the panel’s viewer, in which case it stays until they close that document. There is no result view: the flow posts a message into the conversation with the full result and any files it produced, and that message arrives on its own (no manual refresh), so a panel could only duplicate it. Users can also just ask the agent for the status or results of a flow it launched — including questions about a document the run produced. The agent is not limited to the excerpt of that document carried automatically in its context: it can list the documents produced in the conversation, search inside one for a phrase, and read any part of it on demand, so a question about a passage buried deep in a long report is answerable. Each document is access-checked for the person asking. The full technical detail of any run — step log, per-node outputs, state and token usage — lives in the flow editor’s Run panel, where a run links back to the conversation it ran in.

A paused sub-agent run surfaces an Awaiting review card in the conversation’s live flow-run panel, where the user can approve or reject it (with a comment) — or edit what they were shown and approve that instead — without leaving chat; the panel’s reopen control turns amber (“Review needed”) and the conversation’s sidebar row shows an amber review badge until the pause is resolved. The same pending review is also listed in the Agent Inbox (Admin > AI & Agents > Agent Inbox) for a reviewer to act on, but the conversation is a complete path in its own right — a reviewer never has to go to the inbox. Either path resumes the flow, which then posts both the decision and the run’s outcome back to the conversation. See Human-in-the-Loop.

Running a Flow

From the canvas

Use the run panel in the editor to start a run with parameters and uploaded files. The run executes in the background — progress, per-node status, and produced artifacts stream back to the panel. The usage panel shows per-node model/tool call counts and token usage — including, for MCP action nodes, the names of the tools the run actually called, so you can confirm it used the tool you intended, and, for any node, which model spent that node’s tokens, with its call count and token total. A node’s totals on their own cannot be attributed to either.

From chat

When a flow is Sub-agent enabled, the chat agent can launch it during a normal conversation — see Letting the chat agent run a flow. The agent confirms, runs the flow in the background, maps the user’s request onto the flow’s parameters, binds uploaded files to the flow’s input slots, and posts the result and any produced files back into the conversation when the run finishes.

Asking to continue an earlier run

No run can be continued once it has ended — including one that finished successfully. Running the flow again starts a new run from the first step: nothing carries over, no partial output is kept, the new run does not read or revise the earlier run’s output, and every approval is asked again. So when a user refers back to an earlier run — “continue the last RFP”, “pick up where it stopped”, “what happened to that one” — the agent looks that run up before doing anything else. If it is still going, the agent reports its state instead of launching a second one. If it has ended, the agent says how — failed (naming the step it stopped at, where there is one), cancelled, or completed — and says plainly that what it is starting now is a fresh run, rather than describing it as a continuation. The completed case matters as much as the failed one: asked to “continue” a run that had finished, the agent was observed announcing a new run as producing an updated document, which is the same defect one status over. The lookup only ever returns the asking user’s own runs in that conversation.

Reading a run’s progress

The two surfaces show a run at very different resolutions, on purpose. The editor’s Run panel is the debug surface: it lists the raw step log — one entry per node execution, branch suffixes and all — alongside per-node outputs, the run’s state and its token usage. A Map/Join fan-out appears there as it actually executed, one entry per branch, so “which of the nine sections failed?” is answerable. The chat flow-run panel shows only the step in flight, by name, while the run is going. A fan-out is named by the plan node driving it rather than by branch. It reports nothing about a finished run — it closes itself instead — because the run’s result and its files are posted into the conversation as messages. The single exception is a document the user already has open in the panel’s viewer: a run that finishes mid-read never yanks the file away, so the close waits until they close the document.

When a run’s executor stops

A run executes inside the API process; there is no worker queue behind it. If that process stops mid-run — a deploy, a pod restart, a dev-server reload — nothing is left to finish the run. Such runs are reconciled — on the next API start, or on demand from Startup Health — and marked Failed with “Run was interrupted — its executor stopped before the run finished”, so a conversation stops looking permanently busy and its re-open control stops offering a run that nothing will ever complete. A run parked at a Human review gate is never reconciled this way — it is waiting for a reviewer, not orphaned, and resumes as soon as someone answers it. Operators do not have to wait for a restart: Admin > Monitoring > Startup Health has an Orphaned agent flow runs check that reports how many stale runs exist and repairs them in place.

Transient errors and retried steps

A network-level failure inside a node — a dropped connection, a read timeout — is retried once after a short pause, so a single blip does not have to end the step that hit it. The retry is spent inside the node’s own budget: a node that has already used up its declared wall budget is not retried. An attempt the retry absorbed is recorded against that node in the run’s step log, so a retry that worked leaves a trace rather than disappearing. A tool call the agent itself can fix is not a failure. Inside Knowledge research agent and Web research agent, a tool call the far end rejected — a Cypher query the graph refused to parse, a type mismatch in a predicate, a filter naming a document type this deployment does not have — is handed back to the agent as a failed tool result with the reason, and the loop carries on: the agent rewrites the query and calls again. Only the failure it cannot act on ends the step: the graph being unreachable, a timeout, or a permission error on the connection itself (the graph answering NOPERM, which means the credentials or the ACL are wrong and no rewrite will clear it). Before this, one malformed query aborted the whole agent loop and the map branch it ran in — and because the document at the end of the flow does not depend on that branch, the run failed while still producing a document that simply had that branch’s research missing from it. A rejected call is still recorded against the step in the run’s step log, so a rewrite that worked leaves a trace. The agent steps are never retried, in any pass. Orchestrator agent, Knowledge research agent, Web research agent and MCP action each run a loop that can act on an outside system — send the mail, create the record, write through a connected integration. A retry restarts that loop from its goal, with no memory of what the failed attempt had already done, so an action that succeeded before the connection dropped would simply be performed a second time. These steps fail on the first blip instead, which is what they did before the retry existed. What that buys is worth stating exactly: it stops a whole agent loop being replayed, and nothing more. It does not make a step that writes exactly-once — inside the loop a tool call that failed is still retried there, and a call that failed after the far end had already committed looks no different from one that never landed. A flow that writes through an integration still depends on that integration to tolerate the same request twice. Nothing is retried in a pass that resumed from a human gate. Re-running a step after a resume could re-ask a reviewer who has already answered, so the exclusion is deliberately blunt: it covers the whole resumed pass, not just the node holding the gate. What the retry actually covers, then, is the non-agent steps that run before a flow’s first gate — a run that never pauses is covered end to end, and a run that pauses is covered only up to that point. Read your own flow’s shape before relying on it: everything past the first gate is uncovered, so a gate drawn early leaves almost the whole run outside the retry. In the built-in RFP Response Pipeline, Review the compliance matrix sits ahead of the section fan-out, so the parallel section authoring — the part with the most branches, and the likeliest place for a blip — runs on the far side of the gate and is not retried (it is an agent step, so it would not be retried in any case). A failure a later pass genuinely fixed no longer sinks the run either. When a Map branch fails and the same Map, running the same step over the same item, succeeds on a later pass — a loop that re-enters that map — the earlier failure is superseded and the run can settle Completed. The match is on the item, not on its position in the list, so a later pass succeeding at a different section can never clear an earlier section’s failure. It is on the Map and its body step as well: a separate revise Map, with its own body step, is different work and supersedes nothing. That is the shape the RFP Response Pipeline has — re-authoring runs through a second Map rather than a second pass of the first — so a section that failed on the first authoring pass still fails the run there, however well the revise pass rewrites it. Any failure that nothing superseded still fails the run exactly as before.

A step can be red on a run that completed

A step that ran to completion but reported that it fell short is recorded as failed and shown red, even though it produced output. Two independent signals do this, both volunteered by the step itself: a status outside the success set (a model-declared partial, a budget cut-off, an error envelope), or a non-empty list of block failures — a tool the agent called died, which counts regardless of what the model then claimed about its own work. This is deliberate. Before it, the step log was seeded success before a node ran and only ever downgraded if the node raised, so an agent that returned normally while reporting its own failure logged green on every surface a human approves from — and runs shipped documents with empty and stubbed sections that nothing anywhere marked. A green run that delivered a hollow section was the defect; a red step on a run that produced a file is the fix, not a regression. Two consequences to hold onto:

The run status is unchanged. A degraded step does not raise, does not alter routing, and does not fail the run — a run whose steps degraded still settles Completed. Instead, the completion message posted back to the conversation appends a note naming the step that stopped early and warning that parts of the document may be incomplete. (A run that genuinely fails still reports Failed, and the admin Run panel’s step log names the failing step and shows which steps never ran.) When the flow fanned out over a Map/Join, that failure no longer reports only the headline of the node that raised: the run’s error message — posted back into the conversation for a sub-agent run, shown on the Run panel for a canvas one — also names, per Join, how many branches were rejected or held back for review in the last pass, how many sections are recorded, and each named section with the underlying cause, plus a separate line for sections condemned by an earlier pass that no later pass re-produced cleanly. The wording carries the distinction that tells you what to do next: rejected means nothing of that section survived, held back for review means its text is recorded and was not cleared for use. The message is budgeted to fit the chat preview and the held-back sections are named first, so what gets truncated is the failing node’s own error — its full text is still on the run’s step log and error list in the Run panel.
A degraded step’s output is still shown. It is not withheld the way a crashed node’s is, because that content is exactly what a reviewer needs in order to judge how bad the shortfall actually is.

Step status is last-wins, so a branch that a later revise pass re-ran successfully clears; a step does not stay red for the rest of the run because of one earlier attempt.

Output length is deliberately not a degradation signal. On the runs this was built from, good sections spanned 2,844–18,339 characters and degraded ones 400–15,782 — the two classes overlap completely, so no threshold separates them and any value chosen would reject good work. A length floor is available as an opt-in per-flow setting on Join instead, and is a stub floor rather than a quality test.

Human-in-the-Loop (HITL)

Flows pause whenever they reach a Human review node (or a Knowledge Graph node configured to interrupt on clarification). A paused run waits for a reviewer to approve or reject (with a comment) before it resumes. Paused runs surface in the Agent Inbox at Admin > AI & Agents > Agent Inbox, which lists every run awaiting human input — newest pause first — with the paused node and a click-through to act on it. Runs you start from the canvas also surface their pause in the editor’s Run panel. Resuming a run is atomic: two reviewers cannot both resume the same pause. A gate can fail without the work it guards failing. When an agent step calls Human review as one of its allowed blocks and that block is the step’s only failure — the step returned normally, reported no problem of its own, and nothing but the gate died — the step is still recorded as failed and its branch still counts as failed at the Join, but its text is kept rather than thrown away, and is reported as held back for review rather than rejected. An unapproved section is not an untrustworthy one, so a flow with a revise lane gets another pass at it while the words already written stay recorded. If a content block failed in the same step, that is the whole story and the branch is treated as unusable exactly as before. A gate that cannot reach the store where it normally parks its payload still stops the run and shows the reviewer the full payload inline, rather than dying quietly while the flow authors on.

Editing before approving

A reviewer is not limited to a yes/no on what the node proposed. Where the review payload is a document or a block of text, the card offers Edit: the reviewer rewrites the text — or a document’s title and each of its sections — and then approves. The edited version is what the rest of the flow receives, so a downstream Generate DOCX node renders the reviewer’s wording rather than the draft they were shown. An edited card is marked edited, and Revert restores the original. A very large payload is stored in the run record in elided form and fetched in full when the card opens; it is not editable until that full content has arrived, so nobody can overwrite a document they have not actually seen.

What the conversation records

For a run launched from a conversation, each decision is written back as a message in that conversation: which gate it was, whether the reviewer approved or rejected it, and the note they left (a rejection with no note is recorded as having none). When the reviewer edited before approving, the message says so and carries what was approved — the edited version — so reading the thread back shows what actually went downstream, not the superseded draft. Answers to a mid-run question are recorded the same way. Each decision message is tied to the review it answers, so a partial resume or a re-settle cannot post it twice. The question and its answer are shown as one card. Both messages are still recorded — nothing is deleted — but the transcript renders them together: the answer appears underneath the question it answers, and the question’s “answer it in the run panel” call to action drops away once it has been answered, because it no longer applies. A long answer — a reviewer who rewrote a whole document before approving, say — is shown as a preview with a View full response control that opens the rest in the side panel. One case deliberately stays as two separate cards: an answer given after the user has already sent another chat message, so a verdict never appears above a later user turn.

Several questions at once

A run can pause on more than one question at the same time — for example two Human review nodes that sit on parallel branches, or a review plus a Knowledge Graph clarification. When that happens:

Every pending question is listed together, and the reviewer can answer them in any order.
A reviewer is never made to wait. An answer given while the run is still applying a previous one is held and submitted automatically as soon as the run frees up — it is not refused, and there is nothing to retry. Only the card being submitted right now is briefly unavailable; questions the run still lists as pending stay answerable throughout.
An answered card clears, and the same question does not come back. A gate the flow re-raises carrying new content — a revise pass returning to the same Human review node — is a fresh question and is shown again: a card is suppressed on what it asked as well as on which gate asked it, so a re-settle of an unchanged question stays hidden while a genuinely re-asked one comes back and has to be answered again. The second answer is recorded in the conversation as its own decision rather than folded onto the first. Unanswered questions stay on screen, and the conversation’s amber review marker stays lit until the last one has been answered.
Each question is answered on its own — there is no bulk sign-off. Approving or rejecting a card submits that card’s answer along with any edits made on it, and each decision carries its own note; a free-text question with an empty answer box has no defensible default and is never answered on the reviewer’s behalf.

Because each answer is applied to a specific question, an API caller resuming a run with several pending questions must say which one it is answering (see REST API); a bare value is rejected.

The review payload shown to a reviewer (and any generated documents) is cleaned of raw [evidence:…] citation markers, so reviewers see readable text. Inline citations are still preserved in the assistant’s chat answers.

Templates

Experio seeds starter templates you can duplicate into your own draft:

RFP Response Pipeline — extracts requirements from an uploaded RFP, drafts sections, and produces a formatted response document.
Grunley Scope Merge — merges uploaded scope-of-work documents into a single document.
Knowledge Graph Report — answers a question from the knowledge graph as a cited narrative report.
RFQ Generation — turns a scope of work into a supplier Request For Quotation, filling in an uploaded Excel RFQ template and returning the same workbook with its branding, formatting and formulas intact.

Duplicate a template from the flows list, then edit and publish your copy.

Delivering a template fix to flows already in use

A template is a starting point, not a live link. “Use template” copies the template’s definition into a new, independent flow; nothing records where that copy came from. This matters when a fix ships in a template, because the obvious assumptions are both wrong:

Re-seeding the templates does not change flows already created from them. It updates the template flow only.
Re-publishing the derived flow does not pull the fix in either. Publishing snapshots that flow’s own draft, which still holds the definition copied when it was created. Versions are immutable, so nothing rewrites it in place.

The consequence worth planning for: a deploy can report success while the fix has not reached the flow that actually runs.

Re-seeding the templates

Templates are seeded by a management command, run from server/:

pipenv run python manage.py seed_agentflow_templates

It is idempotent — a template whose definition is unchanged publishes nothing and logs Unchanged template <name> (v<N>). A changed one updates the template’s draft and publishes a new immutable version, logging Updated template <name> and published v<N>. A template that fails save-time validation aborts the command rather than seeding a broken definition. Templates are matched by name. If a workspace somehow has two templates with the same name, the seeder updates the oldest (the one it originally created) and leaves the duplicate alone rather than guessing.

The seeder skips templates a person has edited

To protect a tenant’s own authoring, the seeder refuses to overwrite a template it did not write, and says so in the log: Skipping <name>: staff-published v<N> or Skipping <name>: edited draft. A template counts as staff-authored on either of two signals:

any version of it was published by a person (versions the seeder creates have no publisher), or
it has an unpublished draft that differs from its published snapshot — the seeder’s own draft is always identical to what it published, so any divergence is a human edit.

The second signal is sticky. A template hand-edited once — during a demo or a review, and never published — is treated as staff-authored from then on, so it silently stops receiving template updates on every subsequent deploy. The log line is the only place this is visible. Read the seeder’s output on deploy; a Skipping line means that template is now frozen for that tenant.

To override the skip, pass --force:

pipenv run python manage.py seed_agentflow_templates --force

This destroys the staff edits to that template — it does not merge them. It logs loudly (OVERWRITING staff-authored <name> (--force): their template edits are being discarded) so the choice is never invisible in a deploy log. Export the tenant’s definition from the flow’s Edit as JSON dialog before running it.

Getting the fix into the flow that runs

Re-seeding leaves you with an updated template and an unchanged flow. The direct way to close that gap is the delivery command, run from server/:

pipenv run python manage.py deliver_agentflow_template --template "RFP Response Pipeline"

It reports what it would do and writes nothing until you add --write, and says so on the last line (DRY RUN — nothing was written. Re-run with --write to publish.). --template is repeatable and defaults to every built-in template. Derived flows are found by name prefix, which cannot reach a copy somebody renamed — name that one with --flow <uuid> instead (repeatable, and it needs exactly one --template). It changes which flows are considered, not what the command is willing to write to — the checks below still apply to a flow you named. A --flow id that matches nothing, or that names a template row, is called out as NOT DELIVERABLE rather than passing silently. What it reads matters as much as what it writes. The definition comes from the shipping code, not from the library template row, so a template the seeder has frozen as staff-authored (the Warning above) still delivers. It skips a flow whose latest version a person published, or whose draft has diverged from that published snapshot, because delivery would revert that work; --include-human-authored overrides both, and reverting is then exactly what it does. It also skips a flow whose live version is pinned, and no flag overrides that one — a pin does not advance on publish, so the new version would never run. Unpin it first. A skip of either kind is logged as SKIPPED with the reason, so a deploy log says which flows were left alone. Delivery validates the definition, names the nodes it would rewrite, publishes a new immutable version — runs in flight and paused runs keep the definition they started on — and advances the flow’s draft to match, so a later publish from the canvas cannot quietly undo it. Unlike pasting a definition into Edit as JSON, it keeps the flow’s own name and re-pins the internal id itself. If you would rather not run a command, or the flow is one the command skips, the two manual routes still work:

Create a fresh flow from the updated template (Use template), re-apply any customization, publish it, and switch the Sub-agent toggle and description over from the old flow; or
Carry the definition across by hand — export the updated template’s definition from its Edit as JSON dialog, paste it into the existing flow’s, apply, and publish.

The second route keeps the flow’s identity and anything already pointing at it. Two things to expect: applying a pasted definition renames the flow to the name inside that definition (rename it back if you don’t want the template’s name), and the definition’s internal id is re-pinned to the flow’s own automatically, so you don’t need to edit it. Either way, publishing is the step that matters. A flow’s draft is not what runs — the live version is. Verify afterwards on the Versions panel that the version you just published is the one carrying the Live badge, and remember that runs already in flight stay on the version they started with.

REST API

Agent Flows are also available over REST under /api/agent-flows/ for programmatic use:

Endpoint	Purpose
`GET/POST /api/agent-flows/`	List and create flows (writes are staff-only). Add `?subagent_enabled=true` to list only sub-agent-enabled flows.
`PATCH /api/agent-flows/{id}/`	Update flow fields, including `subagent_enabled` and `description` (staff-only)
`POST /api/agent-flows/{id}/validate/`	Validate the saved draft without publishing. `profile` (query param or body, default `human`) selects the strictness — `ai` is the stricter profile an AI-origin draft is re-checked under. Response: `{valid, errors, warnings}`.
`POST /api/agent-flows/validate/`	Validate a definition by value — nothing is read from or written to a saved flow. Body: `{"definition": {...}, "profile"?: "human" or "ai", "subagent_enabled"?: false}`. An invalid definition is still a `200` with `valid: false`; `400` is reserved for a malformed body. This is what the Admin Copilot’s own validation and the `validate_agentflow_definition` management command use — see Hollow-pattern checks.
`POST /api/agent-flows/{id}/publish/`	Validate (under the `human` profile) and publish the draft as a new version
`POST /api/agent-flows/{id}/set-live/`	Set the live version: body `{"version": <number>}` pins live to a validated version; `{"version": null}` clears the pin so the flow follows the latest published version again (staff-only)
`GET /api/agent-flows/{id}/versions/`	List published versions
`POST /api/agent-flows/{id}/runs/`	Start a run (returns immediately; executes in the background)
`GET /api/agent-flows/runs/`	List runs; filter with `?surface=` (e.g. `chat`, `canvas`, `subagent`) and `?channel=<id>`
`GET /api/agent-flows/runs/{run_id}/`	Poll run status, state, step log, and usage
`POST /api/agent-flows/runs/{run_id}/resume/`	Resume a paused (HITL) run. With several questions pending, send `{"resume": {"<interrupt_id>": <value>}}` naming the one you are answering — a bare value returns `400`. Returns `409` while another resume is still in flight: the lease is momentarily busy and the answer is worth re-sending. Returns `410` with a detail naming them when the answer names only questions that are no longer pending — already answered, or the run has moved on — and nothing about that request can succeed on a retry. A map naming several questions of which only some are still pending applies the ones that matched; the rest are dropped and recorded only in the server log, not on the response.
`GET /api/agent-flows/pending-hitl/`	List runs awaiting human input
`GET /api/agent-flows/node-types/`	Node registry metadata for the canvas palette, plus a `node_types_hash` version stamp for the palette

A flow’s JSON carries subagent_enabled (whether the chat agent can launch it) and its live-version pointers: live_version (the pinned version id, or null when the flow follows the latest published version) and live_version_number (the effective live version number).

Reads are available to authenticated users; creating, editing, and publishing flows require staff permissions.

Getting Started

Data Sources

Knowledge Graph

User Management

Integrations

Settings

Monitoring

Overview

The Flows List

Building a Flow

Config fields

Bindings

Declaring run parameters

Edit as JSON

Hollow-pattern checks

Node palette

Budgets

Publishing and Versioning

The live version

AI provenance and publish warnings

Letting the chat agent run a flow

Running a Flow

From the canvas

From chat

Asking to continue an earlier run

Reading a run’s progress

When a run’s executor stops

Transient errors and retried steps

A step can be red on a run that completed

Human-in-the-Loop (HITL)

Editing before approving

What the conversation records

Several questions at once

Templates

Delivering a template fix to flows already in use

Re-seeding the templates

The seeder skips templates a person has edited

Getting the fix into the flow that runs

REST API

​Overview

​The Flows List

​Building a Flow

​Config fields

​Bindings

​Declaring run parameters

​Edit as JSON

​Hollow-pattern checks

​Node palette

​Budgets

​Publishing and Versioning

​The live version

​AI provenance and publish warnings

​Letting the chat agent run a flow

​Running a Flow

​From the canvas

​From chat

​Asking to continue an earlier run

​Reading a run’s progress

​When a run’s executor stops

​Transient errors and retried steps

​A step can be red on a run that completed

​Human-in-the-Loop (HITL)

​Editing before approving

​What the conversation records

​Several questions at once

​Templates

​Delivering a template fix to flows already in use

​Re-seeding the templates

​The seeder skips templates a person has edited

​Getting the fix into the flow that runs

​REST API

Overview

The Flows List

Building a Flow

Config fields

Bindings

Declaring run parameters

Edit as JSON

Hollow-pattern checks

Node palette

Budgets

Publishing and Versioning

The live version

AI provenance and publish warnings

Letting the chat agent run a flow

Running a Flow

From the canvas

From chat

Asking to continue an earlier run

Reading a run’s progress

When a run’s executor stops

Transient errors and retried steps

A step can be red on a run that completed

Human-in-the-Loop (HITL)

Editing before approving

What the conversation records

Several questions at once

Templates

Delivering a template fix to flows already in use

Re-seeding the templates

The seeder skips templates a person has edited

Getting the fix into the flow that runs

REST API