AI Task Node

Instruct an LLM to interact with a webpage

The AI Task node uses natural language instructions to perform actions inside a real browser. It is the most flexible node type and is ideal for handling dynamic UI, multi-step interactions, and workflows that benefit from LLM reasoning.

Common actions include:

Navigate

Navigate to and through pages

Fill forms

Enter and submit structured data

Use files

Read, upload, or download files

Extract data

Scrape data from a webpage

---

Configuration

Instructions

The core of an AI Task node is a natural language instruction block. You describe what the agent should do, and the LLM executes those steps in the browser.

Recommended Structure

To achieve the most reliable behavior, structure your instructions with:

• Goal: What the node is trying to accomplish
• Ordered steps: A sequence of specific actions
• Edge cases: Known variations the agent must handle
• Success criteria: Observable conditions indicating completion

Example:

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.

Dynamic Variables

Dynamic variables make your instructions reusable across multiple runs with different inputs. Variables are passed at execution time and referenced with the {{.var_name}} syntax.

Example:

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

Naming Rules

Variable names must:

• Start with a letter or underscore
• Contain only letters, numbers, and underscores
• Not include special characters such as @, -, ., or spaces

Valid: {{.user_name}}, {{.email}}, {{.api_key}}

Invalid: {{.user-name}}, {{.my@var}}, {{.1st_item}}

Advanced Templating

AI Task instructions support full Go Template syntax, enabling conditionals, loops, and structured data.

Advanced: Conditionals

Use if statements to conditionally adjust behavior:

{{if .is_premium}}
Navigate to the premium dashboard and enable all features.
{{else}}
Navigate to the free dashboard.
{{end}}

The corresponding variable values should be:

{"is_premium": true}

Advanced: Loops

Iterate through lists or arrays.

Simple array:

Fill the form with the following items:
{{range .items}}
- Enter "{{.}}" in the next field
{{end}}

Array of objects:

Add products to the cart:
{{range .products}}
- {{.name}}: {{.price}}
{{end}}

The corresponding variable values should be:

["Item 1", "Item 2", "Item 3"]

Via SDK, you’d pass:

{
  "inputs": {
    "products": [
      {"name": "Widget A", "price": "$10"},
      {"name": "Widget B", "price": "$20"}
    ]
  }
}

Inside a range, {{.}} refers to the current item. For objects, use fields like {{.name}} and {{.price}}.

Advanced: Nested Data

Access nested JSON structures:

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

{{if .user.verified}}
Proceed to checkout.
{{else}}
Please verify your email before continuing.
{{end}}

The corresponding variable values should be:

{"name": "Jane Smith", "email": "[e-mail]", "verified": true}

Model Selection

Choose the model that best fits the complexity of the task:

Asteroid Fast

Lowest latency. Best for simple, fast interactions.

Asteroid Balanced

Default model. Balanced speed and accuracy.

Asteroid Max

Highest intelligence and reasoning depth for complex flows.

Execution mode

Execution mode controls how much autonomy the AI has at each step. In default mode the model reasons and uses tools freely. In scripted mode the runtime runs stored automation first for speed and reliability, falling back to the AI only when the script fails.

Scripted mode pairs that determinism with self-healing: when a script breaks or the UI drifts, you can let the AI recover, escalate to a human, or stop the run, depending on how you configure failure handling below.

In the graph editor this appears as Execution mode. In API or YAML exports, set execution_mode to default or scripted on the AI Task node.

Default

Full autonomy with shared knowledge. The agent reasons and acts freely, with access to a persistent shared/ directory for saving and reusing knowledge across executions.

Agent filesystem

Read how shared/ keeps files across runs for the same agent

Scripted

Runs stored scripts before the LLM. Falls back to AI on failure, or cancels if freeze is enabled.

Use scripted mode when the UI path is stable and you want speed; stay on default while you are still exploring the flow.

If the script fails

When a stored script errors in scripted mode, the graph editor lets you choose how the run continues:

Fall back to AI

Let the AI agent recover and continue the task.

Cancel execution

Stop the execution immediately.

Ask the human

Pause and wait for a human to decide.

AI Capabilities

Enable specific capabilities depending on what the node needs to perform:

Web Browsing Essentials

Basic navigation, clicking, typing, and interaction

Advanced Web Browsing

Complex navigation, dynamic UIs, and robust action handling

Computer Vision

Visual understanding of the page and image-based interaction

Communication

Exchange messages and emails with the user during execution

File System

Upload, download, read, and write files

Memory & Storage

Store and retrieve data across execution steps

Google Sheets

Read from and write to Google Sheets

Authentication

Generate and manage authentication tokens

Context & Utilities

Access contextual data and system utilities

Explore all available features in AI Capabilities.

Critical: Basic Browser Interaction Tools Required

Always ensure Basic Web Interaction tools are enabled for AI Task nodes. This capability is enabled by default and provides essential tools for clicking, typing, selecting elements, and interacting with the DOM.

• Basic Web Interaction is required for AI Task nodes to function properly
• Disabling this capability will prevent the agent from performing basic browser interactions
• You should not disable this capability unless you have a very specific reason

For more details, see AI Capabilities.

---

Transitions and Failure Handling

Critical: AI Task Nodes Must Have 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

For more details, see Transitions and Output Nodes.

---

API / YAML Reference

When configuring an AI Task node via the API, SDK, or MCP, use the following type identifier:

Field	Value
Node type	ai
Transition types	ai, selector
Optional	execution_mode: default or scripted; freeze: cancel when the stored script is missing or fails (strict scripted path)

Example settings.yaml:

label: "Submit Form"
type: ai
execution_mode: default
tools:
  - go_to_url
  - dom_browser_interaction
model: "asteroid_balanced"
transitions:
  - to: success_output
    type: ai
  - to: failure_output
    type: ai
  - to: confirmation_page
    type: selector
    name: "Confirmation Visible"
    selector: ".confirmation-banner"

The node’s instructions are stored in a separate instructions.md file in the same directory.

---

Additional Settings

Batch Actions

Enable parallel steps for faster execution when the workflow allows it.

Snapshot Compression

Reduce context size by compressing browser snapshots captured during execution.

Scripted mode (scripts and placeholders)

In scripted execution mode, the runtime looks for a stored script on disk before involving the full LLM turn. API / YAML: execution_mode: scripted on the AI Task node.

Where scripts live

Scripts live under the agent’s persistent shared/ tree (see Agent filesystem):

• Default path: shared/<node-slug>/scripts/ with exactly one .js file for the fast path.
• If you pass a target_directory execution input, the path becomes shared/<node-slug>/<target_directory>/scripts/.

<node-slug> is derived from the node’s display name (lowercased, punctuation stripped). See Files for the full layout.

Placeholders and substitution

1. __PLACEHOLDER__ — Double underscores around a UPPER_SNAKE name in the saved script. Before the deterministic run, a lightweight model pass reads the script plus your instructions and fills these slots; values are substituted into the script text.
2. <<.var_name>> — Same family as Playwright script variables: declared fields the resolver replaces with concrete strings before execution.

Vault secrets use ##CREDENTIAL## (see Agent profiles); that system is separate from __PLACEHOLDER__ and <<.>> resolution.

Runtime behaviour

The stored script runs against the live browser session. Credentials referenced in the script are injected automatically at runtime; return values are captured as activities for transitions.

If the script succeeds and the node has a single unambiguous outbound transition, the runtime may advance without a full agent round-trip for that node. Otherwise the script outcome is passed to the model as context.

If no eligible script file exists while the node is configured to require one (strict / freeze in API exports), the execution cannot proceed.

Scripted mode is usually much faster than full default mode but expects stable UI. Use default mode while you are still discovering the flow; move to scripted mode when the path is repeatable.

For the dedicated Playwright node type (outcome-only transitions, YAML playwright_script), see Playwright node.