Agentic graphs: modelling agents as a graph

An agentic graph is a way to describe an agent system as a directed graph. The nodes are the units of work, an agent that implements a story, a step that runs tests, a tool call that queries a database, and the edges are the connections between them, carrying two things at once: control flow (which node runs next) and data flow (what result gets passed along). Draw it and you get a diagram of your system: boxes for the work, arrows for how work moves and what it carries.

The reason this framing matters is that it separates two questions people usually tangle together: what are the steps and how are they wired. The nodes answer the first; the edges answer the second. And once edges are first-class, you can express wiring that a plain sequence cannot, an arrow that splits into two parallel arrows, two arrows that merge into one, or an arrow that points back to an earlier node.

There are two important shapes. A DAG, a directed acyclic graph, has no cycles: every path flows forward and eventually ends, which makes it easy to reason about and guarantees termination. A cyclic graph allows loop-back edges, a node can send work backward, and that is what lets an agent retry or refine. Cyclic graphs are almost always paired with a state store the nodes read from and write to, because a loop needs somewhere to remember what it already tried. This whole vocabulary is the structural layer under any real agentic workflow.

The simplest agent design is a linear chain: prompt, tool, parse, respond, one step after another. It is the right model for a task that genuinely is a straight line. Most real work is not. The moment a task involves doing two things at once, choosing between options, or trying again on failure, the straight line has to be bent, and a graph is what you get when you stop pretending it is straight.

Four capabilities are the reason to reach for a graph. Each is awkward or impossible in a pure chain and natural as an edge type:

The deeper point is that the graph is not a different tool from the chain, it is the more general one. Every linear chain is a graph that happens to have a single path. Adopting the graph model costs you nothing on simple tasks and gives you a place to put parallelism, routing, and loops the moment a task needs them, instead of retrofitting them into a design that assumed one path.

Most agentic graphs are built from a small vocabulary. Learn the handful of node types and edge types below and you can read, or draw, almost any agent system, because complex graphs are just these pieces composed.

Edges are simpler, there are four kinds, and any graph is some arrangement of them:

Abstractions land better on a concrete case, so here is a graph for shipping a feature that has several independent stories. It uses every building block above: a planner, fan-out to parallel workers, tool and evaluator nodes, a loop-back edge on test failure, and a join at the end.

            ┌─────────────┐
            │  spec node  │  turn the feature into stories + acceptance criteria
            └──────┬──────┘
                   │ fan-out (one edge per story)
        ┌──────────┼───────────┐
        ▼          ▼           ▼
   ┌────────┐ ┌────────┐  ┌────────┐   parallel implementation
   │ story  │ │ story  │  │ story  │   subgraphs (isolated)
   │ worker │ │ worker │  │ worker │
   └───┬────┘ └───┬────┘  └───┬────┘
       ▼          ▼           ▼
   ┌────────┐ ┌────────┐  ┌────────┐
   │  test  │ │  test  │  │  test  │   tool node runs the suite
   └───┬────┘ └───┬────┘  └───┬────┘
       ▼          ▼           ▼
   ┌────────┐ ┌────────┐  ┌────────┐
   │  eval  │ │  eval  │  │  eval  │   evaluator: pass or fail?
   └───┬────┘ └───┬────┘  └───┬────┘
       │ fail ↑   │           │        loop-back edge on failure
       └─(back to worker, up to N tries)
                   │ pass (fan-in / join)
                   ▼
            ┌─────────────┐
            │   PR node   │  open one PR per story, review, merge
            └─────────────┘

Reading it top to bottom: the spec node decomposes the feature, then a fan-out edge launches one implementation subgraph per story so they run in parallel. Inside each subgraph, a worker writes the code, a tool node runs the test suite, and an evaluator checks the result. On failure, a loop-back edge returns the story to its worker to try again, bounded by a retry cap. On pass, the subgraphs join and each ends at a PR node. The same idea, expressed as steps rather than a diagram:

1. 1

   Spec node (planner)

   Decompose the feature into independent stories, each with acceptance criteria. This node defines how wide the fan-out will be.
2. 2

   Fan-out to parallel story subgraphs

   Emit one edge per story. Each story becomes its own bounded subgraph running concurrently, and crucially isolated, so the branches don't contend on the same files.
3. 3

   Worker + tool node inside each subgraph

   The worker implements the story; a tool node runs the tests. Keeping test-running as its own node means the result is data the graph can route on, not a hidden side effect.
4. 4

   Evaluator with a loop-back edge

   The evaluator passes or fails the result. Fail follows the loop-back edge to the worker (bounded by a max-retries stop condition); pass moves forward.
5. 5

   Join at the PR node

   Passing subgraphs fan back in: each opens one reviewed PR. The join is the single place that knows all stories are done and the feature is ready to merge.

Nodes need to share information, and there are two common patterns for it. Shared state, a blackboard, is a single object every node reads from and writes to; it is simple and gives every node the full picture, but it couples nodes and makes concurrent writes a hazard. Message passing sends explicit results along edges; nodes stay decoupled and only see what they are handed, which is safer for parallel branches but means state has to be threaded deliberately rather than assumed. Many real graphs mix the two: a blackboard for durable facts, messages for the results flowing along edges.

Whichever you choose, state is what makes a loop meaningful, and it is also what makes a loop dangerous. A loop-back edge with no stop condition is an unbounded cycle: an evaluator that never quite passes, a worker that keeps making the same mistake, and the graph spins forever, burning tokens and money with nothing to show. This is the single most important discipline in cyclic graphs, tie every loop to an explicit exit.

A graph is a model, not a library. You can express one in plain code: functions are nodes, your control flow is the edges, and a dictionary is the shared state. That is worth doing once, because it makes clear that the graph lives in your design, not in a dependency.

That said, several libraries model agent systems explicitly as graphs and give you a runtime for them: a way to declare nodes and edges, a state object that flows through the graph, cycle support with stop conditions, and often a visualizer. Once your graph has many nodes, conditional routing, and cycles, that machinery earns its place, hand-rolling a scheduler and a state store gets old. The point to hold onto is that these tools implement the same node-and-edge model described here; they do not replace the design work of slicing your system into nodes with clear inputs and outputs. Get the graph right on paper first, then pick a runtime, or write your own, to execute it.

Graphs add power, and each new edge type comes with its own way to go wrong. Three failures account for most broken agent graphs, and all three are prevented by design, not by a smarter model.

Notice how much this overlaps with running several agents by hand: contention between parallel branches is exactly the collision problem the multi-agent coding workflow solves with story slicing and isolation, and bounding loops is core to any durable AI agent harness. A good graph borrows those guardrails rather than reinventing them.

AIDEN's board is an agentic graph made concrete for coding, and it is built precisely around fan-out and fan-in. An epic is the planner node: it fans out to parallel stories, and each story runs in its own git worktree, so the parallel branches are isolated by construction and cannot contend on shared state, the very failure mode from the previous section, designed out rather than hoped away. The mechanics of that isolation are covered in parallel agents with git worktrees.

Each story is a bounded subgraph. It starts at an approved spec (the spec-approval gate is the stop condition on scope, no agent runs until you sign off), an agent, a Claude Code or Codex CLI, does the work in its worktree, and the subgraph ends at a reviewed pull request. When those PRs merge, the stories join back into the trunk. That is fan-out to isolated branches and fan-in at review, the exact shape of the worked example above, without hand-wiring a graph runtime. AIDEN drives your existing CLIs and your own inference; the board is the graph, and the worktree-per-story plus approval gate are its guardrails. The broader picture of specs, harnesses, and review is agentic engineering; how the same board orchestrates Claude Code specifically is in Claude Code orchestration.