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 > Agents > Agent Toolkit > Agents — flows appear in the same list as agents, and the + Agent picker offers XFlow. There is no separate flow entry in the menu.

Why it matters

An XFlow is a processing pipeline — a connected graph 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 two different things. You’ll see the word “workflow” used loosely for both elsewhere — this 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.

Every collection already has a built-in ingestion flow (Knowledge collections add an indexing step); you build your own flows 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 > Agents > Agent Toolkit > Agents.
2. To create: click + Agent → in the picker choose XFlow → the Add XFlow dialog opens (name + description; see below). Save, and the canvas opens.
3. To open an existing one: click its row in the list, or filter the list to XFlow first. XFlows and agents share the list; the XFlow rows open the canvas editor instead of the agent editor.

The XFlow editor shell

┌ XFlows ───────┐┌ 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        │ │
│ [ + XFlow ]    ││ │                    ┌────▼─────┐      │  │  Move To State       │ │
│                ││ │                    │ Move To  │      │  │  Vector Ingestion    │ │
│                ││ │                    │  State   │      │  │  … (operators only)  │ │
│                ││ │                    └──────────┘      │  └──────────────────────┘ │
│                ││ │    orient / zoom in / zoom out       │                            │
└────────────────┘└─────────────────────────────────────────────────────────────────────┘

• Left rail — once a flow is open you get a searchable list of the project’s XFlows (name + description + pin icon). Footer + XFlow to create; a per-row ⋮ menu offers Edit / Delete / Duplicate. (When you open a flow straight from the Agents list, that list is your rail instead.)
• 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.
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.	Each obeys your access.

Watch out. Some flows are built and maintained by the platform — the one that ingests documents into every collection, for example. You can look at them but not edit them.

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) groups nodes into three kinds — Stages, Activities, and Functions (the operators):

• Stages — currently empty. Nothing in this group can be dropped on the canvas today.
• Activities — a single tile: Python Library (run a Studio-authored Python/Library snippet, A13 · Library & bots).
• Functions / operators — the full set. 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

What you can actually drag. The palette shows three groups, but only the operators listed above plus Python Library can be dropped on the canvas today; the Stages group is empty. Build from the operators above.

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 (each obeys your access): 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 are rejected) and a Description. Under Show Advanced Settings you can also set Concurrency Limit, Execution Profile (how much resource each run gets), 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’s configuration dialog.
3. Configure a node — the 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 link (or pick a file with 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 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 side panel with the run’s identifiers, 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 side panel 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 that sits at queued and never starts usually means the platform’s processing capacity isn’t available rather than anything wrong with your pipeline — ask your administrator before you start editing nodes.

Meshes use this same canvas. Open a Mesh and the palette narrows to XFlow Operator, Queue and Service, and the Runs tab becomes the mesh Run trace (member timeline, queue-health banner, and a Baton trail of the hops between members). 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 ingestion 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 an event: pick a collection-ingestion trigger and you choose the collection, or pick a stage trigger and you choose the stage.
• 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 > Agents > Agent Toolkit > 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.
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 palette — Move To State and SQL Operator are the write-style operators you can drag.)
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 · Trained models (Classic ML) — trainable AI models, prediction reports, and the model-chaining AI Pipeline. A different kind of pipeline entirely from this one.
• A11 · Teams & mesh — wire XFlows and agents into durable, restart-surviving meshes; the Queue / Service / pub-sub nodes and the mesh run trace.
• R4 · XFlow node reference — every node in the palette, the node card, edges, the Execute dialog, and the full Runs and mesh-trace screens.
• D3 · Taxonomy, lifecycle, tags & events — the Lifecycle/Stateflow an XFlow is not.