From loop designer to Graph architect: the 13-step roadmap

Most builders still wire their agents by hand. They write a function, call the next one from inside it, add an if when it branches, add a try when it fails, and ship it. It works. It keeps working right up to the run that dies on step nine.

Almost none of them can answer the question that follows: what exactly did it have to redo?

No validation, no checkpoint, no resume, no trace. A while loop has a counter and a body. It cannot tell you which part succeeded, cannot restart from the middle, and cannot be checked before it runs. You learn the shape of your own control flow by watching it execute.

The leverage point has moved. Not from prompting to looping this time, but one floor up again: from writing the steps to declaring the shape they run in.

This is the 13-step roadmap from loop designer to graph architect. Not sourced from a vendor blog: everything below runs. The engine is about 150 lines with no framework, the terminal output near the end is real, and every code block in this article is a line lifted from the file that produced it.

Three tiers: work out whether you actually need a graph, learn what a node and an edge have to be, then build the smallest runtime that can check itself.

Tier 1 - Nodes

01. Find the seam where one loop does three jobs

Before you draw anything, look for the function that decides, acts, and evaluates in one pass. That function is not a node. It is three nodes that have not been separated yet.

The tell is the word “and” in your own description. “It searches and ranks them.” “It writes the draft and checks it.” Every “and” is a seam.

Split on the seams, not on the file structure. A 200-line function that does one job is one node. A 20-line function that does two is two.

02. One job per node, one output shape

A node earns its name by being describable without a conjunction.

That is the whole node. It takes a claim and produces queries. It does not search. It does not decide what to do next. If it did either, the graph would lose the ability to route around it.

The output shape matters as much as the job. Every node returns the same type, a State, differing only in which fields it touched. That uniformity is what lets the runtime treat nodes as interchangeable black boxes.

03. Pure nodes: state in, state out

First gate.

A node that reads a global, mutates a shared object, or writes to disk cannot be replayed, cannot be tested alone, and cannot be safely retried. Every capability in Tier 3 depends on this one property.

Note frozen=True and note that every collection is a tuple. Both are deliberate. A frozen dataclass makes accidental mutation an error at the moment it happens rather than a mystery three nodes later, and immutable collections mean a checkpoint is a real snapshot rather than a reference to something that keeps changing underneath it.

A node that mutates cannot be replayed, and a node that cannot be replayed cannot be resumed.

04. Version the state before the second node

Add the version field while you have one node. It costs nothing now and it is very hard to add later, once checkpoints from three schema generations are sitting in storage.

The failure this prevents is specific: you change a field name, deploy, and a resume operation loads a checkpoint written by the old code. Without a version field the load succeeds and produces silent nonsense. With one it fails loudly at the boundary.

Tier 2 - Edges

05. Static edges first, conditional edges only at real branches

Most edges in a working graph are boring. Search always goes to rank. Rank always goes to write. Make those static, because a static edge is a fact the runtime can verify without running anything.

Four lines, and now four fifths of your control flow is machine-readable. Reserve conditional edges for places where the decision genuinely depends on state. In this agent there are exactly two.

06. The router is a node, not a buried if

This is the step that decides whether the rest of the roadmap is available to you.

A conditional that lives inside a node body is invisible. The runtime cannot see it, the validator cannot walk it, and the diagram you draw for your teammate is a guess. Lift it out, and make it declare where it can go.

The targets argument is the part people skip, and it is the part that pays. A router function is opaque: you cannot know its possible return values without executing it against every state. Declaring them turns an opaque branch into a checkable edge.

Two lines of bookkeeping. In exchange, step 09 becomes possible.

07. Every cycle needs a visit cap

Second gate.

Cycles are the reason to build a graph at all. They are also the reason graphs hang. The refinement edge in this agent sends unverified claims back to be researched again, which is exactly right until the day nothing can be verified and the graph discovers that fact forever.

The cap does not live in the router. It lives on the node.

Per-node rather than global, because different nodes deserve different budgets. A refinement node might reasonably run twice. An entry node running twice means something is badly wrong.

I tested this by deleting the exit condition, replacing the router with one that always loops:

Eighteen nodes and a clear message, instead of a process you notice an hour later on the billing page.

08. Fan-out needs a declared join policy

The moment one node has two outgoing edges that both fire, you have committed to answering a question: what happens when they come back?

Decide it explicitly and write it down. There are only a few honest answers. Take the first to finish and cancel the rest. Wait for all and merge. Wait for a quorum. Take the highest scoring.

The failure mode is not choosing. An undeclared join becomes whichever behaviour your code happened to have, and it will differ between the happy path and the retry path.

Tier 3 - Runtime

09. Validate the graph before it runs

Third gate, and the payoff for step 06.

Because every edge is data and every router declares its targets, the whole graph can be walked without executing a single node.

I pointed one edge at a node that does not exist and removed another node’s only exit. The validator found both, plus the four nodes that became unreachable as a consequence, in under a millisecond and without an API call.

Every one of those is a bug that a loop would have surfaced at runtime, mid-run, after spending money.

10. Checkpoint after every node

One line in the runtime loop.

The instinct is to checkpoint at milestones, because checkpointing feels expensive. It is not. State is immutable, so a checkpoint is a reference, not a copy. Storing one per node costs almost nothing and it is the difference between resuming from where you were and resuming from an approximation of where you were.

11. Resume from the last good node

The trick is the third line. A checkpoint tells you the state, but not where to go next, because the routing decision depends on state you now have. So you re-run the routing function, which is cheap and pure, and skip the node bodies, which are neither.

Resuming this run from checkpoint 5 replayed 14 nodes instead of 19. In a real agent the nodes you skip are the ones that made the model calls.

12. The trace is the graph, replayed

Observability for a graph is not a logging concern. It falls out of the runtime for free, because the runtime already knows the node name and the elapsed time at every step.

Four fields. What they give you is a list of visited nodes in order, which is the same thing as the path taken through the graph. You do not need to reconstruct what happened from log lines. The trace is the path.

13. Send the failure back as an edge

The last step is the one that makes it a system rather than a diagram.

When a node raises, the runtime does not stop. It writes the error into state and lets the graph route on it.

A failure becomes a value, and a value can be routed. That is what lets after_verify send an errored run straight to publish instead of into another refinement cycle that will fail the same way.

The same principle covers the successful-but-incomplete case. The unverified claims from step 12 of the previous article become the new claim in this graph:

That single node is the edge that closes the graph.

Conclusion: The lever has changed

But the honest version of this is not that everyone should go build a graph. Most agents do not need one yet. Not until the control flow actually branches on state, not until there is a cycle you cannot bound in your head, not until a mid-run failure costs more than a full restart, and not until more than one person has to understand the path. Miss one of those and the graph is ceremony: you have paid for a runtime to describe a straight line.

The test is blunt. If you can draw your agent’s control flow on a napkin and be confident it is complete, you have a loop, and a loop is the right answer. If you cannot, you already have a graph. You just have not written it down where the runtime can read it.

If you pass the test, build small. One state schema. One pure node. One declared router. One visit cap. Get a node replayable before you checkpoint it. Get the edges declared before you validate them. Get validation working before you build resume. Order matters here more than anywhere else in the roadmap, because every capability in Tier 3 is a consequence of a decision made in Tier 1. Skip ahead and you get a runtime that reports confidently on a system it cannot actually see.

The point is not that agent work got easier. It is that the leverage point moved again. Draw the graph. Stay the engineer.