Skip to main content

Workflow Builder

The Workflow Builder is the visual canvas inside the task editor. It lets you design a task's execution flow as a diagram — drag nodes onto the canvas, connect them with edges, and configure each node — without writing code.

The builder is part of the task editor. For the full task lifecycle (creating tasks, the task list, running tasks, and execution history), see Task Management.

Opening the Builder​

Open the task editor by clicking Configure on a task in the task list, or by creating a new task. The editor opens at /tasks/edit/:taskId with the canvas in the center.

The editor has a canvas in the middle, a node library on the left, a configuration panel on the right, and a debug panel along the bottom. These are described in detail in Task Management → Task Editor.

The Canvas​

The canvas is where you assemble the flow:

  • Drag and drop — drag nodes from the left node library onto the canvas.
  • Connections (edges) — drag from one node's output port to another node's input port to create an edge. Connections are validated for type compatibility.
  • Zoom and pan — zoom and drag to navigate large flows.
  • Empty-canvas prompt — a guide button appears when the canvas is blank, to help you add your first step.

Node Types​

You build a workflow from these node types:

Node TypeWhat it does
AgentInvokes an AI agent to handle tasks that need judgment or generation
OperatorPerforms a specific task — call an API, transform data, send a notification, run custom code, and more (see Operator Nodes)
ControlControls the execution path — branching and iteration
DatasetQueries or modifies a dataset
Data SourceConnects to and reads from a data source

You add nodes from the node library, which is grouped into AI Agents, Tools (operators), Datasets, Data Sources, and Control Flow.

Control Flow​

Two control nodes are available as draggable nodes from the Control Flow category:

  • If-Else — routes execution down a true or false branch based on a condition. See If-Else Condition Node.
  • ForEach — iterates over a list, running a sub-flow for each item. See ForEach Loop Node.
note

The engine also supports a Switch (multi-branch) control node, but it is not offered as a draggable node in the console builder — only If-Else and ForEach appear in the palette. See Switch Branch Node for details.

Connecting Data Between Nodes​

Nodes pass data along edges. An edge connects a source port to a target port using the form nodeId:portName, and can optionally select part of the source output with a dataPath. For the exact edge format and examples, see Operator Nodes → How Data Flows Between Nodes.

Node inputs and edge values support the {{VARIABLE_NAME}} environment-variable template syntax — see Environment Variables.

Error Handling and Retries​

Error handling is configured at the task level (in the task's advanced configuration), not as a separate node. The available settings are:

SettingDescription
Max RetriesHow many times to retry a failed run (0–10)
Retry IntervalWait time between retries, in milliseconds (minimum 1000)
Retry Strategyfixed (constant interval) or exponential (back-off)
Failure ActionWhat to do on failure: retry, notify, or stop
Enable NotificationWhether to send a notification on failure

You set these when creating or editing a task. See Task Management → Advanced Configuration.

To branch on errors within a flow, combine an operator's output with an If-Else control node.

Building a Workflow: Typical Steps​

  1. Open the task editor (Configure a task, or create a new one).
  2. Open the node library (Ctrl + K) and drag your first node onto the canvas.
  3. Add the operator, agent, dataset, and data-source nodes your flow needs.
  4. Connect nodes with edges, selecting fields with dataPath where needed.
  5. Add If-Else / ForEach control nodes for branching and iteration.
  6. Configure each node in the right panel (Ctrl + I), and set task-level retry/failure handling under Configure.
  7. Save Changes, then Run Now and watch the live logs in the bottom debug panel.

FAQ​

Details

Does the builder support conditional branching and loops? Yes. Add an If-Else node to branch on a condition, and a ForEach node to iterate over a list. Both are available from the Control Flow category. (A Switch node exists in the engine but is not in the builder palette.)

Details

How do I debug a workflow? Run the task with Run Now and watch the bottom debug panel: it streams the run logs in real time and highlights the currently executing node on the canvas. You can also review past runs in the Execution History tab. See Task Management.

Details

Where do I configure retries and failure handling? At the task level, under the task's advanced configuration. Use Configure in the editor (or the create-task dialog) to set max retries, retry interval, retry strategy, and the failure action. See Task Management.

Next Steps​