> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Transitions
> The edges of a workflow graph: how an execution decides which node comes next, and what data travels with it.
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](/concepts/nodes) ends when one of its outgoing transitions fires. Draw one transition for every way the step can finish.
***
## The two transitions you author
The workflow reads the page and the task, then chooses this edge.
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.
```yaml theme={null}
transitions:
- to: next_node
type: ai
- to: failure_output
type: ai
```
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.
```yaml theme={null}
transitions:
- to: confirmation_page
type: selector
name: "Submit Button Visible"
selectors:
- 'button:has-text("Submit")'
```
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.
```yaml theme={null}
transitions:
- to: confirmation_page
type: selector
name: "Order Confirmed"
selectors:
- "text=Order confirmed"
- "text=Bestellung bestÃĪtigt"
- "[data-testid='confirmation-banner']"
```
***
## 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
| Transition | API, SDK, and MCP `type` | `settings.yaml` `type` |
| ---------- | ------------------------ | ---------------------- |
| AI | `iris` | `ai` |
| Selector | `selector` | `selector` |
| Fixed | `outcome_success` | `outcome_success` |
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.
Define the fields the receiving node needs, and describe each one.
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_`. A selector transition's tool is `to__via_selector`.
The payload arrives as the `output` variable. Reference it in that node's instructions with `{{.output}}`.
```mermaid theme={null}
flowchart LR
A[Agent node
Look up patient] -->|to_file_claim
patient_id, plan_name| B[Agent node
File claim]
A -->|to_not_found| C[Output node
patient_not_found]
```
A patient lookup node hands the identifiers it found to the next node:
```json theme={null}
{
"type": "object",
"properties": {
"patient_id": {
"type": "string",
"description": "The patient's MRN as shown in the EHR"
},
"plan_name": {
"type": "string",
"description": "The insurance plan on file"
}
},
"additionalProperties": false,
"required": ["patient_id", "plan_name"]
}
```
The receiving node reads it:
```text theme={null}
The patient you are filing a claim for:
{{.output}}
Open their claims form and submit 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](/concepts/inputs-and-outputs).
***
## Requiring confirmation
Gate any transition on a person's approval with `require_confirmation`.
```yaml theme={null}
transitions:
- to: submit_payment
type: ai
require_confirmation: true
```
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.
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.
***
## Related
How nodes and transitions form one workflow
The three node types and what each holds
Outcome labels and the result your code reads
Draw transitions in the visual builder