/langgraph

name: langgraph
license: MIT
compatibility: "Claude Code 2.1.251+."
description: LangGraph 1.x (LTS) Python workflow patterns for state management, delta channels, resilience (node timeouts, error handlers, graceful drain), routing, parallel execution, supervisor-worker, tool calling, checkpointing, human-in-loop, streaming (v2 format), subgraphs, and functional API. Use when building LangGraph pipelines, multi-agent systems, or AI workflows.
tags: [langgraph, workflow, state, delta-channel, resilience, timeout, routing, parallel, supervisor, tools, checkpoints, streaming, streaming-v2, subgraphs, functional, lts, python]
context: fork
agent: workflow-architect
version: 2.3.0
author: OrchestKit
user-invocable: false
disable-model-invocation: true
complexity: high
persuasion-type: reference
effort: high
targets:
  # Python only. The JS package `@langchain/langgraph` is on its own faster line (1.4.x as of
  # 2026-07) and every rule here is Python — declaring a JS floor advertised coverage this skill
  # does not have. Re-add it only alongside real TypeScript rules.
  - library: "langgraph"
    version: ">=1.2.0"
upstream-version-tested: "1.2.11"
metadata:
  category: document-asset-creation
allowed-tools:
  - Read
  - Glob
  - Grep
  - WebFetch
  - WebSearch

LangGraph Workflow Patterns

Comprehensive patterns for building production LangGraph workflows. **LangGraph 1.x is LTS** (Long Term Support) — the first stable major release, powering agents at Uber, LinkedIn, and Klarna. Each category has individual rule files in `rules/` loaded on-demand.

> **LangGraph 1.2 (shipped 2026-05-12) — the fault-tolerance release.** Everything below is on > `StateGraph.add_node(...)` unless noted: > > - **Per-node timeouts** — `timeout=` accepts `float | timedelta | TimeoutPolicy`. > `TimeoutPolicy(run_timeout=, idle_timeout=, refresh_on="auto"|"heartbeat")` separates a hard > wall-clock cap from an idle cap that progress refreshes. On expiry LangGraph raises > `NodeTimeoutError` (carrying `kind="idle"|"run"` and `elapsed`), drops that attempt's writes, and > defers to the retry policy. Cooperative: it rides asyncio cancellation, so a node blocking the > GIL is *not* interrupted. See `rules/resilience-node-timeouts.md`. > - **Node error handlers** — `error_handler=` registers a recovery node that runs once the retry > budget is exhausted. It receives failure context by declaring a parameter typed `NodeError` > (fields `node`, `error`) and returns a `Command` to update state and reroute. > See `rules/resilience-error-handlers.md`. > - **`RunControl`** (`langgraph.runtime`) — cooperative graceful shutdown. `request_drain(reason)` > from any thread; nodes poll `runtime.drain_requested` and stop at a checkpoint boundary, leaving > a resumable thread instead of a half-applied superstep. See `rules/resilience-graceful-drain.md`. > - **`DeltaChannel`** (`langgraph.channels.delta`, **beta**) — checkpoints store only incremental > writes and replay them through a batch reducer, with a snapshot every `snapshot_frequency` > updates. Fixes checkpoint cost growing with thread length. Its reducer takes a *batch* and must > be batching-invariant. See `rules/state-delta-channel.md`. > - **`runtime.heartbeat()`** — explicit progress signal, the only one that refreshes an idle timeout > under `refresh_on="heartbeat"`. > > **Landed earlier, in 1.1 — not 1.2** (they are current and supported; only their release > attribution was wrong in prior versions of this skill): deferred nodes (`defer=True`), node-level > caching (`CachePolicy` + `graph.compile(cache=...)`), and model middleware > (`before_model` / `after_model`) on `create_agent`.

Quick Reference

| Category | Rules | Impact | When to Use | |----------|-------|--------|-------------| | [State Management](#state-management) | 5 | CRITICAL | Designing workflow state schemas, accumulators, reducers, delta channels | | [Resilience](#resilience) | 3 | CRITICAL | Node timeouts, error handlers, graceful drain (1.2+) | | [Routing & Branching](#routing--branching) | 4 | HIGH | Dynamic routing, retry loops, semantic routing, cross-graph | | [Parallel Execution](#parallel-execution) | 3 | HIGH | Fan-out/fan-in, map-reduce, concurrent agents | | [Supervisor Patterns](#supervisor-patterns) | 3 | HIGH | Central coordinators, round-robin, priority dispatch | | [Tool Calling](#tool-calling) | 4 | CRITICAL | Binding tools, ToolNode, dynamic selection, approvals | | [Checkpointing](#checkpointing) | 3 | HIGH | Persistence, recovery, cross-thread Store memory | | [Human-in-Loop](#human-in-loop) | 3 | MEDIUM | Approval gates, feedback loops, interrupt/resume | | [Streaming](#streaming) | 3 | MEDIUM | Real-time updates, token streaming, custom events | | [Subgraphs](#subgraphs) | 3 | MEDIUM | Modular composition, nested graphs, state mapping | | [Functional API](#functional-api) | 3 | MEDIUM | @entrypoint/@task decorators, migration from StateGraph | | [Platform](#platform) | 3 | HIGH | Deployment, RemoteGraph, double-texting strategies |

**Total: 41 rules across 12 categories**

State Management

State schemas determine how data flows between nodes. Wrong schemas cause silent data loss.

| Rule | File | Key Pattern | |------|------|-------------| | TypedDict State | `rules/state-typeddict.md` | `TypedDict` + `Annotated[list, add]` for accumulators | | Pydantic Validation | `rules/state-pydantic.md` | `BaseModel` at boundaries, TypedDict internally | | MessagesState | `rules/state-messages.md` | `MessagesState` or `add_messages` reducer | | Custom Reducers | `rules/state-reducers.md` | `Annotated[T, reducer_fn]` for merge/overwrite | | Delta Channels (1.2, beta) | `rules/state-delta-channel.md` | `DeltaChannel(reducer, snapshot_frequency=)` for large accumulators |

Resilience

Fault tolerance for nodes that talk to the outside world. New in 1.2 — before it, the only lever was `retry_policy`, which cannot help a node that never fails beca