XFlows & pipelines

In one line. What an XFlow is, when to build one instead of a single agent, and how to author, run, and debug one in the visual canvas. You’ll be able to. Build a small extract → validate → write pipeline from the node palette, execute it, and read its run logs. Where this lives. Studio ▸ Agent Builder ▸ Agents (XFlows appear in the unified Agents list; the + Agent picker offers XFlow). The same editor also has a home at Studio ▸ Automation ▸ XFlow (automation/xflow).

Why it matters

An XFlow is a processing pipeline — a directed graph (a DAG) of operators that does work on your documents or data: fetch something, run an agent, query SQL, call an API, write a result. You build one when the work is deterministic, multi-step, and reusable — a fixed sequence you want to run the same way every time, over one document or a hundred thousand.

Watch out — the single most common newcomer mix-up. An XFlow is a pipeline of operators (a verb that processes documents). A Lifecycle / Stateflow is the set of review stages a document moves through (D3 · Taxonomy, lifecycle, tags & events). They are different objects in different tables. The codebase overloads the word “workflow” for both — the Academy never does. XFlow = pipeline. Lifecycle = stages. Burn it in.

XFlow vs a single agent — which to reach for

Build a…	When the work is…
Single agent (A3)	One open-ended, judgement-heavy task — “read this and extract the fields”, “answer this question”. The agent decides how.
XFlow (pipeline)	A fixed, ordered sequence of steps — extract, then validate, then write to a table, then email on failure. You want it deterministic and repeatable, and you may want to reuse it across collections.

An XFlow can call an agent as one of its steps (the Agent Operator), so you get the best of both: a deterministic spine with an AI step where judgement is needed.

Under the hood. An XFlow is stored as bm.workflows + bm.workflow_tasks and runs in the Agent-Orchestrator as a Prefect flow. You never touch Prefect — you see nodes, edges, and runs. Every collection already has a system-seeded ingestion XFlow (and Knowledge collections add a vector-ingestion step); you build your own XFlows for downstream work.

Reaching the editor

XFlows are part of the unified Agents list, so you create and open them the same way you do agents:

1. Go to Studio ▸ Agent Builder ▸ Agents.
2. To create: click + Agent → in the picker choose XFlow → the Add XFlow dialog opens (name + description; see below). Save, and the workflow-activity canvas opens.
3. To open an existing one: click its row in the list. XFlows and agents share the list; the XFlow rows open the canvas editor instead of the agent editor.

Tip. The same editor also lives standalone at Studio ▸ Automation ▸ XFlow, with its own left-rail list of XFlows. It’s the identical canvas — use whichever entry point you prefer.

The XFlow editor shell

┌ XFlows (L2) ──┐┌ Acme Extract Flow          [ XFlow | Runs ]                          ┐
│ search…        ││  Enable   Auto-Refresh   Save   Discard   Execute ▾   ⋮             │
│ ▸ Extract      ││ ┌──────────────────────────────────────┐  ┌─ palette ────────────┐ │
│ ▸ Classify     ││ │ ...... dotted canvas ..........      │  │  Stages: (empty)     │ │
│ ▸ Ingest (pin) ││ │   ┌──────────┐     ┌───────────┐     │  │  Python Library      │ │
│   …            ││ │   │  Agent   │────▶│Conditional│     │  │  Agent Operator      │ │
│                ││ │   │ Operator │     │ Operator  │     │  │  Conditional Op.     │ │
│                ││ │   └──────────┘     └────┬──────┘     │  │  SQL Operator        │ │
│                ││ │                    ┌────▼─────┐      │  │  Move To State       │ │
│ [ + XFlow ]    ││ │                    │ Move To  │      │  │  Vector Ingestion    │ │
│                ││ │                    │  State   │      │  │  … (operators only)  │ │
│                ││ │                    └──────────┘      │  └──────────────────────┘ │
│                ││ │    orient / zoom in / zoom out       │                            │
└────────────────┘└─────────────────────────────────────────────────────────────────────┘

• L2 left rail — a searchable list of XFlows (name + description + pin icon). Footer + XFlow to create; a per-row ⋮ menu offers Edit / Delete / Duplicate. (Hidden when the editor is embedded in the Agents list — there the unified list is your L2.)
• L3 tabs — XFlow (the canvas) and Runs (execution history).
• Toolbar — the controls that act on the whole XFlow:

Control	What it does	Notes
Enable toggle	Turns the XFlow’s scheduled run on/off.	Disabled while you have unsaved changes.
Auto-Refresh toggle	Live-refreshes the Runs tab (with a pulsing spinner).	Only on the Runs tab.
Save	Persists the graph + dialog settings.	Disabled unless something changed (dirty).
Discard changes	Reverts to the last saved version.
Execute ▾	Hover-menu: Quick Run / Document Run / Custom Run.	See “Running it”.
⋮ action-menu	Publish · Edit · Duplicate · Pin / Unpin · Delete.	All permission-gated.

Watch out. XFlows whose name starts and ends with __ are system-reserved (the seeded ingestion spine, for example). Non-super-admins don’t get edit affordances on them. Don’t name your own XFlows that way.

The canvas

The XFlow tab is a directed-graph canvas. You build the pipeline by dragging nodes from the palette, configuring each, and connecting them with edges. An empty canvas prompts: “No task found in flow. Drag and drop any task to get started.”

The node palette — what you can actually drag today

The palette (top-right, draggable; expand/collapse with the expand icon) still groups nodes into three kinds — Stage, Activity, and Functional / operator — but the editor filters what it renders, so what you can drag onto the canvas today is narrower than the full catalogue:

• Stage group — currently empty. None of the coarse phase nodes (Manual Review, Sources, RPA Bots, Agent Flow, AI Pipeline) are surfaced as draggable tiles.
• Activity group — a single tile: Python Library (run a Studio-authored Python/Library snippet, A13 · Library & bots). The other activity nodes (Export, Data Feeds, Conditional, Rescore Models, Regroup Summary, User Allocation) are not in the palette.
• Functional / operator group — rendered in full. These are the real workhorses you build pipelines from:

Operator	Does	Operator	Does
Agent Operator	run an Agent as a step	Conditional Operator	branch on a condition
SQL Operator	run a SQL query	Xflow Operator	call another XFlow
API Fetch	make an HTTP/API call	Iterator Operator	loop over items
Send Email	send mail (To/Subject/Body)	Bot Operator	invoke an RPA Bot
Move To State	advance a doc’s lifecycle stage	Vector Ingestion	chunk → embed → index for Knowledge
Bash Operator	run a shell command	Agent Finetuning	start a fine-tune step

Reality check — the palette is filtered. The data model defines a much larger node set (the full Stage and Activity nodes — Manual Review, Sources, Export, Conditional, and the rest). But the live editor restricts the rendered palette to the operators above plus the single “Python Library” activity (the Stage group renders empty). The node reference catalogues the whole model and marks which nodes are surfaced vs present-but-filtered. Build pipelines from the operators above — they are what you can actually drop on the canvas.

The Move To State operator is the only place a pipeline touches a Lifecycle — it pushes a document to a stage. The XFlow itself is still a pipeline, not a Lifecycle.

The node card

Each node on the canvas shows an icon tile (coloured) + an inline-editable label and description. Watch for the warning badge — it means required parameters are missing; the run will be unhappy until you fill them. An optional footer shows a doc count (deep-links to those documents); expanding the card reveals the roles that can view it and its Operator Type. Hovering reveals action icons (permission-gated): start-connection, cancel-connection, edit (or double-click), and delete.

Edges and canvas controls

• Connect two nodes: hover the source node, click its start-connection arrow, then click the target node. An arrow appears.
• Edit an edge: click the edge line → the Edit Edge dialog (Name, Description); edit or delete it there. Click the line again to disconnect.
• Canvas controls (bottom-right): Switch Orientation, Zoom In, Zoom Out. The legend bar adds Zoom-to-window and Maximize/Normal (which toggles palette visibility). The canvas auto-zooms to fit on your first click.

Building a pipeline

1. Open or create the XFlow (above). In the Add XFlow dialog set a Name (required; duplicate names and reserved __ names are rejected) and a Description. Under Show Advanced Settings you can also set Concurrency Limit, Execution Profile (size class), Repeat Every (the schedule), Retries / Retry Delay, the Trigger event types, and an On Failure Notification email. Save.
2. Add nodes — drag tiles from the palette onto the canvas. Each drop opens the node config dialog (create-task-meta-info).
3. Configure a node — the config dialog’s fields are operator-specific (a SQL Operator asks for a query; an Agent Operator asks which agent; an API Fetch asks for a URL). Fill the required params so the warning badge clears. Re-open any node later via double-click or its edit icon.
4. Connect edges — wire the nodes in run order (start-connection arrow → target). The graph’s direction is the execution order.
5. Save — the toolbar Save lights up while you have changes; click it to persist.

Running it

Execute

Click Execute ▾ and pick a mode:

Mode	What you supply	Use it for
Quick Run	nothing	Fire the whole pipeline immediately.
Document Run	a document_url (or pick a file via the drive picker)	Run against one specific document.
Custom Run	free-text Run Input (JSON/params)	A one-off run with custom input.

The run is queued and the XFlow Progress overlay appears, streaming live status (run id, engine URL) until it finishes.

The Runs tab

Switch to Runs to see execution history. A filter bar lets you narrow by Tags, Stage, and Date Range (quick radios: Today / Yesterday / Week / Month / Custom). The run table shows:

• Flow Name (with copy-run-id / copy-document-id),
• a Status pill — completed / failed / running / paused / cancelled, each with an inline action (Retry / Resume / Cancel / Suspend / rerun) for its state,
• Start Time (sortable) and Total Duration.

Select rows to get a bulk toolbar (Retry / Pause / Resume / Cancel / Delete). Click a row to open a right sidenav (60%): header chips (parent_run_id, flow_run_id, deployment_id), a state badge, duration, and two tabs — Task Logs (expandable per-task rows with timestamped, level-coded lines) and Logs (the raw scrollable stream).

Debugging a failed run

1. In Runs, find the run with a red Status pill.
2. Click it → open Task Logs in the sidenav and expand the task that stopped the chain (the failing operator).
3. Read the level-coded error lines; cross-check that operator’s config in its node dialog.
4. Fix the node (or the upstream data), Save, then hit the inline Retry on the run.

Tip. A run stuck at queued that never starts usually means the Prefect worker isn’t running (locally, the worker container is down). It’s an environment issue, not your pipeline.

Mesh mode. When the editor runs in Mesh mode, the palette is restricted to exactly XFlow Operator + Queue + Service, and the Runs tab switches to a mesh Run trace (member timeline, queue-health banner, pub/sub Baton trail). That’s the subject of A11 · Teams & mesh.

How an XFlow gets triggered

You rarely run an XFlow only by hand. The production triggers:

• As a collection’s processing pipeline — a collection’s ingestion / secondary XFlows run per document as it arrives (set on the Job’s Secondary XFlows, see D4 · Ingestion & connectors).
• On a schedule — set Repeat Every in Advanced Settings and flip the Enable toggle; the XFlow then runs itself on that interval.
• On an event — the Trigger field (Add XFlow dialog) fires the pipeline on events like Entity Ingestion or a Stage change.
• From a mesh — a mesh wires the XFlow to other runnables as a durable pipeline segment (A11).

Try it yourself

Build a tiny three-node extract → validate → write pipeline:

1. Studio ▸ Agent Builder ▸ Agents → + Agent → XFlow. Name it Try Extract Validate, add a description, Save — the canvas opens.
2. Drag an Agent Operator onto the canvas; configure it to call your extraction agent from A3. This is extract.
3. Drag a Conditional Operator (or a Python Library step) and configure a simple check — e.g. “is the total present?”. This is validate. Connect extract → validate with an edge. (Both of these are in the live palette — see the palette section above.)
4. Drag a Move To State operator as write — advance the document to the next lifecycle stage. Connect validate → write. (There is no “Export” tile in the current palette; use an operator that is actually draggable, such as Move To State or SQL Operator.)
5. Confirm no node shows a warning badge, then Save.
6. Click Execute ▾ → Document Run, pick a sample document, and watch the Progress overlay.
7. Open the Runs tab, click your run, and read Task Logs for each of the three steps. If a step is red, fix its config and Retry.

You’ve now built, run, and inspected a real pipeline.

Where to go next

• A9 · AI Builder — trainable AI models, prediction reports, and the model-chaining AI Pipeline that the AI Pipeline stage node runs.
• A11 · Teams & mesh — wire XFlows and agents into durable, restart-surviving meshes; the Queue / Service / pub-sub nodes and the mesh run trace.
• XFlow node & operator reference — every node in the palette, the node card, edges, the Execute dialog, and the full Runs/Mesh-trace surfaces.
• D3 · Taxonomy, lifecycle, tags & events — the Lifecycle/Stateflow an XFlow is not.