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

# Graph Agents

> Graph workflows, nodes, transitions, and context patterns on Asteroid

Asteroid implements browser automation as **graph workflows**: a simple but powerful way to break complex tasks into small, reliable components.
Instead of one large “do everything” agent, your automation is built from **nodes** (focused subtasks) linked by **transitions** (rules that determine what happens next).

This structure makes your agents:

<CardGroup cols={2}>
  <Card title="Reliable" icon="shield-check" horizontal>
    Each node handles a narrow responsibility, reducing ambiguity and improving success rates
  </Card>

  <Card title="Observable" icon="eye" horizontal>
    Every state, transition, and action is visible, making debugging and monitoring effortless
  </Card>

  <Card title="Composable" icon="puzzle-piece" horizontal>
    Mix AI actions, scripts, and outputs seamlessly
  </Card>

  <Card title="In Control" icon="sliders" horizontal>
    Assign different models, permissions, and capabilities to each part of your workflow
  </Card>
</CardGroup>

***

## Nodes & Transitions

Asteroid workflows are built from two core concepts: **nodes** and **transitions**.

### Nodes

Nodes represent individual steps of your automation. They come in a range of types, depending on the nature of their subtask:

<Card title="Agent Node" icon="brain" href="/fundamentals/nodes/agent" horizontal color="#E6BFF8">
  Instruct an LLM to interact with the webpage
</Card>

<Card title="Output Node" icon="check-circle" href="/fundamentals/nodes/output" horizontal color="#D6E7FE">
  End the execution and return an outcome label plus structured results
</Card>

### Transitions

Transitions define how the workflow moves between nodes:

* **Agent-driven** transitions: The AI detects when a subtask is complete and moves forward
* **Deterministic** transitions: Code or conditions trigger movement (e.g., *“element X appeared”*)

This hybrid architecture gives you the freedom to pair AI reasoning with deterministic logic—ideal for real-world, multi-step browser flows.

<Info>
  Curious why we chose this architecture?
  Read our deep dive: **[Graph-Powered Browser Agents](https://asteroid.ai/blog/introducing-asteroid-ai-browser-agents)**.
</Info>

***

## Context Management

### Local context

Each node receives only the information it needs for **its subtask**. This prevents context pollution, reduces reasoning drift, and makes each step more deterministic.

### Passing information between nodes

When data must flow between steps, you should use:

* **[Per-transition output schemas](/fundamentals/transitions#passing-data-across-a-transition)**: define the exact shape of the data a node hands to the next one as it crosses a transition
* **[The agent filesystem](/fundamentals/files)**: write files under `shared/` to carry larger artifacts between nodes

This model avoids “giant prompts” and encourages clean, modular design—similar to strong function boundaries in software engineering.

***

## Workflow Design Best Practices

### 1. Start simple

Begin with:

* The seeded **Start** node, which every graph has exactly one of
* **One Agent node**, and
* **One Output node**

This helps validate the core task before introducing structure.

### 2. Add nodes as complexity grows

Introduce more nodes when:

* You interact with **multiple portals** or move between distinct URLs
* The workflow involves **separate tabs or pages** within one portal
* A subtask becomes long or has multiple sub-steps
* You want different models or timeouts for different stages
* You’ve gained grounded knowledge and can safely split steps

A good rule of thumb:

> **If a node needs more than a paragraph of instructions, it should probably be split.**

### 3. Scope nodes to a sequence of related actions

Each node should represent a clear, single intention, such as:
“Fill driver information” | “Upload documents” | “Retrieve quote”.

### 4. Use descriptive naming

Clear names make your graph self-documenting:

* **Agent Name** – what the whole flow accomplishes
* **Node Names** – the subtask (“Drivers Node”, “Billing Node”)
* **Variables** – reflect real-world meaning (`customer_id`, `doctor_note`)
* **Outcome labels** – predictable and explicit

### 5. Always define failure paths

Every Agent node should have a **Failure** transition to an output node.

Failure paths make debugging easier and enable safe recoverability.

***

## Examples Task Decomposition

Here are high-level examples of how complex workflows break naturally into nodes.

### **Insurance Carrier Quoting**

**Task:** Generate an insurance quote for a customer.

**Nodes**:

* <Icon icon="brain" color="#E6BFF8" /> Navigate to carrier and log in (Agent node)
* <Icon icon="brain" color="#E6BFF8" /> Create quote (Agent node)
* <Icon icon="brain" color="#E6BFF8" /> Insert driver info (Agent node)
* <Icon icon="check-circle" color="#D6E7FE" /> Output quote (Output node)

***

### **Healthcare EHR Data Entry**

**Task:** File a patient consultation on an EHR.

**Nodes**:

* <Icon icon="brain" color="#E6BFF8" /> Navigate to EHR and log in (Agent node)
* <Icon icon="brain" color="#E6BFF8" /> Lookup patient (Agent node)
* <Icon icon="brain" color="#E6BFF8" /> Fill consultation (Agent node)
* <Icon icon="check-circle" color="#D6E7FE" /> Confirm success (Output node)

***

### **Property Management Workflow**

**Task:** Update the lease information for a tenant.

**Nodes**:

* <Icon icon="brain" color="#E6BFF8" /> Navigate to portal and log in (Agent node)
* <Icon icon="brain" color="#E6BFF8" /> Search tenant (Agent node)
* <Icon icon="brain" color="#E6BFF8" /> Update lease info (Agent node)
* <Icon icon="check-circle" color="#D6E7FE" /> Return updated records (Output node)

These flows remain readable, predictable, and easy to iterate on, far more than a single long-running “mega-agent.”