Skip to main content
A transition is an edge between two nodes. It decides where an execution goes next, and it decides what data goes with it. An agent node ends when one of its outgoing transitions fires. Draw one transition for every way the step can finish.

​
The two transitions you author

AI transition

The workflow reads the page and the task, then chooses this edge.

Selector transition

The execution takes this edge the moment a selector matches the live page.

​
AI transitions

An AI transition lets the workflow decide. It weighs the page state and the task context, then picks an edge. Reach for an AI transition when:
  • The next step depends on page content or on meaning.
  • Several paths are possible and something must choose between them.
  • The choice needs reasoning over information the workflow extracted a moment earlier.
Most edges in a healthy graph are AI transitions.

​
Selector transitions

A selector transition is deterministic. It fires the moment a selector matches the live page, and it skips the model. Reach for a selector transition when:
  • You wait for one specific element to appear.
  • You need a guardrail for a navigation change or a modal.
  • The branch must be event-driven and exact.
Use selector transitions sparingly. They break when the target markup changes. Add one only when you are certain the element’s structure and behaviour are stable.

​
Matching any of several selectors

selectors is a list, and it is an OR. The transition fires as soon as any selector in the list matches. Use it when one signal renders in more than one way, such as a banner that changes with locale.

​
One transition per target

A node may have at most one AI transition to a given target node. It may have at most one selector transition to that same target.Alternative selectors for the same edge belong in that transition’s selectors list. They do not belong in a second edge.

​
The fixed transition

Some nodes make no routing decision. The node completes, and the execution follows its single edge. That edge has type outcome_success. Validation enforces these rules:
  • The start node has exactly one outgoing transition. It must be type outcome_success.
  • The start node’s transition must point at a node that is not an output node.
  • An agent node may not use outcome_success. It routes with an AI or a selector transition.
  • A node may hold at most one outcome_success transition.

​
Type identifiers

When you call the API, the SDK, or the MCP tools, send the value in the middle column. In a workflow’s settings.yaml, write the value in the right column.

​
Passing data across a transition

A transition carries data as well as control. Attach a JSON Schema to an outgoing transition, and the node hands the next node exactly that shape. Schemas belong to the transition, not to the node. A node that branches three ways can hand off three different shapes.
1

Attach a schema to the transition

Define the fields the receiving node needs, and describe each one.
2

The workflow fills the payload

As it takes the edge, the workflow calls a handoff tool and fills in a payload that matches the schema. An AI transition’s tool is to_<target>. A selector transition’s tool is to_<target>_via_selector.
3

The receiving node reads it

The payload arrives as the output variable. Reference it in that node’s instructions with {{.output}}.
A patient lookup node hands the identifiers it found to the next node:
The receiving node reads it:
A transition schema shapes the payload for the next node. It is never the execution’s final result.The final result comes from the output node’s own result schema, and your code reads it at executionResult.result. See Inputs and outputs.

​
Requiring confirmation

Gate any transition on a person’s approval with require_confirmation.
When the workflow tries to cross this edge, the execution pauses and moves to awaiting_confirmation. It continues once a person confirms. It ends there if the execution is cancelled or times out while it waits. Put a confirmation in front of steps that are hard to undo: submitting a payment, filing a claim, sending an irreversible form.

Executions and statuses

What awaiting_confirmation means and how an execution leaves it

​
Failure paths

Every agent node needs a transition to an output node that handles failure.Give each agent node at least one edge into an output node built for the bad case. An AI transition is the usual choice.An execution that meets a missing element then ends on a label you chose, instead of stalling.

Workflows are graphs

How nodes and transitions form one workflow

Nodes

The three node types and what each holds

Inputs and outputs

Outcome labels and the result your code reads

Build in the platform

Draw transitions in the visual builder