2.1

The superstep loop: plan, execute, update

Treat each superstep as one transaction: parallel writes become visible together, in task-path order, so never let your state depend on which node finished first.

Two parallel nodes each ask a model for an answer and append it to one list. Your log shows b returning before a in most runs. The state lists a first every time. The order you see in the state is a sort order, and the runtime fixes it before the nodes run.

When you finish this section, you can read a superstep trace line by line and predict which node runs next from the channel versions. You can also predict the merge order of parallel writes, and set a recursion limit that counts the right thing.

Three phases in one loop

Superstep: one turn of the LangGraph loop. It plans the tasks that are ready, runs them, and then applies all of their writes at once.

The loop is short. loop.tick() plans, runner.tick() runs every planned task that has no saved writes yet, and loop.after_tick() applies the writes and saves a checkpoint. A node never sees a write from its own superstep. The values it reads are the values at the end of the superstep before.

Plan. prepare_next_tasks builds two kinds of task. A PULL task is a node whose trigger channel holds a value and has a newer version than the node last saw. A PUSH task is one Send waiting in the __pregel_tasks channel.

Execute. The runner starts the tasks in parallel. As each task finishes, the loop records its writes and passes them to the checkpointer in the background. Section 2.3 follows that write.

Update. After the last task, apply_writes sorts the tasks, groups their writes by channel, and calls each channel once with the whole group. Then _put_checkpoint saves the result.

One agent run, captured

We patched the loop functions of langgraph 1.2.22 to record each call. Then we ran create_agent with Qwen3 4B on Ollama, on the x86 server guest, at temperature 0. The prompt was Weather in Paris and Oslo?. The model asked for two get_weather calls in its first reply, which took 3.64 s, and answered in its second, which took 1.59 s. These times come from one run on a loaded guest, so read the order and the counts and not the seconds. This is step 1 and step 2 of the trace:

outputplan, execute, and update for the model step and the tools stepFull log
[ 12] PLAN step=1 stop=9999 updated_channels=['branch:to:model', 'messages']
        task __pregel_pull model  id=c716c241 path=('__pregel_pull', 'model') triggers=['branch:to:model']
        versions_seen(before)={'__input__': {}, '__start__': {'__start__': 1}}
[ 13] TICK step=1 returns=True status=pending run=['model']
        channel_versions={'__start__': 2, 'branch:to:model': 2, 'messages': 2}
…
[ 15] UPDATE order=["model@('__pregel_pull', 'model')"]
…
        versions_changed={'__pregel_tasks': [None, 3], 'branch:to:model': [2, 3], 'messages': [2, 3]}
        versions_seen_updated={'model': {'branch:to:model': 2}}
        updated_channels=['__pregel_tasks', 'messages']
…
[ 18] PLAN step=2 stop=9999 updated_channels=['__pregel_tasks', 'messages']
        task __pregel_push tools  id=7bd87c87 path=('__pregel_push', 0, False) triggers=['__pregel_push']
        task __pregel_push tools  id=81e79e5c path=('__pregel_push', 1, False) triggers=['__pregel_push']
…
[ 25] UPDATE order=["tools@('__pregel_push', 0, False)", "tools@('__pregel_push', 1, False)"]
Steps 1 and 2 of the run. The writes of the model and the saver lines between the phases are cut.

create_agent turns each tool call into its own Send, so two tool calls become two PUSH tasks of the tools node. Each one gets its own task id and its own index in the path. Figure 2.1 draws all six supersteps of the run with the version of each channel.

Fig. 2.1six supersteps of one create_agent run, with channel versionstimeline
Six supersteps of one create_agent run, with channel versions A grid of the 6 planned supersteps of one create_agent run with two tool calls, from the input step -1 to step 4, which finds no task. The top row names the tasks planned in each step: __start__, model, two PUSH tasks of tools, model again, and none. Four rows below give the version of __start__, messages, branch:to:model, and __pregel_tasks after each step. A filled cell is a channel written in that step, a dashed cell is a channel cleared by its reader with a new version, and a plain grey number is a version carried over. Every channel that changes in one step gets the same number. Amber arrows run from the channel version that triggers a task to that task in the next step. The bottom row is the version of branch:to:model that model had seen. At step 4 the channel is at version 5 and model saw 4, but the channel is empty, so no task runs. SUPERSTEP -1 0 1 2 3 4 tasks planned PULL or PUSH __start__ messages branch:to:model __pregel_tasks model had seen branch:to:model input v1 - __start__ v2 v2 v2 - model v2 v3 v3 v3 - tools[0] tools[1] v2 v4 v4 v4 v2 model v2 v5 v5 v4 v2 none v2 v5 v5 v4 v4 1 1 step 1: messages, __pregel_tasks and branch:to:model all get v3 2 2 step 3: branch:to:model v4 is newer than seen v2, so model runs 3 3 step 4: v5 is newer than seen v4, but the channel is empty: no task written, new version read and cleared, new version PUSH task from a Send version that triggers the next task grey number: version carried over empty channel, triggers nothing
Every write in a superstep gets the same new version, and a node runs only when its trigger channel is newer than the version it last saw. Columns are supersteps, from the input step to the step that finds no task. Amber tags are the tasks planned. In the channel rows, a filled cell is a write with its new version, and a dashed cell was read and cleared. Amber arrows run from a version to the task it triggers.

Versions decide what runs next

Channel version: a number that the loop stores for each channel in the checkpoint. A channel that changes in a superstep gets a new version.

The rule is simple, and it is global. apply_writes takes the highest version of any channel and adds one. Every channel that changes in that superstep gets that same number. In step 1 above, messages, __pregel_tasks, and branch:to:model all moved to version 3.

versions_seen: a map in the checkpoint, from each node to the version of each trigger channel when that node last ran.

apply_writes updates versions_seen only for the channels that triggered the task. After step 1, model has seen branch:to:model at version 2. In step 3 that channel is at 4, so model runs again. A PUSH task has the trigger __pregel_push, which is no channel, so versions_seen for tools stays {} in the trace.

One detail explains why the run ends. branch:to:model is an EphemeralValue. When model reads it, the loop clears it and still gives it a new version. In step 4 its version is 5 and model saw 4, but the channel is empty. The plan asks for both a newer version and a value, so no task runs and the loop stops.

Writes merge in task-path order

apply_writes sorts the tasks by their path before it applies anything. A reducer then gets the writes in that order, whatever order the tasks finished in.

We measured this on the x86 server guest with Qwen3 4B, 3 runs per case. Two parallel nodes, a and b, each ask the model for an answer and append to one list with operator.add. One node asks for 60 words and the other for one word: Raw runs

outputsix runs, two finish orders, one merge orderFull log
slow node=a: finish order (node, model seconds)=[('a', 5.58), ('b', 5.75)]  merged list=['a', 'b']
slow node=a: finish order (node, model seconds)=[('b', 0.6), ('a', 5.93)]  merged list=['a', 'b']
slow node=a: finish order (node, model seconds)=[('b', 0.6), ('a', 5.85)]  merged list=['a', 'b']
slow node=b: finish order (node, model seconds)=[('b', 5.48), ('a', 5.62)]  merged list=['a', 'b']
slow node=b: finish order (node, model seconds)=[('b', 5.7), ('a', 5.83)]  merged list=['a', 'b']
slow node=b: finish order (node, model seconds)=[('b', 5.67), ('a', 5.8)]  merged list=['a', 'b']
Each pair is the node and the seconds of its model call, in the order the nodes returned.

The model calls did not take the time we asked for. One CPU Ollama server answered both nodes, so a short answer could wait behind a long one. b returned first in 5 of 6 runs, and the list was ['a', 'b'] in 6 of 6.

PULL paths sort before PUSH paths. The writes of a node that Command(goto=...) started by name apply before the writes of the Send tasks in the same superstep. In the capture, node a asked the model for a city and sent c to look up its weather. The planner listed c first, and the update applied b first:

outputa PULL task and a PUSH task in one superstepFull log
  PLAN step=2: push c path=('__pregel_push', 0, False) triggers=['__pregel_push'] id=5f91e09b; pull b path=('__pregel_pull', 'b') triggers=['branch:to:b'] id=5bbd9a1a
  UPDATE order=["b@('__pregel_pull', 'b')", "c@('__pregel_push', 0, False)"] -> updated=['results'] versions={'__pregel_tasks': [3, 4], 'branch:to:b': [3, 4], 'results': [3, 4]}

Figure 2.2 sets the two orders side by side. So the order of a merged list is stable across runs, and you can test it. It also means a reducer that keeps the last value keeps the value of the task whose path sorts last. The slowest task has no say.

Fig. 2.2the order tasks finish against the order their writes applycomparison
The order tasks finish against the order their writes apply Seven supersteps with two parallel tasks each, recorded with Qwen3 4B on the x86 server guest. On the left, the tasks in the order they returned, with the seconds of their model call. On the right, the order in which apply_writes applied their writes. In six runs, nodes a and b each ask the model for an answer and append to one list with operator.add. b returned first in 5 of 6 runs, and the list was a, b in 6 of 6. In the last superstep, node b was started by Command(goto) as a PULL task and node c by a Send as a PUSH task. c finished first, and b still applied first, because PULL paths sort before PUSH paths. ORDER THEY RETURNED ORDER APPLIED model seconds under each sorted by task path a asked for 60 words a 5.58 s b 5.75 s a item 1 b item 2 apply_writes a asked for 60 words b 0.60 s a 5.93 s a item 1 b item 2 a asked for 60 words b 0.60 s a 5.85 s a item 1 b item 2 b asked for 60 words b 5.48 s a 5.62 s a item 1 b item 2 b asked for 60 words b 5.70 s a 5.83 s a item 1 b item 2 b asked for 60 words b 5.67 s a 5.80 s a item 1 b item 2 Command and Send c PUSH b PULL b PULL c PUSH a PUSH task from a Send b back first in 5 of 6, merged a, b in 6 of 6
The nodes returned in two different orders over six runs, and their writes applied as a, then b, in all six, because apply_writes sorts by path. Each row is one run. Left, the nodes in the order they returned, with the seconds of their model call. Right, the order apply_writes used. The last row is one superstep with a PULL task and a PUSH task, and a dashed box is the PUSH task.

What the recursion limit counts

The loop sets stop to the current step plus the limit plus one, and fails when the step passes stop. So the limit counts supersteps, and the hidden __start__ step is one of them.

We measured the count on the x86 server guest with Qwen3 4B, one run per limit. The prompt tells the model to call a tool on every turn: Raw runs

recursion_limitsupersteps runmodel calls before the error
121
452
563
10115
252613

A limit of k runs k plus one supersteps on new input, and the model runs about k divided by two times. A resume of an interrupted thread with a limit of 4 ran 6 supersteps, steps 2 to 7. create_agent sets the limit to 9,999 on its graph. A plain StateGraph gets 10,007.

What to do with this

Write reducers whose result does not depend on order, such as a sum or a set, when the order means nothing. When it means something, depend on the path order and test it, because it is stable. Never use a log of finish times as the order of the state.

Give a key that two parallel nodes write a reducer, even when you expect one writer. Section 2.2 shows what one missing reducer does to a thread.

Count model calls, not steps, when you set a limit for an agent. For a budget of n model calls, set recursion_limit to two times n. Each before_model or after_model hook node adds one superstep per model call, so add those too.

LangChain (Python): langchain, langchain-core, langgraph, deepagents, langsmith 1.5.0 · c2f4036 · 2026-11-11 · Edition 2026.11