graph-engineering

Graph Engineering

This is a design principle for weaving work that cannot be done with a single agent's loop into a graph where specialized nodes exchange shared state. Source: Shirley, "Graph Engineering Guide (2026)", AI Builder Club (2026-07-20, updated 2026-08-28) — https://www.aibuilderclub.com/blog/graph-engineering-guide-2026

Key line: The label is optional; only the transition from "one loop → coordinated graph" is real. Do not bring out a graph before it is needed.

0. Terminology

말	뜻
Node	A unit that does work. Usually a specialized agent or a deterministic step
Edge	A path between nodes. Straight line, conditional branch, fan-out (simultaneously into multiple branches), fan-in (merging branches back together)
Shared state	An object that flows along edges. Every node reads and writes it. It grows as it flows
Loop	A single agent receiving a goal and a pass threshold, choosing its own path, and repeating

A loop is a graph with an edge attached to a single node that returns to itself. So going from a loop to a graph is a matter of increasing nodes and edges.

The difference between a loop and a graph is "who decides the path." In a loop, a person sets only the goal and the pass threshold, and the agent chooses the path. In a graph, a person declares the valid paths and branching conditions, and the agent's freedom exists only within each node .

1. Five layers — the graph is the top layer

층	Focus	Question asked
1. Prompt	A single request	Are you asking well?
2. Context	What the model sees	Does it have the right information?
3. Harness	Tools, memory, scaffolding	Can it act and remember?
4. Loop	Repetition of a single agent	When does it check its own work and stop?
5. Graph	Coordination of multiple agents	Who does what, in what order, sharing what state?

If the lower layers are shaky, the upper layers only amplify the problem. If a single loop cannot verify itself and stop, splitting that loop into nodes will not solve it. Build the loop properly first.

2. Conditions for bringing out a graph

The default is a loop. Honestly examine the six signals below one by one. All six do not need to hold, but If most of it is on the loop side, don't build a graph. If you use a graph then, a two-hour job becomes a two-day framework construction project. If only one signal is triggered, first check whether it can be handled inside the loop (e.g., adding a verification step at the end of the loop).

Task shape — The work is divided into different areas of expertise and results are handed off.
Parallelism — Multiple steps must run simultaneously (fan-out) and results must be merged back together (fan-in).
Different tools/models — Each node requires a different tool set or model.
Control flow — The paths between roles must be explicit and auditable.
Failure isolation — One node breaking must not contaminate the rest.
Separated verification — A dedicated reviewer is needed to separately inspect the results of other nodes.

Reversal test: If merging several nodes into a single agent's loop does not reduce what can be done, merge them.

3. Design procedure (before code)

First try whether it can be maintained as a loop. Write down the reason it can't, using the condition numbers from Section 2. If you can't write one down, go with the loop.
Only name a node when it is a genuine area of expertise. The criteria are a different model, a different tool set, or a read-only reviewer. Things that are merely one step of a single loop, like "summarizer" or "formatter", are not nodes.
Draw the edges before coding. Sketch the paths, conditional branches, and back edges.
Explicitly design the shared state object. Decide, field by field, what each node reads and what it writes.
Give the reviewer node teeth. It must be a read-only verifier, separate from the writing node. If it fails, there must be a conditional edge that returns to the writing node. A structure where the writer grades its own results is not a reviewer.
Isolate failures. Ensure that even if one node fails, the shared state is not contaminated. Writes should go only to its own fields, failures should be left in the state as a "failed" marker, and partial results should not be overwritten.
Don't build the framework yourself; choose one. For example: LangGraph, Google ADK, Microsoft Agent Framework. Within Claude, subagents (Agent) and workflow scripts are this framework.
Set spending caps and forced termination conditions. A graph is a structure where multiple loops run simultaneously, so if verification is weak, tokens leak in parallel. Put a cap on the number of nodes, put a maximum iteration count on each back edge, and stop when the overall cost cap is exceeded.

4. Deliverable — Graph specification (write this first before implementation)

목표: <한 문장>
왜 루프가 아닌가: <2절 조건 번호와 구체적 이유>

노드:
  - <이름>: 하는 일 / 모델 / 도구 / 읽는 필드 / 쓰는 필드 / 읽기 전용?
엣지:
  - A -> B                       (직선)
  - A -> {B1, B2, B3} -> C       (팬아웃 → 팬인)
  - Reviewer --합격--> Ship
  - Reviewer --불합격--> Writer  (최대 N회)
공유 상태: { task, <필드>: <누가 쓰나>, ... }
실패 처리: <노드 실패 시 상태에 무엇을 남기고 어디로 가나>
상한: 노드 <K>개, 지출 $<X>, 고리당 최대 <N>회, 전체 시간 <T>
한 호흡 설명: <그래프 전체를 한 문장으로>

If you can't write a "one-breath explanation", the graph is too big.

5. Basic skeleton — research → write → review

[Researcher] --{task, notes}--> [Writer] --{task, notes, draft}--> [Reviewer]
                                   ^                                  |
                                   +----------- 불합격 ---------------+
                                                                      | 합격
                                                                      v
                                                                   [Ship]

The Researcher gathers sources and writes notes.
Writer는 {task, notes}receives and writes a draft.
Reviewer는 {task, notes, draft}receives and scores against the passing threshold. If it fails, it sends it back to the Writer.
The state grows as it flows. Each node adds its own fields to the state it receives and passes it on.

6. Over-engineering warning

	예	Verdict
Over-engineering	For "summarize this PDF," five nodes: fetcher → chunker → summarizer → reviewer → formatter	A single loop is faster and cheaper. The nodes do not have different models, tools, or verification roles
Appropriate	Daily market brief: the researcher uses five sources as parallel fan-out → the synthesizer fans in → the writer writes a draft → a skeptical reviewer sends it back if it fails	Each node does something a single loop cannot (parallel collection, separate verification)

The success criterion is not the number of nodes. The criterion is "every node does something a loop cannot, and the whole can be explained in one breath."

7. What graph engineering is not

It is not a knowledge graph or GraphRAG. That is data modeling; this is execution modeling.
It is not a new capability. Directed graphs and state machines have existed for a long time (LangGraph, AutoGen GraphFlow, Google ADK, etc.). What is new is the common name and the perspective of seeing this as a design technique distinct from loop design.
It is not the default option. Most work still ends with a single loop.

8. Review checklist (check all when designing or reviewing)

Did you write the reason a loop will not work using the condition numbers in Section 2, and are most of the six signals on the graph side?
Does each node have one of: a different model, a different tool, or a read-only role? Did you merge nodes that do not?
Did you draw the edges (including branches and feedback loops) before the code?
Is the write owner for each field of the shared state defined?
Is the reviewer read-only and separate from the writer, and is the failure path actually connected?
If one node fails, are the results of the other nodes preserved?
Did you use an existing framework instead of a hand-built orchestrator?
Are the node count cap, spending cap, maximum iterations per loop, and total time cap hard-coded?
Can you explain the entire graph in one sentence?

If even one is empty, do not implement it; fix the specification (Section 4) first.