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

<Card title="Outcome Success" icon="check" horizontal>
  Used by nodes that deterministically signal successful completion
</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`              | AI Task nodes       |
| Selector Transition | `selector`        | AI Task nodes       |
| Outcome Success     | `outcome_success` | Deterministic nodes |

***

## Types of Transitions

### AI Transitions

AI Transitions are the most flexible and expressive transition type.
They allow **AI 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[AI Task node] -->|AI Transition| B[Next node]
    A[AI Task 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"
    selector: "button:has-text('Submit')"
```

### Outcome Success Transitions

Outcome Success transitions are used after **deterministic nodes** that explicitly return either a success or failure.

**When to use:**

* Any deterministic node that returns a clear "success" state

**YAML example:**

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

***

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

* **Outcome Success Transitions:**
  For deterministic steps with clearly defined success states.

### Failure Transitions

<Warning>
  **Critical: AI Task Node Failure Paths**

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

  * Every AI Task 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>