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.

AI Transition

Chosen by AI based on the agent’s analysis of the page and task context

Selector Transition

Jumps to the next node the moment a specific element appears

---

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:

YAML example:

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:

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.

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

---

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.

Example

An agent node that looks up a patient hands the identifiers it found to the next node:

{
  "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:

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

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