Graph Engineering: Every Edge You Draw Takes a Decision Away From the Model

Give one agent four jobs and it will do three of them.

Research the topic, write it up, review the draft hard, then ship or send it back. One prompt, one loop, four responsibilities. It researches well. It writes well. Then it reviews its own draft and approves it, because nothing in that loop gives it a reason not to. The output is confidently fine. Nothing errors, no metric moves, and the failure is invisible until somebody downstream reads the thing properly.

I have never seen that arrangement produce a real rejection. An agent marking its own work is not a check, it is a formality you pay tokens for.

The fix is to make the reviewer somebody else: a separate step, a different model, no write access to the draft, and a rule that a failed review goes back to the writer. Since mid-July 2026 that fix has a name, graph engineering, meaning the practice of arranging several agents or steps as a graph, with nodes that do the work, edges that route between them, and a shared state object travelling along the edges.

The name is a few weeks old. What it describes is a state machine, and I would rather you carried the older vocabulary into it, because everything that will hurt you here already has a name in systems engineering.

What you are actually building

A node is a unit that does work, usually a specialised agent with one job, sometimes a plain function. An edge is the routing between nodes, possibly branching on the result. Shared state is the object every node reads and writes, and it is the part that decides whether you have a system or a group chat with amnesia.

Three nodes, four edges, one of them a cycle. Note that the cycle is not optional. Production agents retry failed tool calls, ask for missing input, and revise after validation, so anything without a route backwards is a pipeline that you have drawn as a graph.

Now look at what that diagram actually changed. Not one agent in it got smarter. Every arrow is a routing decision that used to be made by a model at runtime and is now made by me, in advance, at design time.

That is the entire trade, and Google's Agent Development Kit states it plainly in its own docs: workflow agents there "operate based on predefined logic" and sequence execution "without consulting an AI model for assistance with the orchestration". What you buy is "deterministic and predictable execution patterns". What you pay is that a predetermined path can never be better than the prediction you made when you drew it.

An edge is a decision you have taken away from the model. Everything below follows from that one line.

The rule I apply before drawing any edge

Only draw edges for decisions you can make better in advance than the model can at runtime.

The model decides with full sight of what it just found. You decide months earlier with none of that. So the question for every arrow is not "does this look tidy in the diagram", it is "am I genuinely better informed about this decision than the thing standing in front of the evidence".

Sometimes the answer is obviously yes, and it is usually because the decision is not a judgement at all. Approval before publication in a regulated flow is a requirement, not a guess. Routing a support ticket to one of five known handlers is a classification with a fixed codomain. Fan out across six sources and join the results: I know the sources, so I can write that edge.

The answer is no more often than architecture diagrams suggest. The test I use in reviews is small and it works: can you name the edge's condition without using the word "appropriate"? "If the review fails, return to the writer" passes, because failure is defined. "If the agent decides further research is appropriate, return to the researcher" fails, because that is not a condition, it is the model's judgement with a box drawn round it. Leave that decision inside the node and let the loop own it.

The strongest evidence I can point at for getting this wrong is not mine, and it is better than mine. LangChain's generic deep research began as a predefined graph and they moved it to "a more agentic core loop" because planning and delegation there were "hard to pin down ahead of time". The team that sells the graph framework pulled the graph out of their flagship product, in public, because the work was not shaped the way their edges assumed. Read that as permission to do the same when your arrows start fighting you.

The refactor: promote one node, do not redraw the org chart

The migration people reach for is a rewrite, and it is almost always wrong. A loop is a graph with one node and an edge back to itself, which means the correct move is additive: keep the loop you have, make it node one, and split off only the step that is failing inside it.

This is the pattern I look for in review:

// Don't: rebuild the whole thing as a graph because one step was weak
const graph = buildGraph([research, plan, write, format, review, publish]);

// Do: keep the loop, promote only the step that needs to be somebody else
const draft = await writerLoop(task);
const verdict = await reviewer(draft);        // different model, read only, no write access to state
return verdict.passed ? draft : writerLoop(task, verdict.notes);

The reviewer is nearly always the first node worth extracting, and the reason has nothing to do with graphs. It is the self-assessment problem from the opening, and the fix is structural: a different model, read-only access, and no ability to edit what it is judging. That is one function call. You do not need a framework, a runtime, or a diagram to get the largest single quality improvement available in an agent system.

If you are choosing between shapes once you have more than two nodes, I wrote up the trade-offs in multi-agent topologies, and the supervisor pattern separately. Graph engineering is vocabulary for the wiring. It does not choose the topology for you.

Shared state is a schema, so treat it like one

Nodes and edges get the diagrams. State causes the incidents. Four systems-engineering questions, and I want all four answered before any of it is written.

Who owns each field. State is a schema with several writers and no database enforcing anything, which is the condition every distributed system gets burned by. Write down which node may write which field and enforce it in code. A reviewer that can edit the draft it is reviewing has just recreated the problem you split it out to solve.

Where the transaction boundaries are. A node either commits its output or leaves state exactly as it found it. Partial writes are the failure that hurts most, because the run continues on state that is half updated and downstream nodes see something no node intended to produce. If a node dies at token nine hundred, its half-written field must not survive. This is atomicity, it has been solved for decades, and agent frameworks will not do it for you.

What each node is allowed to see. The default that every framework makes easy is passing the whole state to every node, and it inflates your context window on a schedule. Each node appends, the state grows, and the state is the prompt, so by the fifth node you are paying to re-read the research notes on every call and pushing the part that matters further from the model's attention. Give each node a projection: the reviewer needs the draft and the bar, not the raw sources. The same discipline that makes agent memory work applies here, because retrieval beats accumulation the moment the accumulated thing outgrows the window.

What the blast radius of a bad write is. One node writing nonsense should degrade one branch, not poison the run. If a single malformed field can take down every downstream node, you have coupling you have not acknowledged.

None of those four questions is new. They are ownership, atomicity, projection and isolation, and the only novelty is that the thing violating them is a language model rather than a service.

What it costs, stated honestly

A graph is many loops, so a weak verifier now burns tokens in parallel instead of one at a time, and the bill scales with your fan-out rather than with your patience. Put a spend cap and a hard iteration bound on every cycle before it runs unattended, because a loop-back edge with a soft condition is an unbounded loop wearing a diagram.

Debugging changes shape too. The question stops being "what did the agent do" and becomes "which node made this call, on what state, and why did that edge fire", and none of that is answerable without tracing designed in from the first commit. Retrofitting observability onto a graph is worse than retrofitting it onto a monolith, because the interesting state is transient.

And the tooling is younger than the confidence around it. AutoGen's GraphFlow still carries the line in its own documentation that it "is an experimental feature" whose "API, behavior, and capabilities are subject to change", and it advises moving to a structured workflow only "when your task requires deterministic control, conditional branching, or handling complex multi-step processes with cycles". That is the same advice as everything above, arriving from the vendor's own docs.

The rule

The label is optional. I do not need the phrase "graph engineering" to build any of this, and neither do you, and the people pointing out that directed graphs of states and transitions have been computer science since before most of us started are correct.

The decision underneath it is not optional and it is sharper than the discourse around it. Every edge moves a routing decision from a model that decides at runtime, holding all the evidence, to you, deciding in advance holding none of it. That transfer is worth making far more often than agent maximalists admit, and far less often than a clean architecture diagram implies.

So draw the edges you would defend in a post-mortem, and leave the rest inside a node. Then watch which of your arrows keeps getting in the way, because that arrow is telling you the thing the diagram cannot: you made a decision you were not entitled to make.