Nodes

The three node types in an Asteroid workflow: start, workflow, and output.

A node is one step of a workflow. Three node types exist.

Node	What it does	API, SDK and MCP type	settings.yaml type
Start	Marks where an execution begins.	start	start
Agent	Reads instructions and acts in the environment.	iris	agent
Output	Ends the execution and returns an outcome label and a result.	output	output

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

Nodes are joined by transitions.

---

Start node

Every graph has exactly one start node. The builder seeds it when you create a workflow.

A start node makes no decision. It holds one outgoing transition, and that transition must point at a node that is not an output node. An execution always begins here.

---

Agent node

An agent node is where the work happens. You write instructions in plain language. The model carries them out in a real browser or on a real desktop.

Navigate

Move to and through pages

Fill forms

Enter and submit structured data

Use files

Read, upload, or download files

Extract data

Pull values off a page

Instructions

The instruction block is the core of an agent node. Four parts make it reliable:

Part	What to write
Goal	What this node accomplishes.
Ordered steps	The actions, in sequence.
Edge cases	Variations the workflow will meet.
Success criteria	What the workflow can observe when the step is done.

Your goal is to submit the consultation form for the current patient:
1. Click "New Consultation"
2. Fill the form fields with the provided data
3. Upload any provided attachments
4. Click "Create"

Edge cases:
- If a modal appears, close it before continuing
- If the page asks for confirmation, accept it

Success criteria:
Once you see the "Consultation Submitted" banner, the task is complete.

Write good instructions

Patterns that hold up across runs

Variables in instructions

Write {{.name}} in a node’s instructions to drop a value in at run time.

Navigate to the patient search page:
1. Enter {{.patient_name}} into the search bar
2. Select the matching result
3. Fill {{.diagnosis}}
4. Click Submit

A variable name must start with a letter or an underscore. After that it may hold letters, digits, and underscores only.

• Valid: {{.user_name}}, {{.email}}, {{.api_key}}
• Invalid: {{.user-name}}, {{.my@var}}, {{.1st_item}}

Reach into nested JSON with a dot path:

User: {{.user.name}} ({{.user.email}})

{
  "inputs": {
    "user": { "name": "Jane Smith", "email": "[e-mail]" }
  }
}

The values come from the inputs your code sends on the execute call.

Model

Each node picks its own model. Match the model to the difficulty of that step.

Model	Pick it for
asteroid-fast	Simple, fast interactions. Lowest latency.
asteroid-balanced	The default. Balanced speed and accuracy.
asteroid-max	Complex flows that need deep reasoning.

Capabilities

Every agent node declares three switches: browser_use, computer_use, and ask_user_question. They decide which tools the node gets. The environment can override two of them.

What a node can do

The three switches and how the environment gates them

Script

By default an agent node works turn by turn: the model reads the page, picks a tool, and acts. Set the node’s Script field to run a stored Playwright script first instead.

Set script_filepath to a relative .js path and the node becomes a scripted node. Clear the field and it goes back to working turn by turn.

Scripts live in the workflow’s shared/ tree. The runtime resolves the path inside the node’s own shared/ directory:

shared/<node-slug>/<script_filepath>

• The runtime derives <node-slug> from the node’s display name. It lowercases the name and strips punctuation. You never write the slug, so renaming a node never breaks the path.
• You author script_filepath itself. It is stored with a ./ prefix, as in ./scripts/find_patient.js.
• Name the file after the action, in lower_snake_case. The directory already says which node it belongs to. Avoid scripts/main.js and scripts/index.js.

A node named “Find Patient” with script_filepath: ./scripts/find_patient.js resolves to /home/agent/shared/find_patient/scripts/find_patient.js.

Workflow filesystem

Where a script file lives, and what each directory is for

Behavior, inputs, and routing

How a scripted node behaves lives in one place, so it stays in step: reading args and credential tokens, what a return value or a returned asteroid.handoff(...) does, the order the runtime picks the next node, and pinning inputs with x-source.

Script a step

Attach a script, route from it, and pass and pin its inputs

Script runtime

The runtime contract: timeouts, the sandbox, the filesystem, and credentials

script_failure_action decides what happens when a script throws. fallback_to_ai (the default) hands the failure to the model, which recovers from the instructions. cancel_execution stops the run at once with reason script_failed, which also fires when the script file is missing.

Ask Astro which steps are worth scripting. It writes and tests the scripts for you.

How an agent node ends

An agent node ends when one of its outgoing transitions fires. It never ends on its own.

Give every agent node a failure path.

Connect at least one transition from every agent node to an output node that handles failure.

Without it, a missing element or an unexpected page has nowhere to go. The execution then cannot report what went wrong.

Agent node reference

In a workflow’s settings.yaml, an agent node is type: agent. Every agent node declares type, capabilities, and model.

Field	Value
capabilities	Required. The browser_use, computer_use, and ask_user_question booleans.
model	Required. One of asteroid-fast, asteroid-balanced, or asteroid-max.
script_filepath	Optional. A relative .js path inside the node’s own shared directory.
script_failure_action	Optional. fallback_to_ai (the default) or cancel_execution. Only read alongside script_filepath.

label: "Submit Form"
type: agent
capabilities:
  browser_use: true
  computer_use: false
  ask_user_question: true
model: asteroid-balanced
transitions:
  - to: success_output
    type: ai
  - to: failure_output
    type: ai
  - to: confirmation_page
    type: selector
    name: "Confirmation Visible"
    selectors:
      - ".confirmation-banner"

A scripted node that falls back to the workflow:

label: "Find Patient"
type: agent
capabilities:
  browser_use: true
  computer_use: false
  ask_user_question: true
model: asteroid-balanced
script_filepath: ./scripts/find_patient.js
transitions:
  - to: patient_found
    type: ai
  - to: not_found
    type: ai

A scripted node that cancels the execution when the script fails:

label: "Login"
type: agent
capabilities:
  browser_use: true
  computer_use: false
  ask_user_question: true
model: asteroid-balanced
script_filepath: ./scripts/login.js
script_failure_action: cancel_execution
transitions:
  - to: dashboard
    type: ai

The node’s instructions live in an instructions.md file in the same directory.

---

Output node

An output node ends the execution. It closes the environment, sets the outcome label, and returns the structured result to your code.

Every graph needs at least one output node. Most graphs have several: one per way the execution can finish.

Outcome labels

An outcome label answers one question: how did this execution finish? It is the value your code branches on.

An output node lists the labels it can produce.

label: "Result"
type: output
outcomes:
  - success
  - failure

Labels are lowercase, and each node holds between 1 and 20 of them. The full rules are on the page below.

Result schema

An output node can also return structured data. You define the shape as a JSON Schema, and the workflow fills it in. Your code reads it at executionResult.result.

The schema lives in an output-schema.json file next to the node’s settings.yaml.

Inputs and outputs

Label rules, schema rules, and the exact response your code receives

---

Related

Workflows are graphs

How nodes fit together into a whole workflow

Transitions

The edges that join nodes

Build in the platform

Add and configure nodes in the visual builder

Environments

Where a node’s work actually runs