The Problem

Building production-grade language agents requires more than calling an LLM in a loop. Agents need durable execution across failures, human-in-the-loop checkpoints, and persistent memory—concerns that generic orchestration tools don't address. LangGraph provides a low-level graph abstraction specifically for stateful, long-running agent workflows.

What This Does

LangGraph is a Python framework for building stateful agents as graphs. Core logic lives in libs/langgraph/langgraph/pregel/main.py (the Pregel execution engine) and libs/langgraph/langgraph/graph/state.py (graph construction). The repo also contains libs/checkpoint for durable state persistence (SQLite, Postgres, Redis backends), libs/cli for deployment tooling, and libs/prebuilt for ready-made agent components.

The examples/ folder has 35 Jupyter notebooks covering RAG, multi-agent systems, human-in-the-loop, and reflection patterns—useful as reference implementations.

How It Is Wired

Execution starts at libs/langgraph/langgraph/pregel/main.py. The invoke method is the central hub, called from 292 places; add_edge (270) and add_node (263) dominate graph construction. The StateGraph class (233 callers) is the primary API entry point.

A typical run flows: invoke → stream → network call via self.http.stream. The checkpoint layer (libs/checkpoint/langgraph/checkpoint/base/__init__.py) is the most-connected non-test module, called from 58 files, and handles both database reads/writes and network calls—it's the persistence backbone. libs/langgraph/langgraph/_internal/_runnable.py (34 callers) manages config context propagation.

The libs/checkpoint/langgraph/checkpoint/memory/__init__.py module is the default in-memory implementation, with Postgres (libs/checkpoint-postgres/) and SQLite (libs/checkpoint-sqlite/) as production alternatives. The langgraph_cli/deploy.py handles deployment and performs secret-generation operations.

How To Use It

Setup (from README):

pip install -U langgraph

Configuration: No required environment variables for core usage. The CLI (libs/cli/) uses langgraph.json for deployment config (see libs/cli/examples/graphs/langgraph.json). Postgres checkpointing requires a database connection string.

Running it: Build a graph in Python:

from langgraph.graph import StateGraph

graph = StateGraph(MyState)
graph.add_node("agent", my_agent)
graph.add_edge("agent", "agent")
app = graph.compile()
result = app.invoke({"messages": []})

Real-World Use

A customer-support agent that must survive process crashes: define nodes for intent classification, retrieval, and response generation. Use libs/checkpoint-postgres for durable state so a crashed run resumes from the last completed node, not from scratch. Add an interrupt node for human approval before executing actions—LangGraph's checkpointing makes this state inspectable and modifiable mid-run.

Code Health & Issues

Static analysis found 172 issues (58 high, 114 medium). Key findings:

  • High - Duplicated code blocks: 141 files share 6-line repeated blocks, notably in libs/checkpoint/langgraph/checkpoint/base/__init__.py and libs/langgraph/langgraph/pregel/_checkpoint.py. Extract shared helpers.
  • High - Deep nesting (×42): Max indentation depth 7 in libs/prebuilt/tests/model.py and libs/checkpoint/langgraph/checkpoint/memory/__init__.py. Use guard clauses.
  • High - Oversized files (×17): libs/cli/langgraph_cli/config.py has 1,327 lines. Split by responsibility.
  • Med - CI dependency drift: .github/workflows uses yarn install without --immutable; locked dependencies aren't guaranteed.
  • Med - No dependency vulnerability scan: No dependency-review-action or osv-scanner in CI.
  • Med - Checkout token persistence: .github/workflows/_integration_test.yml leaves credentials in .git/config; set persist-credentials: false.
  • Low - Missing job timeouts and missing .editorconfig/.gitattributes.

The 146 test files and GitHub Actions CI are solid. No secrets committed.

The Bottom Line

LangGraph is a mature, well-tested framework for stateful agents—the 40k+ upstream stars reflect real production adoption. The codebase has maintainability debt (duplication, large files) but the architecture is sound. Use it if you need durable execution and human-in-the-loop beyond what a simple LLM loop provides.