Skip to content

Search articles, repositories, topics and pages.

langgraph

langchain-ai/langgraph

A graph runtime for durable, stateful agent workflows with explicit control over steps and recovery

45,117 stars7,786 forks

View on GitHub (opens in a new tab)
  • Python
  • agents
  • ai
  • ai-agents
  • chatgpt
  • deepagents
A nonlinear state graph branches and rejoins above a checkpoint timeline, with human interrupt and rollback paths

About

Build resilient agents.

My analysis

Understanding LangGraph Architecture

A source-oriented tour of LangGraph state, nodes, supersteps, checkpoints and interrupts, with guidance on where the runtime fits.

TIAN NEWS AI

Published Updated 4 min read

LangGraph is easiest to understand as a stateful graph runtime, not as a magic agent loop. The application defines state, computation nodes and routing. The runtime schedules work, merges state updates and can persist checkpoints around each step.

That distinction matters when the workflow must pause for approval, recover after failure or inspect how a result was produced.

Updated

Describes the public LangGraph concepts and repository documentation available on October 2, 2026. Pin a package release or commit before source-level implementation work.

Tested with

langchain-ai/langgraph · LangGraph overview · persistence · durable execution

The graph is a state transition system

A graph begins with a state schema. Nodes receive the current state and return updates. Edges determine which node or set of nodes runs next.

Conceptually:

support_graph.py, python
class State(TypedDict):
    messages: Annotated[list, add_messages]
    approved: bool

builder = StateGraph(State)
builder.add_node("draft", draft_reply)
builder.add_node("review", review_reply)
builder.add_edge(START, "draft")
builder.add_conditional_edges("draft", route_after_draft)
graph = builder.compile(checkpointer=checkpointer)

The important detail is that node returns are state updates. Reducers define how parallel or repeated updates combine. Without an explicit reducer, an update may replace a field rather than append to it.

Compilation creates the executable boundary

The builder describes topology. Compilation validates and turns it into a runnable graph where runtime concerns can be attached: checkpointing, interrupts and stores.

Keep business rules in nodes and routing functions that can be tested without a live model. Put provider clients, databases and queues behind application boundaries. A graph definition should not become a place where every integration imports every other integration.

Key takeaway

LangGraph makes control flow explicit, but it does not make side effects safe. A retried node can repeat an email, charge or database write unless that operation is idempotent or separately committed.

Supersteps explain parallel work

LangGraph’s execution model follows graph-processing ideas: nodes made active by the current state can execute within a step, and their updates become visible at the step boundary. This enables fan-out and fan-in patterns without pretending the graph is a simple line.

When two nodes update the same state key, the schema’s reducer is the concurrency contract. If the order of results matters, encode ordering data rather than relying on completion timing.

Typical topology:

text
START -> classify -> research_a --\
                    research_b ----> synthesize -> END
                    research_c --/

The graph shows control dependencies. It does not automatically impose a distributed transaction across those nodes.

Checkpoints belong to threads

With a checkpointer, LangGraph persists graph state as checkpoints associated with a thread identifier. Checkpoints support inspection, replay, fault recovery and human-in-the-loop pauses.

Use a durable checkpointer for production. An in-memory saver is appropriate for tests and local experiments, not recovery after a process restart.

Separate thread-scoped checkpoints from cross-thread memory. A conversation’s execution state and a user profile have different lifetimes, access rules and deletion requirements. LangGraph exposes stores for data that must outlive or cross thread boundaries; the application still owns the data model and policy.

Durable execution requires deterministic thinking

Recovery may resume from a recorded step rather than from the exact machine instruction that failed. Design nodes so that replay is safe:

  • isolate network and database effects;
  • use idempotency keys for external writes;
  • persist external operation results before relying on them;
  • avoid hidden dependence on wall-clock time or random values;
  • keep large opaque objects out of state;
  • version state schemas and serialized payloads.

If a node both calls a model and sends an email, recovery becomes ambiguous. Split proposal, approval and delivery into distinct nodes.

Interrupts turn approval into state

An interrupt pauses execution and surfaces a payload to the caller. The application records the thread and later resumes it with a decision.

This is stronger than a chat message saying “please approve.” The pause exists in runtime state and can survive the request that created it.

Approval still needs application security: authenticate the reviewer, authorize the action, bind the decision to the exact proposed payload and audit who resumed the thread. The graph runtime does not know your organization’s approval policy.

  1. Model the minimum state required by the workflow.
  2. Define reducers for keys written by more than one node.
  3. Keep nodes small and make routing rules testable.
  4. Attach a checkpointer and require a thread identifier.
  5. Split consequential side effects into idempotent, auditable steps.
  6. Use interrupts for decisions that require a person or external event.
  7. Test failure and resume at every side-effect boundary.

Where LangGraph fits

LangGraph is a good fit when the application needs explicit branching, cycles, persistence and recovery. A plain function or queue worker is often clearer for a short, deterministic pipeline. A durable workflow engine may be more appropriate when cross-service transactions and operational scheduling dominate the problem.

The architecture earns its complexity when the graph itself is a useful model of the product’s control flow.

  1. LangGraph repository — source, packages and release history.
  2. LangGraph overview — state, nodes, edges and compilation concepts.
  3. LangGraph persistence — threads, checkpoints, replay and stores.
  4. LangGraph durable execution — replay behavior and requirements for deterministic, idempotent workflows.