> ## 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

> How workflows decide what happens next

Transitions define **how your workflow moves from one node to the next**.
They represent the routing logic of your automation and determine which path the agent follows under different conditions.

Asteroid provides **two types of transitions**, each designed for a different kind of decision-making.

<Card title="AI Transition" icon="brain" horizontal>
  Chosen by AI based on the agent’s analysis of the page and task context
</Card>

<Card title="Selector Transition" icon="code" horizontal>
  Jumps to the next node the moment a specific element appears
</Card>

***

## API / YAML Reference

When configuring transitions via the API, SDK, or MCP, use the following type identifiers:

| Transition          | YAML `type` value | Used with   |
| ------------------- | ----------------- | ----------- |
| AI Transition       | `ai`              | Agent nodes |
| Selector Transition | `selector`        | Agent nodes |

***

## Types of Transitions

### AI Transitions

AI Transitions are the most flexible and expressive transition type.
They allow **Agent nodes** to choose the next step based on reasoning, context, and analysis of the current browser state.

**When to use:**

* When the next step depends on **page content** or **semantic understanding**
* When multiple paths are possible and the AI must **choose intelligently**
* For workflows requiring reasoning, interpretation, or decisions based on extracted information

**Example:**

```mermaid theme={null}
flowchart TB
    A[Agent node] -->|AI Transition| B[Next node]
    A[Agent node] -->|AI Transition| C[Failure node]
```

**YAML example:**

```yaml theme={null}
transitions:
  - to: next_node
    type: ai
  - to: failure_output
    type: ai
```

### Selector Transitions

Selector Transitions are **deterministic**.
They activate **immediately when a specific selector becomes visible or present** on the page.

**When to use:**

* When waiting for a **specific UI element** to appear
* As a **guardrail** for navigation changes or modal detection
* For flows that require deterministic, event-driven branching

**Use carefully:**
Selector transitions should be used **sparingly**, only when you are 100% certain about the structure and stability of the target element.

**Example selector:**

```
button:has-text("Submit")
```

**YAML example:**

```yaml theme={null}
transitions:
  - to: confirmation_page
    type: selector
    name: "Submit Button Visible"
    selectors:
      - 'button:has-text("Submit")'
```

#### Matching any of several selectors

`selectors` is a list, and it is evaluated as an **OR**: the transition fires as soon as **any** selector in the list matches the live page.
Use this when the same signal can render in more than one way — a confirmation banner that differs between locales, or a button whose markup changes between portal versions.

```yaml theme={null}
transitions:
  - to: confirmation_page
    type: selector
    name: "Order Confirmed"
    selectors:
      - "text=Order confirmed"
      - "text=Bestellung bestätigt"
      - "[data-testid='confirmation-banner']"
```

<Warning>
  **One transition per target.** A node may have at most **one selector transition** to a given target node — alternative selectors for the same edge belong in that transition's `selectors` array, not in a second edge.
  The same rule applies to AI transitions: at most **one `ai` transition** per target.
</Warning>

***

## Passing Data Across a Transition

Transitions don't just decide *where* the workflow goes — they decide **what travels with it**.
Each outgoing transition can carry its own **output schema**, so a node hands off exactly the data the next node needs, in a shape you define.

Output schemas are defined **per outgoing transition**, not on the node itself. A node that can branch three ways can hand off three different shapes.

### How it works

1. You attach a JSON Schema to a transition.
2. When the agent decides to take that edge, it calls a handoff tool and fills in a payload matching the schema. An AI transition's tool is named **`to_<target>`**; a selector transition's is **`to_<target>_via_selector`**.
3. The receiving node reads that payload in its instructions via the **`{{.output}}`** variable.

```mermaid theme={null}
flowchart LR
    A[Agent node<br/>Look up patient] -->|to_file_claim<br/>patient_id, plan_name| B[Agent node<br/>File claim]
    A -->|to_not_found| C[Output node<br/>patient_not_found]
```

### Example

An agent node that looks up a patient 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 gets the handed-off payload as the `output` variable, holding the JSON the previous node produced. Reference it in that node's instructions with `{{.output}}`:

```
The patient you are filing a claim for:
{{.output}}

Open their claims form and submit it.
```

***

## Requiring Confirmation

Any transition can be gated on a human's approval by setting `require_confirmation`:

```yaml theme={null}
transitions:
  - to: submit_payment
    type: ai
    require_confirmation: true
```

When the agent tries to cross this edge, the execution pauses and moves to the **Awaiting Confirmation** status instead of continuing. It resumes once a user confirms — or ends there if the run is canceled or times out while waiting.

Use it in front of consequential, hard-to-undo steps — submitting a payment, filing a claim, sending an irreversible form.

***

## Best Practices

### Choosing the Right Transition

Use the appropriate transition type for each decision point:

* **AI Transitions:**
  For dynamic routing based on page content, extracted information, or reasoning.

* **Selector Transitions:**
  For immediate, deterministic reactions to UI events.
  *Use cautiously, only when element type, structure, and behavior are known and stable.*

### Failure Transitions

<Warning>
  **Critical: Agent Node Failure Paths**

  **All Agent nodes must have a connection to an Output node via a failure path.** This is essential for proper error handling and workflow completion.

  * Every Agent node should have at least one transition (typically an AI Transition) that connects to an Output node configured for failure scenarios
  * Without a failure path, your workflow may not properly handle errors, unexpected conditions, or edge cases
  * This ensures that unexpected conditions, missing elements, or interpretation errors are surfaced correctly in your workflow
</Warning>