agentsop-langgraph
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.
agentsope · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add agentsope/SkillAlchemy --skill 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 againstreferences/*.mdfor 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(, orentrypoint/taskdecorators. - 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_LIMITerrors, infinite loops, orInvalidUpdateErroron 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:
-
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 viaAnnotated[list[Msg], add_messages]etc. Missing a reducer on a key that two parallel nodes both write to triggersInvalidUpdateError— reducers are mandatory for parallel writes[cheatsheet/gotchas]. The reducer system is what lets the graph be composable, replayable, and crash-safe. -
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]. -
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
SendAPI (a routing function returns a list ofSendobjects 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- |