Lesson 03 · Foundations · 12 min

State

Nodes do not call each other. They communicate only through shared state, which is what makes a graph inspectable: at any point you can ask what is known, and the answer is a plain object rather than a conversation you have to read.

Two failure modes account for most state bugs, and they pull in opposite directions.

OverwritingA node writes to a key another node still needed. Usually appears as a downstream node behaving as if an earlier step never ran.

AccumulatingState grows without bound because nothing is ever removed. Later nodes get prompts full of things they do not need, which costs tokens and degrades their answers.

The practical rule is that each node should own the keys it writes. When two nodes need to write the same idea, give them separate keys and add a node that reconciles them. That is more explicit than a shared mutable field and much easier to debug.

Note what state is not: it is not the conversation. A graph node usually receives a constructed prompt containing exactly the fields it needs, not the whole history. That is a real advantage over a loop, where every turn re-sends everything.

In this lab, the refund path writes four keys — category, order_id, order, policy — before anything is drafted. The reply node sees only those, which is why its answer cannot contradict the record.

Checkpoint

List the state keys written during one refund run, in order.