Skip to main content
A node’s instructions determine what the node does when it runs. It’s important not to write vague or confusing instructions. Clear, well specified instructions are the key to cheap, fast and accurate integrations.

​
What do good instructions look like?

Write every agent node instruction in four parts.
Success criteria carry more weight than they look like they do. Without one, the workflow has to guess when it is finished, and a guessing workflow keeps clicking.
Name the button text, the field label, and the banner exactly as the site shows them. The workflow reads the page, so the words you write and the words it sees should match.

​
Size a node right

One node does one subtask. A node that logs in is a node. A node that logs in, searches, and files a report is three nodes wearing a trenchcoat. Split a node when:
  • The instruction runs past a dozen steps.
  • Two halves of the instruction can fail for different reasons.
  • You want a different transition out of each half.
  • One half is stable and the other is fragile.
Keep a node whole when the steps only make sense together — open the modal, fill it, submit it. Smaller nodes cost you nothing and buy you three things. The failure point is clearer. The instruction is shorter. Each half gets its own failure path. Read Workflows are graphs for how the pieces fit.

​
Pass values in

Write {{.variable_name}} where a value changes from run to run. The caller supplies the values at run time, so one workflow serves every case.

​
Naming rules

A variable name:
  • Contains letters, numbers, and underscores only
  • Contains no spaces, and none of @, -, or .
Valid: {{.user_name}}, {{.email}}, {{.api_key}} Invalid: {{.user-name}}, {{.my@var}}, {{.1st_item}} Give a variable the name a person would give it. {{.patient_name}} tells the next reader what belongs there. {{.p1}} does not.

Inputs and outputs

How values reach an execution, and how the result comes back

​
Templating

Write {{.variable}} to drop an input value into an instruction at run time. Reach into nested JSON with a dot path:
Keep the instruction one shape. A step that needs to branch is a graph that wants to exist. Build the branches as nodes, and let transitions choose between them.

​
When it goes wrong

Watch an execution, find the step that broke, and change the instruction that owns it. Change one thing, then run it again. Two changes at once hide which one worked.

​
Best practices

  • Start simple. Get the happy path running, then add the edge cases you meet.
  • Write down every variation you see. An execution that surprised you is an edge case you now know.
  • Name nodes and variables so the graph reads itself. “Find Patient” beats “Node 3”.
  • Test with different input values. It’s important that, when the input data changes, the workflow still runs as expected.
  • Add the failure path. Every agent node needs a route to an output node if it can fail in any way.

Test, iterate, publish

Run the draft, read it, change one thing, publish

Improve your workflows

Turn what production teaches you into changes

Nodes

What a node is and what it can do

Transitions

How the workflow chooses where to go next