> ## 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.
# Workflows are graphs
> An Asteroid workflow is a graph of small steps joined by transitions, not one long prompt.
An Asteroid workflow is a graph.
A **node** is one small task. A **transition** is a rule that picks what runs next. Together they describe the whole job.
You do not write one long prompt. You write several short ones and connect them.
***
## Why a graph beats one long prompt
A node holds one intention, so the model has less to get wrong.
An execution reports the node it sits on and the edge it took to get there.
Rewrite one node's instructions. The rest of the graph stays as it was.
Every node picks its own model and its own capabilities.
One long prompt gives you none of this. It succeeds or fails as a whole. When it fails, you rewrite all of it.
***
## The three node types
| Node | What it does |
| ------ | ------------------------------------------------------------------------------------------- |
| Start | Marks where an execution begins. Every graph has exactly one. |
| Agent | Reads instructions and does the work in the environment. |
| Output | Ends the execution. Returns an outcome label, and a result when the node declares a schema. |
What each node type holds and how you configure it
***
## How an execution walks the graph
The start node makes no decision. It has one outgoing transition, and the execution follows it.
The node reads its instructions and acts. It clicks, types, reads pages, and runs scripts.
The node has one outgoing transition per possible next step. The workflow picks one, or a selector matches and picks one for it.
The execution moves along the edge. The receiving node sees any data that edge carried.
The output node ends the execution. It returns an outcome label and structured data to your code.
```mermaid theme={null}
flowchart LR
S([Start]) --> A[Log in]
A --> B[Look up patient]
B -->|found| C[File the claim]
B -->|not found| E([patient_not_found])
C --> D([claim_filed])
C -->|portal error| F([failure])
```
An execution sits on exactly one node at a time. It never runs two nodes at once.
***
## One node, one intention
Give a node a single clear job: "Log in", "Fill driver details", "Upload documents", "Read the quote".
> If a node needs more than a paragraph of instructions, split it.
Start with the seeded start node, one agent node, and one output node. Prove the task works, then add structure.
Split a node when:
* The work crosses two portals or two distinct URLs.
* The work moves between tabs or pages inside one portal.
* A subtask grows long or gains its own sub-steps.
* You want a different model or a different timeout for one stage.
Name things for what they mean. The workflow name says what the whole flow does. A node name says what that step does. An outcome label says how the execution finished.
How to write the instruction block inside a node
***
## Every agent node needs a failure path
Connect every agent node to an output node through a failure transition.
Without one, a missing element or an unexpected page has nowhere to go. With one, the execution ends on a label you chose, and your code can act on it.
***
## What travels between nodes
Each node sees only what it needs. That keeps its context short and its behaviour steady.
When data must cross a node boundary, you have two routes.
| Route | Use it for |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| A schema on the transition | Small structured values, such as an ID or a plan name. The next node reads them as `{{.output}}`. |
| The workflow filesystem | Larger artifacts. Write them under `workspace/` and read them in a later node. Use `shared/` only for data a later execution should still see. |
How an execution chooses its next node, and how data crosses an edge
The directories an execution can read and write
***
## The graph is not the contract
Your code never names a node. It sends **inputs**, then reads an **outcome label** and a **result**. That contract holds while you reshape the graph behind it.
The contract between a workflow and the code that calls it
Draw the graph in the visual builder