用 LangGraph 构建多步骤推理 AI Agent 实战指南

一、为什么需要 LangGraph？

传统的 LLM 调用是单轮无状态的：输入 → 输出，完成任务。但现实中的 Agent 往往需要多轮推理——先规划、再执行工具、判断结果、必要时回退重试。LangChain 的 AgentExecutor 虽然能处理简单循环，但一旦涉及条件分支、并行子任务、状态共享，就显得力不从心。

LangGraph 用有向图（Graph）描述工作流：每个节点是一个可执行步骤，边是转移条件。这让复杂的 Agent 逻辑变得可读、可调试、可持久化——正是生产级 AI 应用所需要的。

二、核心概念速览

在动手之前，先理解三个核心抽象：

• StateGraph：带有共享状态的图，每个节点读写同一个 State 字典。
• Node（节点）：接收 State、执行逻辑、返回更新后的 State 片段的函数。
• Edge（边）：节点间的跳转规则，支持固定边和条件边（Conditional Edge）。

此外，Checkpointer 负责状态持久化（支持 SQLite、Redis），让 Agent 可以中断后恢复。

三、实战：构建一个 ReAct 推理 Agent

下面用 LangGraph 实现经典的 ReAct（Reasoning + Acting）模式：LLM 先推理（Thought），再调用工具（Action），观察结果（Observation），循环直到得出最终答案。

3.1 环境安装

（代码示例：见文末附录）

3.2 定义状态结构

【完整代码示例，约8行，见文末附录】

Annotated[..., operator.add] 表示每次节点更新时，消息列表是追加而非覆盖——这是 LangGraph 状态合并的关键机制。

3.3 构建推理节点与工具节点

【完整代码示例，约30行，见文末附录】

3.4 定义条件边与组装图

【完整代码示例，约16行，见文末附录】

3.5 运行 Agent

【完整代码示例，约9行，见文末附录】

四、生产级增强：持久化与中断恢复

线上 Agent 必须能够处理网络中断、Token 超限等异常。LangGraph 的 Checkpointer 机制让你在任意节点保存快照：

【完整代码示例，约12行，见文末附录】

一旦任务中断，只需用同一个 thread_id 重新调用，Agent 会从最后一个成功节点继续，而不是从头开始——这对长时间运行的任务至关重要。

五、最佳实践与踩坑总结

• 状态尽量精简：只在 State 中放真正需要跨节点共享的数据，避免把大对象塞进 messages。
• 条件边做好兜底：should_continue 函数必须覆盖所有可能的返回值，否则图会卡住。
• 工具调用加重试：在 tool_node 内部捕获异常，返回带错误描述的 ToolMessage，让 LLM 自行决策重试还是换方案。
• 设置最大迭代次数：在 compile() 时传入 recursion_limit 防止无限循环。
• 善用 LangSmith 可视化：配置 LANGCHAIN_TRACING_V2=true 后每次运行都能在 LangSmith 中看到完整的节点轨迹，调试效率倍增。