A graph is a collection of nodes (steps) and edges (typed transitions) that an agent moves through. Each node is a piece of work. Each edge is the rule that decides what comes next. The graph is the structure around the work; the work is still done by loops inside each node.

In agent work, graphs are how non-trivial workflows stay auditable, branchable, and reusable. They are not a replacement for loops. They are a structure that loops live inside.

This piece is the beginner-level introduction. It assumes no prior agent knowledge.

The shape of a graph

Every graph in agent work has the same basic anatomy:

  • Nodes. Each node is a step — read a file, call an API, run a sub-agent, ask the model to summarize, persist a result.
  • Edges. Each edge is a typed transition — "on success go to node B," "on failure go to node C," "on timeout go to node D."
  • State. The graph may carry state between nodes — a status, a payload, a counter, a ticket.
  • Terminal nodes. Some nodes are terminal. The graph ends when the agent reaches one.

A graph that has only one node and unconditional edges is just a loop wearing a uniform. A graph that has typed edges, multiple terminal nodes, and durable state is doing something a loop cannot easily do.

The piece on Basic State Graphs and Workflows treats the implementation side. The piece on Loops vs Graphs treats the threshold between them.

Why graphs matter in agent work

A loop makes the next step implicit. A graph makes it explicit. That difference shows up in three places that matter:

  • Auditability. A graph records the path the agent took. A loop records only the model's decisions. When something goes wrong, the graph tells you which edge fired and why.
  • Branching. A loop encodes branching as conditional logic inside the loop. A graph encodes it as nodes and edges. Past three or four branches, the graph is easier to read.
  • Reuse. A graph node can appear in multiple graphs. A loop's branching logic is usually specific to one workflow.

Graphs also make human-in-the-loop pauses cheap. A graph can pause at a node until a human approves, then continue. Encoding the same pause in a loop adds tail latency and observability cost that graphs make natural.

When a graph is the wrong shape

A graph is not always the right shape. Some work is better expressed as a single loop with no explicit routing at all.

The signal that a graph is the wrong shape:

  • Only one node. A graph with one node is a loop with extra steps. Collapse it.
  • Unconditional edges. A graph where every edge fires every time is a sequence of steps. Encode it as a list.
  • No durable state. A graph that does not carry state between nodes is a sequence of independent calls. Encode it as a script.

The threshold between "loop" and "graph" is the point where the cost of implicit routing inside a loop starts to exceed the cost of explicit routing in a graph. Below the threshold, loops are cheaper. Above it, graphs are cheaper. The piece on Loops vs Graphs walks through the signals that you have crossed it.

Three patterns Triadive uses

Triadive uses three graph patterns. Each one is the right shape for a different kind of work.

  • Sequential graph with typed edges. A flowchart with conditional branches. Each node has one or more outgoing edges with declared conditions. Use this for workflows that are mostly linear with a few branches.
  • Hub-and-spoke with a coordinator. One coordinator node dispatches to leaves. The leaves do not know about each other. Use this when the workflow has a clear central decision and a set of independent operations.
  • State machine with typed events. The graph is a state machine. Each node is a state. Each edge is triggered by a typed event. Use this when the workflow is event-driven and the events are external.

Each pattern can be combined with the others. Real workflows are usually hybrids.

Common questions about graphs

Is a graph the same as a state machine?

A state machine is one kind of graph. The graph is the broader structure; the state machine is a specific shape — nodes are states, edges are events. Most agent graphs are not strict state machines; they have nodes that are not states (a "send email" node, for example, does not change state).

Does a graph need a model inside every node?

Not necessarily. Some nodes are pure routing — they decide which edge to take without calling the model. Some nodes are pure mechanical — they read a file, call an API, persist a result. The model is involved only at the nodes that need inference. The graph's job is to organize the work, not to call the model.

Why not just use a workflow tool?

Workflow tools — Airflow, Prefect, Temporal, Argo — implement graphs in their own way. They are useful for the mechanical parts. They are less useful when the routing itself needs inference, which is most agent work. The trade-off is between tool leverage and routing flexibility.

Takeaway

A graph is the structure around the work. Each node is a small loop that does one piece of work. Each edge is the rule that decides what comes next. The graph is what makes non-trivial workflows auditable, branchable, and reusable.

The rest of this manual treats graphs as one of two shapes an agent workflow can take. The other shape is the loop. Most real workflows are hybrids. The work is to recognize which shape the current work needs and to move between shapes as the work grows.