LangGraph: Agents as State GraphsOpen in Colab
Agentic project loop
Task definition·Context & tools·Orchestration loop·Evaluation·Guardrails·Operations feedback

LangGraph: Agents as State Graphs

The agents lesson describes the ReAct loop — Thought → Action → Observation, repeated until done. That loop is easy to sketch and surprisingly hard to make robust: you need bounded iteration, branching ("did the model ask for a tool, or is it finished?"), persistence so a run can pause and resume, and a way to inspect what happened. LangGraph is a framework that makes that control flow explicit by modelling the agent as a directed graph with shared state, rather than a hidden while loop. This page covers the mental model; the companion notebook builds a tiny LangGraph-style engine from scratch so the abstractions are concrete.

Why a graph, not a chain

Chain vs. graph

A LangChain chain is a fixed pipeline — a DAG you traverse once, A → B → C. LangGraph adds the two things agents need that a DAG can't express: cycles (loop back to re-plan) and conditional edges (choose the next node at runtime). An agent is fundamentally a loop with branches; LangGraph gives that loop a first-class structure.

The three core abstractions

1. State — a single typed object threaded through every node. You declare its shape and, per field, a reducer that says how a node's output is merged in. The canonical example is a message list whose reducer is "append":

statet+1[k]=reducerk(statet[k],  node_output[k])\text{state}_{t+1}[k] = \text{reducer}_k\big(\text{state}_t[k],\; \text{node\_output}[k]\big)
Python
from typing import Annotated, TypedDict
import operator

class AgentState(TypedDict):
    messages: Annotated[list, operator.add]   # reducer = list concatenation
    steps: int                                # default reducer = overwrite

Without the operator.add reducer each node would replace messages; with it, every node appends. The reducer is how LangGraph accumulates a transcript instead of clobbering it.

2. Nodes: plain functions state -> partial_state_update. A node reads the current state and returns only the fields it wants to change. Typical nodes: an agent node that calls the LLM, and a tools node that executes whatever tool the LLM requested.

3. Edges — how control flows between nodes:

  • Normal edge add_edge("tools", "agent"): always go from tools back to agent.
  • Conditional edge add_conditional_edges("agent", route_fn, {...}): call route_fn(state), which returns a key naming the next node. This is where the agent decides whether to call a tool or stop.
  • The reserved START and END sentinels mark entry and termination.

A ReAct agent as a graph

The classic agent is just two nodes and one decision:

Text
        START
          │
          ▼
      ┌────────┐   route: "tools" if the LLM asked for a tool
      │ agent  │──────────────┐
      └────────┘              │
          ▲                   ▼
          │              ┌────────┐
          │   add_edge   │ tools  │
          └──────────────└────────┘
          │
   route: "end" if the LLM produced a final answer
          ▼
         END
Python
from langgraph.graph import StateGraph, START, END

def agent_node(state):
    reply = llm(state["messages"])          # may contain a tool call
    return {"messages": [reply], "steps": state["steps"] + 1}

def tool_node(state):
    call = last_tool_call(state["messages"])
    result = TOOLS[call.name](**call.args)
    return {"messages": [tool_result(result)]}

def route(state):
    last = state["messages"][-1]
    if state["steps"] >= 8:        return "end"     # bounded loop!
    return "tools" if has_tool_call(last) else "end"

g = StateGraph(AgentState)
g.add_node("agent", agent_node)
g.add_node("tools", tool_node)
g.add_edge(START, "agent")
g.add_conditional_edges("agent", route, {"tools": "tools", "end": END})
g.add_edge("tools", "agent")        # the cycle: tool result feeds the next thought
app = g.compile()

app.invoke({"messages": [user("pop. of capital of France / 1000")], "steps": 0})

The tools → agent edge is the cycle that a plain chain cannot express, and route collapses the entire "keep going or stop?" decision (plus the bounded-loop safeguard from the agents lesson) into one inspectable function.

Graph execution model

LangGraph runs in super-steps (a Pregel-style message-passing model). At each super-step it executes the active node(s), applies their updates to the state through the reducers, then evaluates outgoing edges to find the next active node. Nodes with no data dependency between them run in parallel within a super-step; a conditional edge picks the single next node. Execution halts when control reaches END.

Reliability from graph structure

Need (from the agents lesson)What LangGraph gives you
Bounded loopsa step counter in state + a route that returns END past a cap
Human-in-the-loopcheckpointing: persist state at a node, interrupt, resume after approval
Observabilitythe state transcript + per-node tracing is the execution log
Recover from a crasha checkpointer (memory / SQLite / Postgres) snapshots state each super-step
Debug a bad runtime travel: rewind to a past checkpoint and re-run from there

Persistence is the headline feature

Attaching a checkpointer (app = g.compile(checkpointer=...)) makes every run durable and resumable. The same mechanism powers human-in-the-loop approvals (pause at a node, wait for input, continue) and "time travel" debugging (fork from any past state) — capabilities that are painful to bolt onto a hand-written while loop.

Common pitfalls

  1. Forgetting the reducer on the message field. Without Annotated[list, operator.add], each node overwrites the history and the agent loses its memory of prior steps.
  2. No termination guard in the router. A conditional edge that can always route back into the graph yields an infinite loop and runaway cost — always include a step cap or explicit stop condition (the same bounded-loop rule from the agents lesson).
  3. Putting side effects in the router. route(state) should be a pure read of state that returns the next-node key; run tools in a node, not in the edge function.
  4. Reaching for a graph when a chain suffices. If the steps are fixed and acyclic, a plain chain is simpler and more predictable; use LangGraph when you genuinely need branching or loops.

Related concepts

Concept neighbourhood

How this concept connects — click any node to jump there, or explore the whole concept map.

RelatedReferenced by
LangGraph: Agents as State GraphsAgent Protocols: MCP & A2ASub-Agent Types: Sequenti…Agents & Tool UseAI-Engineering Architectu…Deploying Agents in Produ…Retrieval-Augmented Gener…