Sree Dayanidhi

What LangGraph buys over a hand-wired agent pipeline, and the one-line reducer that stops two parallel branches from clobbering each other

Say your pipeline has a threat-scoring agent and a coalition-modelling agent, and both append their findings to the same warnings list on a shared state object. Neither depends on the other, so a for-loop wastes time running them back to back — but fire them off concurrently and both read the old list, both write their own copy back, and one agent's findings silently vanish. A plain loop makes you choose between slow and wrong. A graph runtime solves exactly this, and nothing more exotic — I built two engines on it (a Game of Thrones strategy oracle and an intelligence-operations oracle), each eight to ten nodes over one shared typed state, where a one-line rule declaring that a field merges by appending rather than replacing lets two agents write the same list safely, and a gate kills a broken run before the expensive model step. If your pipeline is honestly a straight line — fetch, then compute, then summarize, each step waiting on the last — you have nothing to parallelize and nothing to merge; write the for-loop and move on.

16 min read

Contents
  1. Two engines that wanted the same shape
  2. A for-loop is right until two steps stop needing each other
  3. The topology is data, sitting apart from the work
  4. The one-line merge rule that makes the branch safe
  5. A fork in the wiring, not a scatter of early returns
  6. Resuming an expensive run instead of restarting it
  7. The same pause that survives a crash can wait on a person
  8. The two engines, side by side
  9. Where this pattern shows up outside a game oracle
  10. The build, and what to wire in early
  11. References

The first time I added a second parallel branch to one of these pipelines, the run died before either branch's work was used. Two analysis steps had finished at the same moment and both tried to append a warning to the same list on the shared state, and the runtime stopped with an error about two updates arriving for one value at once. Nothing was wrong with either step. The problem was that I had asked two things to write the same place and never said how their writes should combine.

That error is the whole argument for the machinery in this post, in miniature. A pipeline of agents is easy to write as a straight loop — call the first step, hand its output to the second, and so on — right up until two steps have no reason to wait for each other and every reason to write back to the same object. At that point the loop forces you to pick between running them one after another for no reason, or running them together and hand-merging their results without dropping one. A graph runtime makes that a property of the wiring instead of a thing you remember to do by hand.

Two engines that wanted the same shape

I have built the same skeleton twice, for two unrelated problems.

The first was a strategy oracle for Game of Thrones — give it a character at a turning point, say Joffrey deciding Ned Stark's fate at the Great Sept, and it tells you what he should have done instead and what it would have cost him. It runs eight nodes. A first step assembles the board state for that moment: who holds power, who owes whom, which alliances are live. Two branch off it in parallel — one scores threats by mapping the alliance network, where an information broker like Littlefinger outranks a rival with an army, and one models coalitions, pricing what each ally is actually worth to Joffrey's position. They converge on a step estimating what each actor believes, including the gap between what Joffrey thinks Littlefinger is doing and what Littlefinger is actually doing. Then a sequential run: an adversary model predicting how each rival weighs a loss, a strategy solver ranking the real options on the table — execute Ned, exile him, or honour the deal sending him to the Night's Watch, with zero weight landing on the execution he chose — a simulator rolling each option forward two thousand times to put a survival probability on it, and finally a narration step that turns the numbers into prose.

The second was an intelligence-operations oracle — a single operative moving through a hostile network, planning under uncertainty about who is compromised. It runs ten nodes with the same fan-out and fan-in: assemble state, branch into an intelligence-network analysis and a coalition analysis at the same time, merge them at a belief-estimation step, then a longer sequential spine of information-value scoring, an adversary model, a planner that reasons over a belief state rather than a known one, a critical-path scheduler, a Monte Carlo simulator, and narration.

Two different problems, one recurring structure: some steps must happen in order, some genuinely can happen at once, one shared object carries the state between them, and at least one point in the flow is a fork where the run should either continue or stop.

A for-loop is right until two steps stop needing each other

The honest counterfactual has to be stated before the framework earns its place, because for a genuinely linear pipeline the framework earns nothing. If your steps run strictly in order and each hands its result to the next, a plain loop is correct, and reaching for a graph runtime is pure ceremony. Do not do it.

The framework starts paying the moment two things are true at once. First, some steps have no dependency on each other — in the strategy oracle, scoring threats and modelling coalitions read the same board state and neither needs the other's output — so running them back to back wastes the wall-clock of the shorter one every single run. Second, those independent steps write back to the same shared state. That combination is where a hand-rolled solution gets subtle.

You can, of course, reach for raw concurrency primitives and gather the two independent steps yourself. The trouble is not launching them; it is landing their results. Two steps that both append to the same list of warnings, or both set a key on the same dictionary, will race — and the failure is not a loud crash but a dropped write that surfaces three steps later as a belief estimate computed from half its inputs. You end up writing the merge logic by hand, for every shared field, and getting it exactly right under concurrency, which is the class of bug people are worst at reviewing.

The ranked reasons the graph runtime is worth it, then, are these. Parallelism you declare rather than orchestrate comes first. Safe convergence of concurrent writes comes second, and is the one that actually bit me. Declarative routing — the ability to fork or stop mid-flow as a piece of wiring rather than a scatter of early returns — comes third. Resumability, being able to restart an expensive run from where it stopped rather than the top, comes fourth. None of those is about making the model smarter. Every one is about making the plumbing around it honest.

The topology is data, sitting apart from the work

The thing that makes the rest possible is that the shape of the pipeline is written down separately from what each step does. Each step is an ordinary function that reads the shared state and returns only the fields it changed. The wiring — which step feeds which, where the flow forks, where two branches rejoin — is declared on its own, as a list of connections between named steps.

That separation is why the whole flow fits on one screen and reads like a map:

The intelligence oracle wired as a LangGraph state machine: a start marker into an assemble-state node, which fans out to two NetworkX branches — intel network and coalition — that fan back in to a belief-estimate node where a barrier waits for both and an append reducer merges the shared error and warning lists; then a sequential spine of value-of-information, a Stackelberg adversary model, a POMDP strategy planner, a CPM critical-path scheduler and a Monte Carlo simulator; then a conditional fork that skips narration and routes straight to END on a fatal error, or otherwise runs a Claude narration step before END. Snapshotting state at each boundary is what lets a long run resume or pause for a human.

Two connections leave the state-assembly step, so its two successors run as a parallel branch. Both successors connect to the belief step, so the belief step does not begin until both have landed — the convergence point is an automatic barrier, not a countdown I maintain. Adding a third parallel analysis later is one more connection out and one more connection in. The step functions never learn that the topology changed, because they were never told the topology in the first place.

The one-line merge rule that makes the branch safe

Now the field where the two branches collide. When two steps in the same parallel tick return a value for the same key, the runtime by default refuses to guess how to combine them and raises what its documentation names an INVALID_CONCURRENT_GRAPH_UPDATE — which is precisely the error that opened this post. The default is a refusal, and the refusal is a feature: it will not silently pick a winner.

The fix is to attach a merge rule to that field once, at the point where the shared state is defined. The rule for the shared error and warning lists is the simplest one there is — combine by appending, so two concurrent writes become one longer list instead of one overwriting the other. The docs call these reducers, and the one property they must have is associativity: merging A then B must equal merging B then A's contents into the batch, which is what lets the runtime replay a batch of writes without changing the result.

The before and after is stark, and worth seeing as two states rather than a description:

Two panels comparing parallel writes to the same shared errors list. Without a merge rule, an intel-network branch writing weak source and a coalition branch writing ally exposed both land on the errors field at once, and the run stops with an INVALID_CONCURRENT_GRAPH_UPDATE error because two updates arrive for one key with no rule to combine them. With an append reducer attached to the field, both writes land and the list is merged into weak source and ally exposed rather than one overwriting the other, though the order is not guaranteed.

One line of declaration at the point the field is defined, and the entire class of dropped-concurrent-write bugs is gone from every branch that touches that field — not fixed case by case, but made unrepresentable. This is the reducer of the title, and it is the single highest-leverage thing the runtime gave me. The one caveat worth stating plainly: an append rule combined with a step that resends its whole list on each pass will duplicate entries, so the rule has to match how its field is written, not just what type it holds.

A fork in the wiring, not a scatter of early returns

The third advantage shows up in both oracles as the same piece of wiring: a gate in front of the narration step. Any step that hits something unrecoverable records a fatal error on the shared state, and a fork reads that flag and routes the run straight to the end, skipping narration entirely — there is no point paying a model to narrate a broken run.

The point is where that decision lives. It is one labelled fork in the topology, sitting next to every other connection, visible in the same map as the rest of the flow. The alternative — a check-and-return at the top of the expensive step, and another inside it, and a guard three steps earlier — spreads the same control flow across the very functions it is meant to protect, where no one reading any one of them can see the whole rule.

Resuming an expensive run instead of restarting it

The fourth advantage only matters once a run gets long enough to hurt, and it is the one to wire in before you feel the need for it. Because the shared state is a single well-defined object and the runtime knows the boundaries between steps, it can snapshot that state after each step — which turns resuming a dead run from a subsystem you build into a flag you set.

Both oracles have the mode that makes that pay. Either can be asked for a whole arc instead of a single decision: every turning point in a character's timeline, in sequence, each one its own expensive planning problem. A twelve-point arc that dies on point nine has thrown away eight finished analyses, and without a snapshot boundary the recovery is bespoke — you invent somewhere to stash partial results and some way to work out what had already been done. With one, the boundary is already there and resuming is configuration.

The rule worth following: turn checkpointing on in the first version of any pipeline whose full run costs real money or real minutes, and prove it by killing a long run halfway on purpose and confirming it comes back at the right point rather than the top. It is nearly free while the step boundaries are still fresh in your head, and it gets expensive once reconstructing them is its own project.

The same pause that survives a crash can wait on a person

There is a second thing the snapshot boundary buys, and it is worth wiring in even when runs are short. A checkpoint does not only survive a crash; it lets a run stop on purpose and wait. A fork already decides whether the run continues, and a snapshot already holds everything the run knows. Put those two together in front of a step you cannot take back, and the verdict that releases the run can come from a person rather than a rule — the run sits at that node for an hour or a week, then carries on from exactly where it paused instead of starting the analysis over.

That is the honest way to put a human in front of an irreversible step — a report that goes to a client, a charge, anything published. It is not a new subsystem. It is the fork and the checkpoint the graph already gives you, with a person reading the verdict. Keep it risk-based: a hold on every harmless step only makes the pipeline slow, so gate the irreversible nodes and let the rest run.

The two engines, side by side

Engine Steps Parallel branch The fork does
Strategy oracle 8 threat + coalition → belief skip narration on fatal error
Intelligence oracle 10 intel-network + coalition → belief skip narration on fatal error

The rows are nearly identical, and that is the observation worth keeping. A war of great houses and a lone operative in a hostile network share no subject matter at all, and the wiring came out the same anyway: fan the independent analyses out, converge them on a belief step, run the deterministic spine in order, gate the model call at the end. The skeleton belongs to neither story. It is what the shape of the problem demands once some steps are independent of each other and one object carries the state between them.

Where this pattern shows up outside a game oracle

Strip away the great houses and the operative, and the shape is a directed graph of steps over one shared record, with parallel branches that must merge cleanly, forks that stop bad runs early, and snapshots that let long runs resume. That description fits a great deal of work that has nothing to do with the examples here.

The unit is not the agent. It is the shared state, the rules for merging concurrent writes into it, and the forks that decide whether the run goes on. Get those three right and the individual steps become boring, which is what you want them to be.

Setting The parallel branch The fork that stops the run
Loan underwriting credit pull and income verification at once decline before ordering a costly appraisal
Medical intake labs and imaging read in parallel halt before a specialist referral if a red flag fires
Ad-campaign build creative checks and audience checks together block launch if brand-safety fails
Insurance claims fraud signals and coverage lookup concurrently route to a human before auto-approving a payout
Content moderation policy classifiers running side by side stop before publish on any hard violation
ETL with validation independent source pulls in parallel quarantine the batch before it hits the warehouse

Three design choices from these builds transfer directly, whatever the domain.

Declare the merge rule for a shared field the day you add the second writer, not the day it breaks. The concurrent-write refusal is a gift precisely because it fails loudly at wiring time rather than quietly at run time. Treat any state field that more than one step can write as needing an explicit merge rule, and write that rule when you add the branch, not after a dropped write has cost you a debugging afternoon three steps downstream.

Put every fork in the wiring, never inside the step it guards. A run that should stop should stop at a labelled branch you can see on the map, not at a guard clause buried in the function that would otherwise do the expensive work. The test is whether someone can read the topology alone and know every place the run can end. If they have to open the step functions to find the exits, the control flow is in the wrong place.

Snapshot at the step boundary before you think you need to. Checkpointing is cheap to turn on at the start and expensive to retrofit, because retrofitting it means reconstructing where your step boundaries even were. Any pipeline whose full run costs real money or real minutes should be checkpointed from its first version, so that the first time a run dies at step nine you resume at nine instead of rediscovering that you cannot.

The build, and what to wire in early

The reference shape, with the real pieces named. The runtime is LangGraph, and the shared state is a single typed dictionary that every step reads and writes. Each step is a plain function returning only the fields it changed. Independent steps are declared as parallel branches by giving one step two successors, and they converge by pointing both at a common next step. Any field two steps can write carries a merge rule — an append for the shared error and warning lists. Forks are labelled conditional connections that route on a verdict or stop on a fatal error. Long runs are checkpointed at the step boundary the runtime already knows. The heavy computation inside the steps is ordinary and deterministic — graph analysis, a planner over a belief state, a Monte Carlo simulator, a critical-path scheduler — and a language model is used only at the very end, to narrate results the pipeline already computed, never to decide them.

Three things are cheap to build in now and expensive to add later. The merge rule on every shared field, because adding it after the fact means auditing every branch that ever wrote there. The checkpoint boundary, because adding it later means rediscovering where your steps begin and end — and because it is also what lets a fork pause for a human instead of only surviving a crash. And the discipline of steps that return only what they changed, because a step that rewrites the whole state defeats both the merge rules and the snapshots at once. Wire those three in on the first pass and the rest of the graph stays boring for as long as you own it.

References

Tooling