Graph Engineering

Do not start by drawing boxes

You may be thinking: “My workflow is getting complex, so I should put every step into a graph.” A graph is useful only when it makes responsibility, state, routing and authority clearer. Drawing boxes around an unclear workflow gives you a more impressive picture of the same ambiguity.

Try this before adding a framework

1. Take one working delegated loop from Give AI Work.
2. Write every responsibility and every possible next state on paper.
3. Circle any transition whose reason is “the agent decides.”
4. Mark every irreversible action and every place where two responsibilities can modify the same real-world state.
5. Those circles and overlaps are the first places where Graph Engineering earns its keep.

Common traps

• Agent multiplication: creating planner, researcher, writer and reviewer agents because more agents feels more advanced.
• Hidden routing: the graph looks explicit, but the most important next-step decision still lives inside an LLM prompt.
• Retry theatre: failed nodes loop back without changing evidence, state, strategy or retry budget.
• Fan-out without fan-in: several workers produce answers, then another model is simply told to “combine them.”
• Rubber-stamp approval: a human gate exists, but the person receives too little evidence to make a meaningful decision.
• Metric capture: every node succeeds while the real business outcome quietly gets worse.

Look out for

• You cannot explain why a particular edge was chosen using visible state.
• Two nodes use the same field but mean different things by it.
• Parallel workers touch the same files, customer record or external resource.
• The number of retries increases but the failure evidence does not change.
• Human approval appears on almost every path and becomes automatic clicking.
• The graph has good local metrics but nobody owns the global outcome.
• More orchestration cost is being added without measurable reliability or business-value gain.

Prove the first lesson

Inject one missing-information case and one conflicting-output case. You should be able to explain, from recorded state and explicit rules, why the graph took each route, who had authority at each transition and what evidence allowed or blocked progress.

A graph is an explicit workflow contract

Graph Engineering starts when relationships between responsibilities become the thing you need to engineer. You can implement the graph in ordinary code first; the architectural discipline matters more than the orchestration framework.

First: should this even be a graph?

Graph vs. workflow

Your first explicit graph

START
  ↓
PLAN
  ↓
MAKE
  ↓
VERIFY ── fail ──→ REPAIR ──→ VERIFY
  │
 pass
  ↓
HUMAN GATE ── reject ──→ REPAIR
  │
 approve
  ↓
DONE

The diagram is not the implementation. Its job is to force hidden behavior into named responsibilities and explicit routes before framework code obscures the design.

Write each node like a contract

Node: VERIFY
Input:
  - proposed_change
  - acceptance_criteria
  - repository_state

May:
  - run tests
  - inspect changed files
  - read logs

May not:
  - silently rewrite requirements
  - approve on confidence alone

Output:
  - status: pass | fail | blocked
  - evidence[]
  - reasons[]
  - recommended_next_route

Fan-out is easy. Fan-in is the engineering.

Parallel agents often look impressive because several workers return quickly. The difficult part is deciding how conflicting outputs become one next state.

The graph can be correct and the business can still lose

This is where Graph Engineering becomes Run AI. A graph may execute every node successfully and still optimize the wrong thing. Booking agents can maximize appointments while show-up quality falls. Content agents can maximize output while brand trust falls. Support agents can minimize handling time while repeat contacts rise.

Look out for when the graph reaches production

• Blindness upward: every node follows its goal correctly but nobody is allowed to ask whether the goal itself should change.
• One loop improves its own metric by pushing work or risk into another loop.
• The proxy metric becomes easier to optimize than the actual outcome.
• No node has permission to question whether the target itself is still correct.
• The graph becomes so complicated that human review becomes the slowest and most expensive node.
• Nobody can reconstruct what happened after a customer, operator or auditor asks “why?”

Continue in Run AI: trust, ownership, recovery, trace, measure and release →