/agentsop-langgraph

name: agentsop-langgraph
description: |
  Decision protocol for building, debugging, and operating LangGraph-based agent
  systems. Activates when a coder agent is asked to design a stateful LLM workflow,
  add human-in-the-loop, choose a multi-agent pattern (supervisor / swarm /
  hierarchical), pick a checkpoint backend, or migrate a fragile chain into a
  durable graph. LangGraph is positioned by its maintainers as a "low-level
  orchestration framework for building, managing, and deploying long-running,
  stateful agents" — this skill encodes the *when* and *why*, not the API.
version: 0.1.0

LangGraph · SOP

> Source posture: every non-trivial claim is cited inline. Citations use short > tags like `[lc-docs]`, `[lc-blog/interrupt]`, `[gh/6731]`, `[zenml/uber]` — > resolve them against `references/*.md` for the full URL.

---

何时激活 (Activation Rules)

Activate this skill when **any** of the following triggers fire:

• The task mentions LangGraph, `StateGraph`, `MessageGraph`, `create_react_agent`,

`interrupt(`, `Command(resume=`, `add_messages`, `checkpointer`, `PostgresSaver`, `Send(`, or `entrypoint` / `task` decorators.

• The user wants to build a **stateful** agent (memory across turns, long-running,

must survive a process crash) — LangGraph's stated sweet spot `[lc-docs/why-langgraph]`.

• The user wants **human-in-the-loop** (approve a tool call, edit state, multi-turn

validation) — LangGraph offers a first-class `interrupt()` primitive that competitors require "duct-taping" to achieve `[bswen/hitl]`.

• The user is hitting **`GRAPH_RECURSION_LIMIT`** errors, infinite loops, or

`InvalidUpdateError` on parallel branches — these are LangGraph-specific failure modes with known fixes `[lc-docs/errors]` `[cheatsheet/gotchas]`.

• The user is choosing between LangGraph and CrewAI / AutoGen / OpenAI Swarm /

raw LangChain — section *生态对照* gives the decision matrix.

• The user is migrating an existing LangChain chain or a hand-rolled while-loop

agent to something durable and observable.

Do **not** activate if the task is a single LLM call, a one-shot RAG query, or a stateless tool pipeline — `Sec. 反模式` explains why graphs are overkill there.

---

核心心智模型 (Core Mental Model)

**LangGraph is a state machine, not a chain.** The cleanest one-liner from the 2026 docs: "If chains were about passing outputs between steps, graphs are about maintaining and evolving a shared state over time" `[eastondev/2026]`. Pre-LLM analog: think BPMN / finite state machine / Pregel-style "supersteps", not a Unix pipe. The official position is even more reductive: LangGraph is "a deterministic execution engine for AI reasoning workflows" `[eastondev/2026]`.

Three load-bearing concepts ride this model:

1. **State is the single source of truth.** All nodes read from and write to one shared, typed object (`TypedDict` / Pydantic / dataclass). A node returns a *partial update*, never a mutation. How updates merge into state is governed by **reducers**, declared via `Annotated[list[Msg], add_messages]` etc. Missing a reducer on a key that two parallel nodes both write to triggers `InvalidUpdateError` — reducers are mandatory for parallel writes `[cheatsheet/gotchas]`. The reducer system is what lets the graph be composable, replayable, and crash-safe.

2. **Checkpoints make state durable.** After every superstep, the full state is snapshotted into a checkpointer (SQLite for local, Postgres for production, Redis for fast TTL'd swarms) `[lc-docs/persistence]` `[redis/checkpoint]`. This single property is what unlocks the headline features: durable execution that "persists through failures and resumes from their exact stopping point", time-travel debugging (replay or fork from any checkpoint), and human-in-the-loop (a thread can sit interrupted for hours and resume cleanly) `[gh/langgraph-readme]` `[dragonforest/timetravel]`.

3. **Graph topology is just routing logic over state.** Edges are static (always go to N), conditional (a function reads state and picks a next node), or dynamic via the `Send` API (a routing function returns a list of `Send` objects to spawn variable-count parallel workers) `[deepwiki/mapreduce]`. This is where LangGraph diverges from CrewAI's role-based crew and AutoGen's conversational pattern — control flow is **explicit**, not emergent from chat history.

The OS-level claim: **"2026 is the year of Stateful Orchestration"** `[eastondev/2026]`. LangGraph bet that production agents need persistence, explicit control flow, and observability more than they need elegance. That bet is paying off (Klarna serves 85M users on it, Replit pushed it so hard LangSmith had to be rewritten to ingest the traces) — but the cost is verbosity that frustrates anyone trying it on a toy problem `[lc-blog/production]` `[duplocloud/compare]`.

---

SOP 工作流 (Agentic Protocol)

A coder agent should walk this protocol top-down. Each step has a **decision gate** — if the answer is "no" or "not yet", stop and reconsider before adding graph complexity.

Step 1 · Decide whether a graph is actually warranted

Gate questions:

• Does the workflow have ≥1 cycle (tool-call → reflect → retry)?
• Does it need to **survive a crash** mid-execution?
• Will a human need to inspect or override state mid-run?
• Are there ≥2 specialized agents that hand off?

If **all four are no**, use a plain `RunnableSequence` or raw API calls and exit. Over-graphing simple flows is the #1 anti-pattern `[swarnendu/best]`.

Step 2 · Pick the API surface

| Need | Choice | Why | |---|---|---| | Standard tool-calling ReAct loop | `create_react_agent` (prebuilt) | Syntactic sugar over StateGraph; ~3 lines of code `[agentsindex/v1]` | | Imperative Python style, async tasks, no explicit graph | Functional API (`@entrypoint`, `@task`) | Shares the runtime with StateGraph; trades time-travel granularity for code brevity `[lc-blog/functional]` | | Multi-