A loop is what an agent does to make progress. A graph is what an operator builds to keep a long-running system out of trouble. The shift from one to the other is the most consequential design decision in any workflow that runs longer than a single turn.

Loops are forgiving. The agent decides what to do next; the operator decides when to stop. If the agent makes a bad call, the next iteration can recover. Loops are also opaque: the only way to know what the agent did is to read the transcript, and the only way to debug is to find the bad step. Loops work well for short, exploratory, single-agent work. They start to break when the work is long, the order of operations matters, or multiple agents need to coordinate.

Graphs are unforgiving. The operator decides what runs and in what order. If the graph is wrong, the workflow is wrong. The benefit is that every step is auditable, every transition is named, and every failure mode has a defined response. Graphs work well for workflows that have to be reliable, repeatable, and inspectable. They are the wrong shape for exploratory work where the order of operations is not known in advance.

This article is about the move from loop-shaped to graph-shaped systems in practice. It picks up where Loops vs Graphs left off and goes into the design patterns that have held up: when to keep a loop, when to build a graph, what a well-shaped graph looks like, and what collapses it back into spaghetti.

Why the shape matters

A workflow that is the wrong shape fails in characteristic ways. A loop-shaped workflow that should be a graph drifts: it does work that the operator did not intend, in an order the operator did not specify, with no way to interrupt except by killing the run. A graph-shaped workflow that should be a loop is rigid: it cannot handle the inputs the operator did not anticipate, and it produces a structured-but-wrong answer because the operator drew the boxes before the agent had a chance to think.

The shape matters because the operator's debugging story depends on it. A loop-shaped workflow's debugging story is "read the transcript and find the bad step." A graph-shaped workflow's debugging story is "look at the routing decision and ask whether the right node ran." The first is archaeology. The second is inspection.

For workflows that have to run repeatedly, that other agents have to integrate with, or that the operator has to debug in front of an executive, graph-shaped is usually the right answer. For workflows that are one-off, exploratory, or that the operator runs interactively with the agent, loop-shaped is usually fine.

What a state graph actually is

A state graph is a description of a workflow as nodes and edges, where the nodes are the things the workflow can do and the edges are the transitions between them. The "state" in state graph is the workflow's current position: which node has just run, what its outputs were, what conditions are now true.

A node has a contract:

  • A name.
  • A trigger condition (when the node runs).
  • An input shape (what data the node receives when it runs).
  • An action (what the node does).
  • An output shape (what data the node produces).
  • A list of edges to possible next nodes, with the conditions that select each edge.

An edge has a contract:

  • A source node.
  • A target node.
  • A condition that determines whether the edge is taken.

The graph as a whole has a contract:

  • An entry point (where execution starts).
  • One or more terminal nodes (where execution ends).
  • An initial state.
  • A state-update rule (how the workflow's state changes after each node).

That is the whole abstraction. Everything else is detail.

The detail that matters in practice is that the contracts are explicit. A node that "runs the agent" is not a well-shaped node; "runs the agent on the user's question and produces a draft answer in the standard format" is. The explicitness is what makes the graph inspectable.

When to keep a loop

A loop is the right shape when the workflow meets at least two of these conditions:

  • The next action depends on the previous result. The agent reads what it just produced and decides what to do next. A loop is the natural shape.
  • The order of operations is not fixed. The agent decides what to do based on the current state. A graph would have to enumerate every possible order, which is a maintenance burden the agent could absorb.
  • The work is exploratory. The agent does not know in advance what it will find. A graph would lock in steps that the agent might not need.
  • The operator is iterating interactively. The agent is doing the work in front of the operator, who can interject at any time. A graph's gates would slow the interaction.

A daily check-in loop, where the agent reads the day's tasks, decides what to do, does it, and reports back, is loop-shaped because the day's work is exploratory. The graph would have to enumerate every possible check-in, which is exactly what the operator is paying the agent not to enumerate.

When to build a graph

A graph is the right shape when the workflow meets at least two of these conditions:

  • The order of operations matters and is known ahead of time. The operator knows the workflow should go intake → classify → research → draft → review → publish. A graph makes this order explicit and inspectable.
  • Each step needs to be auditable independently. The operator wants to see what the research step produced, separate from what the draft step produced. A graph makes this possible; a loop does not.
  • Multiple agents or services need to coordinate. The intake agent hands off to the research agent, which hands off to the draft agent. Handoffs are easier to specify in a graph.
  • The operator wants guarantees about specific steps running. "Always run the review step before publishing" is a graph-level guarantee. In a loop, the agent could decide the review is unnecessary.

A publishing pipeline that takes a draft, runs a review pass, runs a fact-check pass, and publishes if both pass, is graph-shaped because every step is auditable and the order matters. A graph makes the fact-check step impossible to skip; a loop would let the agent decide it is unnecessary.

What collapses a graph into spaghetti

Three failure modes that turn a well-intentioned graph into an unmaintainable mess.

Edges that loop back without a clear condition. A node that sends execution back to a previous node "if needed" looks like a graph but behaves like a loop. The graph's promise of inspectability is gone because the routing is no longer explicit. The right pattern is to name the condition: "send back to research if fact-check found an unsupported claim" is auditable; "send back if needed" is not.

Nodes with overlapping concerns. Two nodes that both "process the input" are a sign that the workflow has not been decomposed correctly. The processing should be split into named, sequential steps with clear handoffs. Otherwise the graph has duplicated logic that the operator has to keep in sync.

State that lives in the agent's context instead of in the graph's state object. A node that "remembers what the previous node said" is relying on the agent's context to carry state forward. The graph's state object should carry state forward; the agent's context should be a tool the node uses, not the state itself. Without this discipline, the graph's state can drift from the agent's context in ways that are hard to detect.

Patterns that hold up

A few specific patterns that have worked across many setups.

Each node has a single output. A node should produce one thing — a draft, a critique, a fact-check verdict, a structured record. If a node produces two things, split it into two nodes.

Edges are named, not just connected. Every edge has a condition. The condition is checkable: "if the fact-check verdict is 'pass', go to publish; if 'fail', go back to draft." The graph's behavior is fully determined by its edges and their conditions.

The state object is small and explicit. The graph's state is a small JSON-shaped object, not a pile of context. The state contains the inputs, the outputs of each node, and the conditions that have been met. Every node reads from the state and writes to the state. The graph's behavior is fully determined by the state.

Terminal nodes are explicit. A workflow that "ends when the work is done" is a loop. A workflow that ends at a specific terminal node ("publish," "archive," "escalate to operator") is a graph. The terminal nodes name what success and failure look like.

Graphs are tools, not abstractions. The graph is a description of the workflow; the agent runs the workflow. The graph does not replace the agent. The graph says what runs and in what order; the agent does the work. Conflating the two — making the graph itself a smart system — produces a system that is too rigid to handle real inputs and too flexible to be auditable.

A worked state graph

Consider a workflow that produces a research brief from a question. The operator wants every brief to follow the same structure: question summary, three sources, fact-check, draft, review. The order matters. Each step is auditable.

A graph for this workflow:

  • Entry node: intake. Trigger: a question arrives. Action: parse the question, write a structured question object to state. Terminal if parsing fails (escalate to operator).
  • Edge: from intake to research if the question object is valid.
  • Node: research. Trigger: a valid question object in state. Action: run the research agent to find three sources that bear on the question. Write a sources object to state. Terminal if research fails (escalate).
  • Edge: from research to fact-check if three sources are present.
  • Node: fact-check. Trigger: a sources object in state. Action: run a fact-check agent that verifies each source supports the claim it is paired with. Write a fact-check object to state. Terminal if fact-check fails (escalate).
  • Edge: from fact-check to draft if all claims are supported.
  • Edge: from fact-check to research if any claim is unsupported (with the unsupported claim in the edge's payload, so the research node knows what to find).
  • Node: draft. Trigger: a fact-check object in state. Action: run a draft agent that produces the brief from the sources. Write a draft object to state.
  • Edge: from draft to review.
  • Node: review. Trigger: a draft object in state. Action: run a review agent that checks the brief against the source material and writes a verdict. Write a review object to state.
  • Edge: from review to publish if verdict is "pass."
  • Edge: from review to draft if verdict is "revise" (with the review's notes in the edge's payload).
  • Node: publish. Trigger: a review verdict of "pass." Action: write the brief to its destination. Terminal.

This graph has nine nodes and ten edges. Every edge has a named condition. Every node has a single output. The state object is a small JSON that grows as the workflow progresses. A failure at any node escalates to the operator rather than running away.

The graph is auditable: the operator can ask "did the fact-check pass?" by inspecting the state object, without reading any agent transcripts. The graph is inspectable: the operator can ask "what would have happened if the review had passed" by tracing the edges from the review node. The graph is debuggable: a bad brief can be traced back through the state object to the node that produced the bad output.

What graphs do not solve

Graphs do not solve the hard parts of agent design. They do not make a bad agent good. They do not make a slow agent fast. They do not make an agent that hallucinates stop hallucinating. They do, however, make the operator's debugging story legible: when something goes wrong, the operator can find the bad node by inspecting the state object, rather than by reading the transcript.

Graphs also do not remove the need for the agent. A graph that runs a node that does "process the input" with no further specification is a graph with a black box in it. The agent inside the node has to do the work. The graph's job is to put the agent in the right place at the right time with the right inputs, not to do the work itself.

The honest framing: graphs are an investment in inspectability and reliability. They cost more to design than loops. They pay back when the workflow has to run often, when other agents or operators have to integrate with it, or when the operator has to debug a bad run in front of an executive. For one-off work, the cost is not worth it.

Related reading