如果你了解这 6 个 LangGraph 概念，你已经领先 90% 的 AI 开发者

大多数人复制粘贴第一个教程，让它跑起来，然后一旦尝试修改任何东西就彻底卡住。原因就在这六个概念。

大多数人可以在十分钟内构建出自己的第一个 LangGraph agent。

它能运行。

然后他们改了一个地方。

他们添加了一个分支。graph 永远不会停止。或者它跳过了一个他们确信会运行的 node。或者它在 session 之间忘掉了一切。

调试一个小时后，他们得出同样的结论：

“LangGraph 很复杂。”

其实不是。

缺失的并不是另一个教程，也不是更大的代码示例。缺失的是一种 mental model，用来解释 graph 为什么会以这种方式运行。

一旦你理解了六个核心概念——state 如何流动、node 如何通信、edge 如何做决策，以及 memory 实际上如何工作——LangGraph 就会变得出奇地可预测。

本文将从第一性原理拆解这六个概念。掌握它们之后，你将不再靠试错来调试 graph，而是能够自信地构建它们。

为什么选择 LangGraph

LangChain 让串联 prompt 变得很容易：prompt | llm | parser。简洁、可读，适合简单任务。

但真实的 AI agent 很少沿着一条直线前进。一个客户支持 agent 会读取消息，决定是搜索知识库还是调用 tool，在失败时重试，并且需要记住完整对话。线性 chain 做不到这些。

LangGraph 通过显式 primitives 处理 branching、looping、retry、persistence 和 human-in-the-loop checkpoint，让 agent 的行为在每一步都可见。

LangChain 的 2026 State of Agent Engineering 报告发现，超过 70% 的 production agents 采用 graph structure，而不是简单的 linear chain。真实的业务流程很少一路直达终点。

下面这六个概念解释了这种 graph structure 实际上是如何工作的。

概念 1：State

State 是工作流中每一步都可以读取和写入的共享笔记本。

**在 LangGraph 之前，agent state 是分散的：**有些在变量里，有些在 memory 里，有些在 conversation history 里。你永远无法确定某个步骤到底知道什么。LangGraph 通过提前让 state 显式化并带有类型来解决这个问题。

from typing import TypedDict, Annotated
from operator import add

class AgentState(TypedDict):
    question: str           # the user's input
    answer: str             # what the agent produces
    messages: Annotated[list, add]  # conversation history, grows over time

graph 中的每个 node 都可以查看并修改 state 中的任何字段。只从你实际需要的字段开始。大多数指南会跳过这一点：不要一开始就设计一个包含 20 个字段的 state。让需求自然浮现。

Annotated[list, add] 值得理解。默认情况下，当两个 node 更新同一个字段时，第二个会覆盖第一个。添加 add 作为 annotation 会告诉 LangGraph 合并 list，而不是替换它们。它适用于 messages 和累积结果。对于当前状态字段（例如你正处于哪个步骤），使用普通类型即可。

初学者常见错误： 将带有 usage metadata 的完整 LLM response 存入 state。一个构建文档处理 agent 的团队把原始 LLM response 存在 state 中。到 50 个文档时，每个 checkpoint 的 state object 达到了 180KB。Postgres 写入时间上升到 400ms，并开始影响响应时间。修复方式是把 state 精简到下游 node 实际需要的内容。

概念 2：Nodes

Node 只是一个 Python function。它接收当前 state，执行一些工作，然后返回它想要更新的字段。

就是这样。如果你会写 Python function，就能构建 node。调用 LLM、访问 database、修改文本、发起 API call。Python 能做什么，它就能做什么。只有一条规则：接收 state，返回 state updates。

from langchain_openai import ChatOpenAI
from langchain.schema import HumanMessage

llm = ChatOpenAI(model="gpt-4o-mini")

def answer_node(state: AgentState) -> dict:
    # Reads from state, returns only the fields that changed
    response = llm.invoke([HumanMessage(content=state["question"])])
    return {"answer": response.content}

def refine_node(state: AgentState) -> dict:
    prompt = f"Make this clearer: {state['answer']}"
    response = llm.invoke([HumanMessage(content=prompt)])
    return {"answer": response.content}

初学者常见错误： 从 node 返回完整 state。你只需要返回被你修改的字段。返回所有内容会在多个 node 更新重叠字段时导致隐蔽的覆盖 bug。

LangGraph nodes 只是 Python functions。这个 framework 比看起来更简单。

概念 3：Edges

Edges 是连接 nodes 的线路。它们告诉 LangGraph 接下来运行哪个 node。

有两种类型。Direct edges 总是走同一条路径：当 node A 完成后，总是运行 node B。Conditional edges 会根据当前 state 选择去哪里：当 node A 完成后，检查 state 并做出决定。

from langgraph.graph import StateGraph, END

graph = StateGraph(AgentState)
# Add nodes
graph.add_node("answer", answer_node)
graph.add_node("refine", refine_node)
# Direct edge: answer always goes to refine
graph.add_edge("answer", "refine")
# Direct edge: refine goes to END
graph.add_edge("refine", END)
graph.set_entry_point("answer")
app = graph.compile()

初学者常见错误： 忘记 END。如果你没有把最后一个 node 连接到 END，graph 会永远运行，等待一个永远不会到来的下一步。这是早期 LangGraph 代码中导致 infinite loops 的最常见原因。

概念 4：Conditional Edges

这就是 LangGraph 真正强大的地方。conditional edge 不是总是前往同一个下一个 node，而是检查 state，并返回接下来要运行的 node 名称。

可以把它想象成铁路道岔。火车是 state。道岔检查 state，并把火车送到两条轨道之一。

def route_based_on_quality(state: AgentState) -> str:
    # Check the current answer quality
    if len(state["answer"]) < 50:
        return "refine"   # too short, needs more work
    return "done"         # good enough, finish

graph.add_conditional_edges(
    "answer",           # from this node
    route_based_on_quality,  # use this function to decide
    {
        "refine": "refine",  # if function returns "refine", go to refine node
        "done": END          # if function returns "done", end the graph
    }
)

Conditional edges 是 agent 的决策机制。一个 function 检查 state 并返回下一个 node 名称。这就是“我应该使用另一个 tool 还是停止？”的实现方式。

初学者常见错误： 返回 graph 中不存在的 node 名称。错误信息很晦涩，排查拼写错误所花的时间会比预期更久。始终确保返回值与你的 edge mapping dictionary 中的 key 完全匹配。

概念 5：Checkpointing

Checkpointing 是 LangGraph 让你的 agent 拥有 persistent memory 的方式。

没有 checkpointer 时，每次调用 app.invoke() 都会从头开始。agent 不会记得过去的 sessions。添加 checkpointer 后，agent 会在每次 node transition 后保存其 state，并按 thread ID 作为 key。下一次使用相同 thread ID 调用时，会从上次离开的地方精确继续。

一个 production crash 的修复原本可能需要一周时间来编写 custom serialization、Redis state cache 和 session reconstruction function，而使用 LangGraph checkpointing 只花了 45 分钟。

from langgraph.checkpoint.memory import MemorySaver  # dev only
# from langgraph.checkpoint.sqlite import SqliteSaver  # single-server prod
# from langgraph.checkpoint.postgres import PostgresSaver  # multi-instance prod

checkpointer = MemorySaver()
app = graph.compile(checkpointer=checkpointer)
# thread_id groups all interactions for one "session"
config = {"configurable": {"thread_id": "user-session-42"}}
# First call: agent runs and saves state
app.invoke({"question": "What is LangGraph?"}, config)
# Second call with same thread_id: picks up where it left off
app.invoke({"question": "Show me a code example"}, config)

开发环境使用 MemorySaver。单服务器 production 使用 SqliteSaver。当你需要多台服务器共享同一份 state 时，使用 PostgresSaver。

初学者常见错误： 在 production 中使用 MemorySaver。它把所有内容都存储在 RAM 中。服务器一重启，所有 agent state 都会消失。

概念 6：Human-in-the-Loop（Interrupts）

60% 的 production agent systems 添加了人工干预点。它们不是完全自治的 agents，而是在关键决策点暂停，等待人工确认，然后继续运行。

LangGraph 通过 interrupt_before 实现这一点。你指定哪个 node 应该触发暂停。graph 会在进入该 node 之前停止，等待人工审核并可选地更新 state，然后再恢复。

# Compile with interrupt_before to pause before the risky node
app = graph.compile(
    checkpointer=checkpointer,
    interrupt_before=["send_email"]  # pause before this node
)

config = {"configurable": {"thread_id": "task-99"}}
# Graph runs until it hits send_email, then pauses
app.invoke({"task": "Draft and send a refund email"}, config)
# A human reviews the draft here, optionally updates state
# graph.update_state(config, {"draft": "Updated email text"})
# Resume from where it paused, with human-reviewed state
app.invoke(None, config)

初学者常见错误： 试图用一个 conversation turn 来实现人工审批，而不是使用 interrupt。询问 model “我应该继续吗？”并信任它的回答，并不是 human-in-the-loop。这是在让 agent 批准自己的行动。

一个批准自己高风险决策的 agent 并没有受到监督。它只是在表演。

这六个概念如何连接在一起

完整图景如下：

决策框架

关键要点

• State 是一个 typed dictionary，每个 node 都可以读取和写入。只定义你需要的内容。保持精简。

• Nodes 是 Python functions。它们接收 state，执行工作，并只返回被它们修改的字段。

• Direct edges 总是前往同一个下一个 node。始终把最后一个 node 连接到 END。

• Conditional edges 运行一个 function，检查 state，并返回下一个 node 的名称。决策就是这样发生的。

• Checkpointing 会在每个 node 之后保存 state。开发环境使用 MemorySaver。production 使用 SqliteSaver 或 PostgresSaver。

• Interrupts 会在指定 node 之前暂停 graph，并等待人工介入。使用 app.invoke(None, config) 恢复。

接下来学什么

state、nodes 和 edges 这三部分骨架可以在不改变结构的情况下扩展到 production。为 retrieval 添加更多 nodes，你就得到一个 RAG pipeline。为 intent classification 添加一个 routing edge，你就得到一个 support router。添加一个 checkpointer，你就得到 persistent memory。所有这些都不需要重新思考基本原理。

一旦这六个概念变得自然，下一层值得理解的是 reducers（如何控制多个 node 更新同一个字段时会发生什么）、sub-graphs（在另一个 graph 内运行一个 graph，用于复杂的 multi-agent systems）和 streaming（在完整 graph 完成之前向用户发送中间结果）。

但这些都是第二层问题。先熟练构建一个使用上述全部六个概念的 graph。运行它。破坏它。修复它。这个动手循环才是让 LangGraph 的其余部分真正融会贯通的关键。

References

• LangGraph Official Graph API Docs https://docs.langchain.com/oss/python/langgraph/graph-api

• LangGraph Nodes, Edges and State: Core Concepts (MachineLearningPlus) https://machinelearningplus.com/gen-ai/langgraph-graph-concepts-nodes-edges-state/

• What Is LangGraph? Stateful Agent Graphs Explained 2026 (FutureAGI) https://futureagi.com/blog/what-is-langgraph-2026/

• LangGraph in Production: Patterns for Real Agents (Kalvium Labs) https://www.kalviumlabs.ai/blog/langgraph-in-production-stateful-multi-step-agents/

• LangGraph Tutorial: Complete Guide 2026 (GUVI) https://www.guvi.in/blog/langgraph-tutorial-complete-guide/

• LangGraph State Management: Checkpoints and Failure Recovery (BetterLink) https://eastondev.com/blog/en/posts/ai/20260424-langgraph-agent-architecture/