Flows
Visual workflows composed of typed, extensible steps.
A flow is a visual workflow that can express supervisor patterns (a coordinator agent directing specialist agents), conditional branching, manual iteration, and tool calls, and supports human-in-the-loop pause/resume.
[Input]
│
▼
[Coordinator Agent] ──────────────┐
│ │
▼ ▼
[Knowledge Agent] [Specialist Agent] [Tool Agent]
│ │ │
└────────────────────┴──────────────────┘
│
▼
[Output]An extensible step catalog
Every step type in the flow builder follows the same contract — a display name, a typed configuration schema, and an execution behavior. New step types can be added to the catalog without changing any existing step or how the workflow runs, so the catalog grows without risk of regressions elsewhere.
Built-in step catalog
| Step | Category | Description |
|---|---|---|
| Agent | AI | Runs a configured agent (system prompt + model). Optional toggles let it reuse the agent's own Knowledge Base(s) ("Use Agent Knowledge") or connected MCP server(s) ("Use Agent MCP Servers") directly — the same retrieval/tool-calling behavior as standalone agent execution, without wiring a separate Knowledge retrieval/Tool call step. It also takes the agent's memory and guardrail settings and reads input.history from the run input like a standalone agent. Session memory (on by default, with memory_max_turns, default 20) remembers the conversation across turns of the same session, including the tool results the agent worked with, so a follow-up can build on them. A turn that ends in a tool request (for example a tool branch that finishes the run at the End step) is remembered too; the next turn tells the model that the call returned no result because the flow ended the turn in that tool's step and showed its output to the user. That latest turn is handed back to the model as tool-call rounds together with the reasoning behind them (a model keeps its reasoning only across a turn that never reached a final answer), while older turns come back as text. While it holds anything it replaces input.history; it can be switched off. Max tool rounds (max_tool_rounds, 1–10, default 10) caps how often the step may be re-invoked with tool results in one run; past it the run fails (or takes the step's error route). If the model returns nothing (no text and no tool call) or the call is blocked or fails, the step fails — it never passes an empty answer on. Reasoning Effort left unset uses the agent's own setting (pick a value on the step to override it, none switches it off); Response Format left unset uses the agent's own format, Text switches it off for this step, and JSON Schema (with json_schema: {name, schema, strict}) makes the answer JSON that follows the schema; Tool Choice applies to the connected Tool steps and to the agent's own MCP servers (none offers no tool, required forces a tool call on the first turn), and the calls the agent made itself are listed with their results in executed_tool_calls (tool_calls is only for calls that Tool steps must answer); when the step is re-invoked with the answers of its Tool steps, the model gets every tool round of the run back as the assistant's tool call (with the reasoning behind it, for models that return reasoning) followed by the tool result; the knowledge passages it used are in sources (see Sources) |
| LLM | AI | A single raw model call, without agent wrapping. If the model returns nothing (no text and no tool call, for example a reasoning model that spent all of max_tokens thinking) the step fails with a message that says so, and its token count; the flow never carries on with an empty answer. Response format JSON object asks the model for a single JSON object; JSON Schema (with json_schema: {name, schema, strict}) makes the answer JSON that follows your schema; Custom settings (a JSON object such as {"top_p": 0.9, "stop": ["END"]}) passes extra model parameters — which apply depends on the model; credentials, endpoint, tools and streaming are managed by the platform and refused |
| Tool | AI | Exposes a tool definition to the preceding model call and runs it. The name is required, 1–64 letters, digits, _ or - (no spaces), and unique among the tools of one model step; the description is required; parameters must be a valid JSON Schema of "type": "object" (the panel builds it from a list: Add parameter with a name, a description, a type and a Required checkbox; Edit as JSON is there for schemas the list cannot express). The arguments the model sent are published already parsed as tool_args.<tool name>, so later steps read them with plain paths: {{tool_args.get_order.order_id}}, {{tool_args.search.filters[0].field}}, or input.tool_args.get_order.order_id in a script. Parallel tools each keep their own entry. It is null when the model did not send a JSON object (it is never repaired); input.tool_calls[i].arguments still holds the raw JSON text |
| Catch Up | AI | Terminal step that rejoins a tool result back into the model call that requested it. It only belongs after a Tool step: placed anywhere else (or given outgoing connections) the flow is reported as invalid |
| RAG Retrieval | Data | Retrieves from a knowledge base. The step fails when the knowledge base is not found, the query_key is not in this turn's data, or the query text is empty — finding no documents is a result, searching for nothing is a mistake. Score threshold (0–1) is a minimum cosine similarity: 0 keeps every result, 0.5 keeps only close matches (a passage found only by the keyword search counts as similarity 0). Its retrieved_docs output carries the raw passages and sources the same passages with document name and short excerpt, which the run reports as sources. Metadata filter (a JSON object of simple name/value pairs, text values may use {{key}}) only searches chunks whose metadata (editable per chunk in the knowledge base) holds every pair; not available for graph-based knowledge bases |
| Text Output | Data | Emits a fixed or templated piece of text into the run's output |
| Quick Replies | Data | Emits a message together with up to 10 tappable choices (quick_replies); each gate channel renders them natively and the tapped title comes back as the next message. Each choice is {"title": "..."} (optional id and payload, title up to 24 characters); a plain string is taken as the title. Options from (options_from) names a list built earlier in the flow (strings or {title, id, payload} objects) whose items are added after the written choices, up to 10 in all, so choices can be dynamic. In the Web Widget the tapped choice's id and payload also reach the flow as input.reply.id / input.reply.payload; they come from the visitor's browser, so treat them as untrusted |
| Cards | Data | Emits an optional message together with up to 10 cards (cards): title, subtitle, https picture, badge, price, status (with a tone), position number, up to 4 tags and up to 4 actions each. Layout carousel scrolls them sideways (default list), Image ratio is 1:1, 4:3 or 16:9. An action is reply (sends its title back, like a quick reply), link (opens an https page) or host (hands {id, payload} to the page that embeds the Web Widget). Cards can be written in the step or built from a list earlier in the flow (cards_from). The Web Widget renders them; other channels show the message only |
| Event | Data | Sends a named, data-only event (ui_event) to the page that embeds the Web Widget, which receives it through UoWidget.on(name, fn); the visitor sees nothing. The name is lower-case letters, digits, _, . or - (not open, close, ready, action, outgoing or incoming, which the widget uses itself); data is at most 8,000 characters. Other channels ignore it |
| Voice Settings | Voice | Changes how the assistant sounds and listens for the rest of a voice call: voice, language, speed, speech-to-text and text-to-speech providers, whether the caller may interrupt, silence handling and markdown cleanup. A setting left empty is inherited from the gate; the latest value wins. Voice channels only (voice gates, the Web Widget's voice mode, phone gates, the Flow Builder's voice test); other channels ignore it |
| Play Audio | Voice | Plays an audio file (mp3, wav or ogg) from an https URL you host: a jingle, a legal notice, hold music. Fetched from public hosts only, with size and length limits. Turn off Interruptible to make the caller listen to the end. Voice channels only |
| Hang Up | Voice | Ends the call once everything the flow said this turn has been spoken. Voice channels only |
| Collect Digits | Voice | Phone gates only: after what the flow said, the call listens for key presses instead of speech until Max digits were pressed, # was pressed (when enabled) or the caller waited longer than the timeout between presses. The digits reach the flow as the message of the next turn, whose channel.event is dtmf; no key at all is a no_input event. Other channels ignore it (the message is still said) |
| Transfer Call | Voice | Phone gates only: after what the flow said, the caller is connected to another number. Only numbers starting with one of the gate's Allowed transfer prefixes are accepted (empty = transfers are off; the flow cannot override this), and if nobody answers the caller stays with the assistant. Context travels in the X-UO-Context SIP header and is visible to the carrier and the receiving party. Other channels ignore it (the message is still said) |
| MCP Tool | Integration | Calls a tool exposed by a connected MCP server. If the tool reports a failure (unknown tool, rejected arguments) or cannot be called, the step fails with the reason — or takes its error route — instead of passing the input on as if the tool had answered |
| HTTP Request | Integration | Calls an external HTTP endpoint. {{key}} placeholders in the URL are percent-encoded when inserted, so a value can never add query parameters or change the path. A JSON or text body keeps its shape; a binary body (an image, a download) is returned as base64, flagged by http_response_encoding (json, text or base64). Query parameters and headers are tables (names and values both take {{key}}); the body type is JSON, plain text, URL-encoded form, multipart form or binary (base64 from the flow). Authentication: none, Bearer, API key (header or query), Basic or OAuth 2.0 client credentials (the token is fetched and cached for you). Secret fields are masked and never shown again. A timeout (1–300 s, default 30) and a 20 MB response cap apply. Asynchronous starts the request and lets the flow carry on; it is awaited only when a later step reads its result. Save as keeps the result as input.<name>.status/response/headers/encoding. |
| Code | Logic | Runs a sandboxed UO Script snippet against the run's data. It is modern JavaScript (ES2023): const, arrow functions and template literals work. The script reads and writes input and session_storage directly (input.total = 5;); whatever it changed becomes the step's output, and a key it deletes is cleared. A syntax error is shown as you type and refuses the flow when it is saved. Limits: 2 seconds of run time and about 1 MB of data read and returned; no access to files, the network or the server's environment. input and session_storage must stay objects — assign keys to them |
| Condition | Control | If/else branching (true/false handles), evaluated in a restricted, sandboxed manner. The only step type allowed to sit on a cycle — build iteration by routing a false branch back to an earlier step |
| Once | Control | Splits on whether this is the session's first run (first_run/already_ran handles). Runs of one session are serialized, so several simultaneous requests of a new session give first_run to exactly one of them |
| Switch | Control | Multi-way branch. Up to 8 cases, each a JavaScript expression (like Condition) with a name; they are checked from top to bottom and the first true one wins, anything else takes Else. Every case has its own output on the canvas; a configured case must be wired, like both Condition outputs |
| Sleep | Control | Pauses the run for a wait given as a number and a unit (milliseconds, seconds or minutes), up to one hour. The number may be a value from the flow, such as {{retry_after}}; a plain number is checked when the step is saved, a value from the flow when it runs |
| Trigger Flow | Control | Runs another flow of the same project as a sub-flow and returns its result. The sub-flow always receives the parent's whole input. Its session_storage is its own and is remembered for the rest of the session, so calling the sub-flow again continues where it left off — a Once step inside it fires only once. Share session storage also lends it the parent's session_storage and takes its writes back |
| Input | Control | Flow entry point. Nothing to configure: the user's message is available to every step as input.message ({{message}} in a template) |
| Output | Control | Flow exit point and result formatting. output_key names the value of this turn's data to show — content by default, or any key or path an earlier step wrote, such as severity.content — and the format template reads it as {{output}}. Text from a step whose Show in answer (emit_to_output) switch is off is never used as the answer, in streaming and non-streaming runs alike |
Names, time limits and errors
Every step has a Name field: it replaces the default title on the canvas, in the "On error, go to" picker and in the run trace (the step's id stays in the trace as a tooltip). Agent, LLM, RAG Retrieval, MCP Tool and Trigger Flow have a Timeout (seconds): 0 (default) means no limit; past the limit the step fails with "did not finish within Ns" and the run fails or takes the step's error route. HTTP Request has its own timeout (default 30 s).
Passing data between steps
Every run carries one shared data envelope with two scopes:
| Scope | Lives | Use it for |
|---|---|---|
input | one turn | the user's message (input.message) and every step's output of this run |
session_storage | the whole session | values a later turn of the same session should still see |
The steps that answer — Agent, LLM, Text Output, Quick Replies, Cards and the End step — all write the
answer the same way: input.content (the text) and input.reasoning (the model's reasoning, empty
when there is none). A later answering step overwrites them, so a step whose answer must stay readable
after that has a Save as field: with severity entered, its answer is also kept as
input.severity.content and input.severity.reasoning. Steps that are not answers keep their own
descriptive keys (http_response, retrieved_docs, tool_result, …).
Code and Condition scripts read and write the scopes directly; templates ({{ }}) use the same paths.
A path may go deeper — {{input.http_response.items[0].id}} — and a bare key means input:
session_storage.employee_id = input.message;
input.first_item = input.http_response.items[0].id;Where you write the reference decides its form:
| Field | Write | Example |
|---|---|---|
| Template fields (Agent input, LLM prompt, Text Output, HTTP URL and body, Catch Up answer, …) | the bare key in {{ }}; {{input.message}} means the same | {{message}}, {{content}}, {{http_response}} |
| Template, a value from the session | the session_storage. prefix is required | {{session_storage.employee_id}} |
| Code, Condition and Switch scripts | the scope object, no braces | input.message, session_storage.employee_id |
| MCP Tool argument mapping | a bare key or a {{ }} template | order_id_from_msg |
Values that start with _ belong to the engine and are never visible to scripts or templates. Every
field that accepts {{ }} offers autocomplete, including the nested paths of the last test run. The live
contents of both scopes after each step are visible in the Data tab of the flow test panel (a tree
whose rows copy their path, their {{ }} form or their value), streamed on every flow_step event.
Error fallback routing
Any non-structural step can declare an On error, go to target. If that step
raises, the run routes to the target instead of failing; steps without a target
keep the default behavior of aborting the whole run. The fallback is drawn as a
dashed red on error edge. It doesn't count as a normal outgoing connection
during validation, so a step reachable only through an error branch is still
reported as a dead end.
Every kind of step failure takes the fallback the same way: a script error (the
message carries no engine stack trace), a model call that fails or returns
nothing, a missing provider/agent/knowledge base, and a Trigger Flow step
whose sub-flow failed (the parent step fails with the sub-flow's reason instead
of reporting completed). The failing step also appears in the run's step trace
with its error_message.
Step settings are checked when you save
A value that was entered but is not allowed — a sleep of 0 ms or more than an
hour, top_k of 0, max_tokens above 32 768, an unknown option, a tool name
with a space, a tool schema that is not valid JSON Schema — is rejected on save
and on dry_run with an error that names the step and the field. A step that
simply has not been filled in yet is only a warning, so a freshly dropped step
is not lost, but the flow cannot run until it is completed. In the step's side
panel the same rules show as a message under the field, and Apply changes
stays disabled until they are fixed.
Resources, readiness and run limits
A flow can only use resources of its own project: an agent, knowledge base,
MCP server or sub-flow from another project is treated as not found, and so is a
model provider that belongs neither to the project nor to its organization. The
same check runs when you save the flow, on a dry_run, and before a run starts —
a flow whose steps are unconfigured or point at something missing is refused with
a 422 that names the step, instead of running. A step that still meets a missing
resource while running fails with a clear message (or takes its error route);
it never returns an empty result in its place.
Runs are bounded: a model may take at most 10 rounds of tool calls per Agent/LLM step, and a run stops after 250 steps in total, so a loop that never ends cannot keep spending tokens.
Versioning & execution
Every flow keeps a bounded version history (the last 10 versions). Edits made within five minutes by the same author are merged into one version; a version is sealed when someone else edits, when a version is restored, when a version is saved explicitly, and before a flow runs through the Consumer API or a share link. History in the builder lists the versions, and restoring one never loses anything: it creates a new version with the restored content.
History starts with the first change: a flow nobody has edited yet shows an empty history, and the first edit (or Save version) records the state it had before as the initial System version. Each entry shows who made it — Editor, Assistant, MCP, API or System — and when, and the newest is marked Current. A version that was itself created by a restore cannot be restored again; restore the version it came from instead.
Each flow also carries a revision counter. Writers that pass
expected_revision (the builder always does) get a 409 revision_conflict
instead of silently overwriting a newer edit; the builder offers to reload.
An open builder also follows changes made elsewhere — the
AI assistant, an MCP client or another tab — and
reloads the canvas by itself when you have no unsaved edits; with unsaved
edits it keeps them and shows the conflict dialog on save.
Executions can run a saved version with the version parameter, otherwise
they run the current one. Executing a flow runs the full workflow with the
same streaming and checkpointing infrastructure used for single-agent
execution.
Editing a flow programmatically
Besides replacing the whole graph, the Consumer API and the MCP endpoint
edit a flow with small operations (add_node, remove_node,
set_node_config, connect, disconnect). A batch is atomic: one invalid
operation rejects everything and nothing is saved, and the result goes
through the same graph validation as any other save. dry_run validates
without saving, and also reports referenced agents, providers, knowledge bases,
MCP servers and sub-flows that do not exist in the project. Reading a flow through
the API lists its non-blocking issues as validation_warnings. Operations are never
auto-corrected.
remove_node takes cascade: true to remove, as deleting does on the canvas,
everything only its target reaches: for a Tool, its whole branch down to its Catch Up.
Something another path still reaches stays, and Start and End are never removed.
Without cascade only the removed item and its own edges go. The rules around tools hold
on every surface: only an LLM or Agent may reach a Tool (with a tool_call edge), and a
Catch Up is only valid inside a tool's branch. On the canvas a tool pastes only onto the
side + of an Agent or LLM, a Catch Up only inside a tool's branch, and cutting a tool
moves its whole branch.
Secrets such as an HTTP step's token are never readable. Copying a step on the canvas keeps
them. Through the API, give add_node a copy_secrets_from (the id of an existing step) and
the new step takes that step's stored secrets while its own are left blank.
Share links and background tasks
A flow's share link takes an optional password, expiry date and use limit. The
expiry must be in the future (422 otherwise). A visitor sends the password in the
JSON body of the execute request ({"input": {...}, "password": "..."}); there is no
password header, and a wrong or missing password answers 403.
A background task (POST /v1/flows/{flow_id}/tasks on the Consumer API) needs
something to work on: a non-empty input or at least one attachment_ids entry
(422 otherwise).