Why graphs

In this chapter, we will learn when a loop is the wrong tool and a graph is the right one. We will take Sean Chen's definition apart, name the signs that your loop wants to be a graph, and build the pattern catalogue: sequence, fan-out and fan-in, map, router, review cycle, repair path, and sub-graph, with the names the industry uses for the same shapes. By the end you will look at a task and see its graph before you write a line.

The definition, taken apart

A loop discovers what to do next. A graph pre-determines what happens next. In a loop, the model reads the history and chooses: call this tool, or answer. The order of work emerges from those choices, and it can be different every run. In a graph, the order is fixed by the author: this node, then these three at once, then that one, then a review. The model works inside each node, where it still discovers, but it does not decide the shape of the whole.

loop     flexible, exploratory, cheap to write, hard to predict; cost and latency vary with the model's choices
graph    predictable, parallel, testable node by node, more to write; the model cannot skip the review

Neither is better. A loop is right when you do not know the steps. A graph is right when you do, and the whiteboard's graph board draws the moment that changes: one prompt, one agent that plans, six agent loops working at once, a review, a final answer.

Signs your loop wants to be a graph

1. the task has stages you could name            find, then compute, then write
2. parts of the work do not depend on each other  three sections, five tickets, forty files
3. something must happen every time               a review, a test run, a policy check, no matter what the model thinks
4. different stages want different tools          a reader with read_file; a writer with none; a checker with shell
5. the loop flails or bloats                      Chapter 8's problems 2 and 4 are often a missing structure
6. you want to see where the time and money go    a graph reports per node; a loop reports per step

Sign 3 is the strongest. In a loop, the model may decide it is done and skip the test. In a graph the test is a node on the path to END, and the model cannot route around it.

The pattern catalogue

Seven shapes cover nearly every graph you will build. Pick one below and read its text form; the engine in Chapter 10 runs exactly these lines.

The names in the third column are the ones you will meet in other frameworks and papers. They are the same shapes. "Orchestrator-workers" is a planner node that produces a list, a map node that runs a worker per item, and a merge node. "Evaluator-optimizer" is a review cycle. "Handoff" is a router whose targets are loops with different system prompts and tools. Learn the seven shapes and the names stop mattering.

The whiteboard's graph as code

Prompt, Agent, Agent Loops A to F, Review, Final: a planner, a fan-out, a fan-in, a review cycle. In agl's text form:

g = Graph.from_text("""
    START -> plan
    plan -> loop_a, loop_b, loop_c, loop_d, loop_e, loop_f     # one wave, six loops in parallel
    loop_a, loop_b, loop_c, loop_d, loop_e, loop_f -> edit     # fan-in: edit waits for all six
    edit -> review
    review ?pass-> END
    review ?fail-> edit                                        # review cycle
""", nodes={...}, routers={"review": lambda s: "pass" if s["ok"] else "fail"})

One node is on the board only by implication: edit, the step that makes one thing out of six. Six loops that never see each other cannot produce one coherent result, however good each is; a reviewer that judges their stapled output will fail it every time. Whenever a goal needs information that no single node has, add the node that has it. This is the first design rule of graphs, and Chapter 12 shows what happens when you forget it.

Composing patterns

Real graphs are two or three patterns joined.

course builder     sequence (outline -> write -> assemble) + map (one writer per chapter) + repair path (build check -> fix)
support triage     router (classify) + sequence per branch + review cycle (policy check)
research report    map (one researcher per question) + fan-in (synthesise) + review cycle
code review bot    sequence (read diff -> propose) + review cycle (second model) + repair path (tests)

Draw the patterns first, then write the nodes. A node is a function of the state; most are a loop with a prompt template, some are plain Python, a few are another graph.

What a graph costs you

More code, less surprise. A graph is more to write than a loop: nodes, edges, state keys, a router function. It repays that when the task runs more than a handful of times, when parts can run in parallel (three writers take the time of one), when something must happen every time, and when you need to know which stage is slow or expensive. For a one-off exploratory task, write a loop.

Priya sees her graph

Priya's course builder was never one loop. She had drawn a researcher and a writer in Chapter 3 and noticed one fed the other. Now she writes the shape: outline (a planner), write (a map of one writer per chapter), assemble (plain Python), build check (the site's own validator as a node), and a fix node on the fail path. Three patterns. Each node gets only the tools it needs: the writers get none, the build check gets a subprocess. Her flailing problem from Chapter 8 disappears with the structure, because no node has a reason to wander.

Try it yourself

Take a task you do often and write it as patterns from the catalogue, in the text form, before you know how any node works. Then mark each node: a loop with a prompt, plain code, or another graph. Count the nodes that can run in the same wave. If the answer is none, ask whether it needs to be a graph at all.

Common questions

Is a graph just a workflow engine?

The engine part, yes: nodes, edges, state, parallel execution. What makes it an agent graph is that nodes are loops, so each step still discovers within its scope, and that evaluators and routers decide the path from what the loops produced.

Where does the planner's intelligence go?

Into the plan node: a loop that produces a list or a plan as structured output, which the map node then executes. The planner decides what; the graph decides how and in what order.

What about multi-agent "conversations" where agents talk to each other?

They are a graph with a cycle between two loops and a router that decides when to stop. Drawing it as a graph makes the stopping rule explicit, which is the part those systems usually get wrong.

Should every graph end with a review?

Every graph whose output matters should end with an evaluator the model cannot skip: a test run, a build, a judge. That is the whole reason sign 3 is the strongest.

Can a graph change its own shape at run time?

Within limits: routers pick among drawn paths, and a map node runs as many branches as the list has. The set of possible paths is still fixed and drawn, which is what makes the graph testable.

Carry this

• A loop discovers; a graph pre-determines. Use a graph when you know the stages, when work is parallel, or when something must happen every time.
• Seven patterns: sequence, fan-out/fan-in, map, router, review cycle, repair path, sub-graph. The industry names are the same shapes.
• If the goal needs information no single node has, add the node that has it.
• Real graphs are two or three patterns joined. Draw the patterns, then write the nodes.

Check yourself

1. Name the strongest sign that a loop should be a graph.

Answer

Something must happen every time (a review, a test, a policy check). In a graph it is a node on the path to END and the model cannot skip it.

2. Which catalogue pattern is "orchestrator-workers"?

Answer

A planner node producing a list, a map node running one worker per item, and a merge node after the fan-in.

3. Which node does the whiteboard's graph board leave implicit, and why does it matter?

Answer

The edit (merge) node between the fan-in and the review. Six loops that never see each other cannot produce one coherent result; the node that sees all six is what makes the review passable.