Graph Engineering: The Complete Guide

What Is Graph Engineering?

Graph engineering is the practice of designing a multi-agent system as an explicit graph: nodes (agents or deterministic steps, each with a single responsibility), edges (the routing between them — sequential, conditional, or parallel), and shared state (the object that flows along the edges, which every node reads and modifies).

If loop engineering makes one agent's behavior programmable — goal, check command, exit condition, retries — graph engineering makes the organization of agents programmable. A loop answers "how does this agent keep working until it's done?" A graph answers "which agents exist, who hands off to whom, and what happens when a branch fails?"

A useful degenerate case: a graph with one node is just a loop. That's why the two disciplines stack rather than compete — every serious graph is a graph of loops.

Why This Term, Why Now

The term crystallized on X around July 18, 2026, when Peter Steinberger — the same person whose posts helped popularize loop engineering — asked: "Are we still talking loops or did we shift to graphs yet?" Within a day, builders were describing agents as "graduating from while-loops to org charts."

Notably, no new capability shipped that week. The shift was conceptual: by mid-2026, single well-harnessed loops had become reliable enough that teams started running several at once — a researcher loop feeding a builder loop feeding a reviewer loop — and discovered that the hard problems moved to the wiring: routing, hand-off contracts, failure isolation, and state consistency between agents. Graph engineering is the name for designing that wiring deliberately instead of discovering it in production.

The Stack: From Prompts to Graphs

These layers get mixed up constantly online. From innermost to outermost:

• Prompt engineering — optimizing a single instruction to a model, one turn at a time.
• Context engineering — deciding what information (files, memory, retrieved docs) an agent sees before it responds.
• Harness engineering — designing the system one agent runs inside: tools, guardrails, permissions, observability. Agent = model + harness.
• Loop engineering — harness engineering applied to the retry-and-verify cycle: goal, check command, exit condition, max iterations. Full guide →
• Graph engineering — wiring multiple loops into an organization: nodes, edges, shared state, and the routing logic between them. This page is about this layer.

The Anatomy of a Graph

Every well-formed agent graph answers four questions — write them down before you wire anything:

• Nodes — what are the units of work, and does each one have a single responsibility and its own definition of "done"? A node that can't fail independently isn't a node; it's a hidden dependency.
• Edges — for each node, what triggers the next one? Sequential (always), conditional (if the check passes), or parallel (fan-out to many, fan-in to a join point)?
• Shared state — what object travels along the edges? Every field a downstream node needs must be written by an upstream node — graphs force you to admit how much of the workflow you haven't actually modeled yet.
• Failure routing — when a node's loop exhausts its retries, where does control go? Back one step, to a fallback node, or up to a human? A graph without failure edges is a diagram, not a system.

The Org Graph and the Work Graph

A framing that stuck from the original thread: mature systems actually run two graphs at once.

• The org graph is stable and long-lived — specialized agents that own a domain (the reviewer, the researcher, the deploy agent), keep durable context, and exist across many tasks. Think org chart.
• The work graph is dynamic and ephemeral — the task DAG spawned for one job, where nodes appear, fan out, merge, and disappear based on what the work actually turns out to require. Think project plan.

Confusing the two is the most common early mistake: hardcoding today's task decomposition (work graph) into your permanent agent roster (org graph), then wondering why every new task fights the structure.

Named Graph Patterns

A few shapes show up again and again:

• Pipeline (sequential hand-off) — researcher → writer → reviewer. The simplest graph; each node's output is the next node's input.
• Fan-out / fan-in — one node spawns many parallel workers (one per file, per test failure, per data source), and a join node merges the results. The workhorse pattern for anything embarrassingly parallel.
• Orchestrator–workers — a planner node with a stronger model decomposes the task and routes sub-tasks to cheaper worker nodes, then integrates. The multi-agent version of "think slow, act fast."
• Council / judge panel — several nodes attempt or evaluate the same task independently, and a judge node (or majority vote) picks the winner. Buys reliability with redundancy.
• Loops-within-nodes — any node can contain a full retry-and-verify loop internally — a Ralph-style loop, a test-until-green loop — invisible to the rest of the graph. This is the composition rule that makes the whole stack work.

Do You Actually Need a Graph?

The honest, deflating answer: often not yet. Signs a single loop is still enough — one agent with good context can hold the whole task; failures are cheap to retry from scratch; there's no genuine parallelism to exploit. Signs you've outgrown it — hand-offs between phases keep getting lost in one long context; different phases want different models or permissions; one slow sub-task serializes everything; a failure in step 7 forces a restart from step 1.

The pragmatic path is incremental: get one loop reliable, then wire a second one to it with an explicit hand-off, and only reach for a framework when the wiring itself becomes the bug source.

Frameworks

Graph orchestration predates the term. LangGraph is the most direct implementation — you define a StateGraph, add nodes, add edges, and the runtime manages state persistence, conditional routing, and rollback. Microsoft AutoGen's GraphFlow, Google's Agent Development Kit (ADK), and CrewAI cover the same ground with different trade-offs. And agent-native runtimes are converging on the same shape: Claude Code's built-in loop primitives compose into exactly these pipelines and fan-outs. If you've used any of them, you've been doing graph engineering under a different name.

Getting Started

Graphs are built from working loops, so start where the leverage is: make one loop reliable, then wire from there.

• Pick a proven single-agent loop from MCP.so's Loops directory — e.g. Test Until Green or Ship PR Until Green — and run it until it's boring.
• Add one hand-off: a second loop that consumes the first one's output through an explicit state file or PR, with its own check command.
• Only then formalize: move the wiring into LangGraph or your runtime's native workflow support, keeping each node's loop contract (goal, check, exit, retries) intact.

The loops are the muscles; the graph is the skeleton. Browse the full set of ready-to-run loops at MCP.so Loops — each ships with the kickoff prompt, check command, and exit condition a graph node needs.