Advanced agents · Chapter 1 of 10
State at scale
How LangGraph.js 1.5.1 merges writes to one state key: StateSchema fields with and without reducers, the order of parallel writes, Overwrite and UntrackedValue.
Goals
- Run two parallel nodes that write the same key with no reducer, and read the error.To do
- Add a reducer and see how the two writes combine, in order.To do
- Use Overwrite to replace a reduced value.To do
- Predict the end of a superstep.To do
Step 1 of 4: The read
One superstep, many writes
LangGraph runs a graph in supersteps, as in Agent systems, chapter 5. Every node that is due runs in the same superstep, in parallel, and returns an update: an object with the state keys it changes. When all of them have finished, LangGraph applies the updates and saves a checkpoint of the state. Nodes in one superstep never see each other's updates, so what matters is how two writes to the same key combine.
StateSchema and reducers
Since LangGraph.js 1.1 you can declare state with StateSchema, one field per key. A field given as a plain schema, such as z.string() from Zod, holds the last value written and takes one write per superstep. Two writes to it in the same superstep fail with InvalidUpdateError, even when the values are equal, and no checkpoint is saved for that superstep.
A ReducedValue field has a reducer: a function (current, next) => value that LangGraph calls for each write, for example to append to a list. The older Annotation.Root API declares the same thing with Annotation({ reducer, default }).
Which write goes first
A reducer gets a superstep's writes one at a time, in task-path order, not in the order the nodes finished. Task paths are compared as strings, and the path of a node started by an edge ends with its name, so here reviews goes before specs. Since 1.5.0, live runs and checkpointers use this same order, as LangGraph for Python does.
Overwrite and UntrackedValue
new Overwrite(value), added in 1.2, skips the reducer: the key is set to value, for example to replace a long list with a summary. Other writes to that key in the same superstep are dropped, and two Overwrite writes to one key in one superstep fail.
An UntrackedValue field holds a value while the graph runs: nodes read it, but no checkpoint saves it, so a run resumed from a checkpoint starts without it. Use it for large or temporary data you can fetch again.
The lab
Halden, a fictional outdoor shop, asks whether to stock a tent for winter. Two researcher nodes, reviews and specs, each add a note to notes in the same superstep; condense then sums the notes up. You run this graph three times: with no reducer on notes, with a reducer that appends, and with condense returning an Overwrite.
Step 2 of 4: Try it: A superstep timeline
A superstep timeline
Run the same graph three times: with no reducer, with a reducer, then with Overwrite. The timeline shows what each superstep wrote and what its checkpoint saved.
Loading the visual…
Mode:RealSimulatedReal: LangGraph.js 1.5.1 runs in this page, and the error, the merges and the checkpoints are its own. Simulated: the models' replies and how long each takes are scripted, and Halden's data is fictional.
Step 3 of 4: Check
Check
const State = new StateSchema({
topic: z.string(),
notes: new ReducedValue(z.array(z.string()).default(() => []), {
reducer: (current, next) => current.concat(next),
}),
});
new StateGraph(State)
.addNode("reviews", async () => ({ notes: ["reviews"], topic: "Ridge 2" }))
.addNode("specs", async () => ({ notes: ["specs"], topic: "Ridge 2" }))
.addEdge(START, "reviews")
.addEdge(START, "specs");Step 4 of 4: What you can do now
What you can do now
- Declare state with StateSchema, choosing a plain field, a ReducedValue or an UntrackedValue for each key.
- Predict how parallel writes to one key combine, in which order, and when they fail.
- Use Overwrite to replace a reduced value.