这里写自定义目录标题

欢迎使用Markdown编辑器

你好！ 这是你第一次使用# LangGraph智能体开发实战:从状态机到生产级工作流

引言:为什么 LangGraph 值得认真学

在 AI Agent 开发框架的版图里,LangGraph 是一个绕不开的名字。它由 LangChain 团队推出,定位不是"LangChain 的图形化插件",而是一套全新的工程范式——把 Agent 的执行过程建模为一张有向图,用状态机的方式管理每一步的执行。很多开发者第一次接触 LangGraph 时,下意识把它当成 LangChain 的升级版,把 llm.invoke() 换成 graph.add_node(),以为就完成了迁移。这是最危险的认知偏差。

LangChain 本质是函数式编排:每个组件是无状态的纯函数,输入 Prompt,输出字符串,中间靠 Python 变量传值。而 LangGraph 强制你进入状态机建模:所有节点共享一个可变的 State 对象,每次节点执行都是对这个 State 的原子性更新。这个差异带来三个不可逆的工程影响:数据契约显性化、执行流程可视化、状态可持久化。本文从核心概念出发,结合实战案例,拆解如何用 LangGraph 构建一个可运维、可迭代的生产级 Agent 工作流。

一、核心概念:State、Node、Edge 与 Checkpoint

LangGraph 的四个核心概念构成了它的全部抽象。

1.1 State:整个图的"共享内存"

State 是在节点之间传递的数据结构,是整个图的"共享内存"。它通常用 TypedDict 或 Pydantic 模型定义,例如一个订单处理 Agent 的 State 可能是:

class OrderState(TypedDict):
    order_id: str
        status: Literal["pending", "reviewing", "rejected"]
            review_notes: Optional[str]
                attempts: int
                ```
这个模型不是装饰,而是整个工作流的 API 契约——下游节点能读到什么、上游节点必须写入什么,都由它决定。工程上,State 定义得越清晰,工作流越容易维护。一个常见的坑是 State 字段过多、职责混杂,导致节点之间隐式耦合。建议把 State 按业务域拆分,或者用嵌套结构组织。

### 1.2 Node:具体的执行单元

Node 是图中的节点,可以是调用 LLM、调用工具、执行代码等任何具体步骤。每个 Node 接收 State 作为输入,返回更新后的 State 片段。Node 的设计原则是"单一职责":一个 Node 只做一件事,这样既容易测试,也容易复用。

### 1.3 Edge:节点之间的流转逻辑

Edge 定义节点之间的流转条件,可以是顺序执行、条件分支、循环回退。条件分支是 LangGraph 最强大的能力之一——你可以根据 State 中的某个字段决定下一步走向哪个节点,实现"如果审核通过就走发布节点,否则走重试节点"这样的逻辑。循环回退则让 Agent 能够自我纠错:当工具调用失败时,可以回到规划节点重新规划。

### 1.4 Checkpoint:状态持久化与恢复

Checkpoint 是 LangGraph 最突出的特性——保存执行状态,支持中断恢复。这意味着 Agent 可以在任意节点暂停,保存当前 State,之后从断点继续执行。这个能力对生产环境至关重要:当任务执行到一半系统崩溃时,可以从 Checkpoint 恢复,而不是从头再来;当需要人工介入时,可以在关键节点暂停,等人工确认后再继续。

## 二、实战:构建一个带条件分支的订单风控 Agent

下面通过一个订单风控 Agent 的例子,演示 LangGraph 的核心用法。这个 Agent 的流程是:接收订单 → 调用风控规则引擎 → 根据结果决定放行、人工审核或拒绝。

```python
from langgraph.graph import StateGraph, END
from typing import TypedDict, Literal, Optional

class RiskState(TypedDict):
    order_id: str
        amount: float
            risk_score: Optional[float]
                decision: Optional[str]
def check_rules(state: RiskState) -> RiskState:
    # 调用风控规则引擎,计算风险分
        score = compute_risk_score(state["order_id"], state["amount"])
            return {"risk_score": score}
def route_by_score(state: RiskState) -> str:
    score = state["risk_score"]
        if score > 0.8:
                return "reject"
                    elif score > 0.5:
                            return "review"
                                else:
                                        return "approve"
def approve(state: RiskState) -> RiskState:
    return {"decision": "approved"}
def review(state: RiskState) -> RiskState:
    return {"decision": "manual_review"}
def reject(state: RiskState) -> RiskState:
    return {"decision": "rejected"}
graph = StateGraph(RiskState)
graph.add_node("check_rules", check_rules)
graph.add_node("approve", approve)
graph.add_node("review", review)
graph.add_node("reject", reject)
graph.set_entry_point("check_rules")
graph.add_conditional_edges("check_rules", route_by_score, {
    "approve": "approve",
        "review": "review",
            "reject": "reject",
            })
            graph.add_edge("approve", END)
            graph.add_edge("review", END)
            graph.add_edge("reject", END)
            app = graph.compile()
            ```
这个例子虽然简单,但展示了 LangGraph 的核心价值:把"规则判断"这类确定性逻辑从模型推理中剥离出来,用代码实现,让模型只负责真正需要推理的部分。这正是 Graph Engineering 的核心思想——让代码处理确定性规则,让模型处理不确定性推理。

## 三、生产级设计模式:四个必须掌握的技巧

### 3.1 循环检测必须配 Timeout + Retry

Agent 工作流最常见的故障是"循环卡死"——模型在某个节点反复绕圈,永远无法收敛。LangGraph 的循环回退能力是把双刃剑:用得好是自我纠错,用不好就是死循环。生产级实践必须为循环设置最大迭代次数,超限后强制终止并降级;同时为每个工具调用设置超时和重试策略,避免单个节点阻塞整个流程。

### 3.2 Human-in-the-loop:可控又不打断推理流

人工介入是生产级 Agent 的刚需,但设计不好会严重影响体验。LangGraph 的 Checkpoint 机制天然支持 Human-in-the-loop:在关键节点(如高风险操作、最终发布)设置中断,保存 State,等人工确认后从断点继续。设计原则是:人工介入点要少而精,只在高风险或低置信度的环节介入;介入时给人工提供足够的上下文,包括当前 State、模型推理过程和可选操作。

### 3.3 可观测性:让运维看得懂状态流转

LangGraph 应用上线后,运维团队最需要的是"看得懂状态流转"。建议为每个节点埋点,记录节点名、耗时、输入输出摘要;为每次运行生成 trace,记录完整的执行路径;把关键指标(节点耗时、分支走向、失败率)接入 Prometheus 等监控系统。实践中有团队通过这种方式,把 Agent 的平均故障定位时间从小时级缩短到分钟级。

### 3.4 状态契约先行:先定义 State 再写节点

很多团队写 LangGraph 应用时,习惯先写节点逻辑,再回头补 State 定义,结果节点之间通过隐式字段传值,耦合严重。正确的做法是"契约先行":先定义完整的 State 模型,明确每个字段的读写方,再写节点。这样每个节点只依赖 State 契约,不依赖其他节点的内部实现,工作流才能长期可维护。

## 四、从单图到多图:复杂系统的组织方式

当业务复杂到一定程度,单个图会变得臃肿难维护。2026 年的实践趋势是"子图组合":把独立的业务环节封装成子图,再通过父图编排。例如,一个完整的客服 Agent 可以拆成"意图识别子图""知识检索子图""工单处理子图",每个子图独立开发、独立测试,再由父图根据意图路由到对应子图。

子图组合的好处是显而易见的:每个子图职责单一,可以独立迭代;子图之间通过 State 契约通信,耦合度低;测试时可以单独验证每个子图,定位问题更快。但也要注意,子图划分不是越细越好,过度拆分会增加编排复杂度和通信开销。一个实用的判断标准是:如果两个环节经常需要一起修改,它们就应该在同一个子图里。

## 五、常见坑与避坑建议

最后总结 LangGraph 实战中的几个高频坑。坑一:把 State 当全局变量滥用,所有节点都读写所有字段,导致状态混乱。坑二:条件分支逻辑写在节点内部而不是 Edge 上,破坏了图的可视化能力。坑三:忽略 Checkpoint,导致任务中断后无法恢复。坑四:没有为循环设置上限,生产环境出现死循环。坑五:过度设计,把简单的线性流程也拆成复杂的图结构,反而增加了维护成本。

LangGraph 的价值不在于"图"这个形式,而在于它强制你思考 Agent 的执行结构:哪些步骤是确定性的、哪些需要模型推理、失败后流向哪里、哪些环节需要人工介入。想清楚这些问题,无论用什么框架,都能构建出可靠的生产级 Agent。这正是从"写 Prompt"到"设计系统"的进阶之路。

**Markdown编辑器** 所展示的欢迎页。如果你想学习如何使用Markdown编辑器, 可以仔细阅读这篇文章，了解一下Markdown的基本语法知识。

## 新的改变

我们对Markdown编辑器进行了一些功能拓展与语法支持，除了标准的Markdown编辑器功能，我们增加了如下几点新功能，帮助你用它写博客：
 1. **全新的界面设计** ，将会带来全新的写作体验；
 2. 在创作中心设置你喜爱的代码高亮样式，Markdown **将代码片显示选择的高亮样式** 进行展示；
 3. 增加了 **图片拖拽** 功能，你可以将本地的图片直接拖拽到编辑区域直接展示；
 4. 全新的 **KaTeX数学公式** 语法；
 5. 增加了支持**甘特图的mermaid语法[^1]** 功能；
 6. 增加了 **多屏幕编辑** Markdown文章功能；
 7. 增加了 **焦点写作模式、预览模式、简洁写作模式、左右区域同步滚轮设置** 等功能，功能按钮位于编辑区域与预览区域中间；
 8. 增加了 **检查列表** 功能。
 [^1]: [mermaid语法说明](https://mermaid.js.org/intro/)

## 功能快捷键

撤销：<kbd>Ctrl/Command</kbd> + <kbd>Z</kbd>
重做：<kbd>Ctrl/Command</kbd> + <kbd>Y</kbd>
加粗：<kbd>Ctrl/Command</kbd> + <kbd>B</kbd>
斜体：<kbd>Ctrl/Command</kbd> + <kbd>I</kbd>
标题：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>H</kbd>
无序列表：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>U</kbd>
有序列表：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>O</kbd>
检查列表：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>C</kbd>
插入代码：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>K</kbd>
插入链接：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>L</kbd>
插入图片：<kbd>Ctrl/Command</kbd> + <kbd>Shift</kbd> + <kbd>G</kbd>
查找：<kbd>Ctrl/Command</kbd> + <kbd>F</kbd>
替换：<kbd>Ctrl/Command</kbd> + <kbd>G</kbd>

## 合理的创建标题，有助于目录的生成

直接输入1次<kbd>#</kbd>，并按下<kbd>space</kbd>后，将生成1级标题。
输入2次<kbd>#</kbd>，并按下<kbd>space</kbd>后，将生成2级标题。
以此类推，我们支持6级标题。有助于使用`TOC`语法后生成一个完美的目录。

## 如何改变文本的样式

*强调文本* _强调文本_

**加粗文本** __加粗文本__

==标记文本==

~~删除文本~~

> 引用文本

H~2~O is是液体。

2^10^ 运算结果是 1024.

## 插入链接与图片

链接: [link](https://www.csdn.net/).

图片: ![Alt](https://imgconvert.csdnimg.cn/aHR0cHM6Ly9hdmF0YXIuY3Nkbi5uZXQvNy83L0IvMV9yYWxmX2h4MTYzY29tLmpwZw)

带尺寸的图片: ![Alt](https://imgconvert.csdnimg.cn/aHR0cHM6Ly9hdmF0YXIuY3Nkbi5uZXQvNy83L0IvMV9yYWxmX2h4MTYzY29tLmpwZw =30x30)

居中的图片: ![Alt](https://imgconvert.csdnimg.cn/aHR0cHM6Ly9hdmF0YXIuY3Nkbi5uZXQvNy83L0IvMV9yYWxmX2h4MTYzY29tLmpwZw#pic_center)

居中并且带尺寸的图片: ![Alt](https://imgconvert.csdnimg.cn/aHR0cHM6Ly9hdmF0YXIuY3Nkbi5uZXQvNy83L0IvMV9yYWxmX2h4MTYzY29tLmpwZw#pic_center =30x30)

当然，我们为了让用户更加便捷，我们增加了图片拖拽功能。

## 如何插入一段漂亮的代码片

去[博客设置](https://mp.csdn.net/console/configBlog)页面，选择一款你喜欢的代码片高亮样式，下面展示同样高亮的 `代码片`.
```javascript
// An highlighted block
var foo = 'bar';

生成一个适合你的列表

  • 项目
    • 项目
      • 项目
  1. 项目1
  2. 项目2
  3. 项目3
  • 计划任务
  • 完成任务

创建一个表格

一个简单的表格是这么创建的：

项目 Value
电脑 $1600
手机 $12
导管 $1

设定内容居中、居左、居右

使用:---------:居中
使用:----------居左
使用----------:居右

第一列 第二列 第三列
第一列文本居中 第二列文本居右 第三列文本居左

SmartyPants

SmartyPants 是一个文本转换工具，主要功能是将普通的 ASCII 标点符号自动转换为更美观的印刷体标点符号。例如：

原始符号 转换后 说明
"引号" “引号” 直引号变弯引号
'单引号' ‘单引号’ 直单引号变弯单引号
-- – 两个连字符变短破折号
--- — 三个连字符变长破折号
... … 三个点变省略号

创建一个自定义列表

Markdown
Text-to- HTML conversion tool
Authors
John
Luke

如何创建一个注脚

一个具有注脚的文本。1

注释也是必不可少的

Markdown将文本转换为 HTML。

KaTeX数学公式

您可以使用渲染LaTeX数学表达式 KaTeX:

Gamma公式展示 Γ ( n ) = ( n − 1 ) ! ∀ n ∈ N \Gamma(n) = (n-1)!\quad\forall n\in\mathbb N Γ(n)=(n−1)!∀n∈N 是通过欧拉积分

Γ ( z ) = ∫ 0 ∞ t z − 1 e − t d t   . \Gamma(z) = \int_0^\infty t^{z-1}e^{-t}dt\,. Γ(z)=∫0∞​tz−1e−tdt.

你可以找到更多关于的信息 LaTeX 数学表达式here.

新的甘特图功能，丰富你的文章

2014-01-07 2014-01-09 2014-01-11 2014-01-13 2014-01-15 2014-01-17 2014-01-19 2014-01-21 已完成 进行中 计划一 计划二 现有任务 Adding GANTT diagram functionality to mermaid
  • 关于 甘特图 语法，参考 这儿,

UML图表

可以使用UML图表进行渲染，例如下面产生的一个序列图：

王五 李四 张三 王五 李四 张三 李四想了很长时间, 文字太长了 不适合放在一行. 你好！李四, 最近怎么样? 你最近怎么样，王五？ 我很好，谢谢! 我很好，谢谢! 打量着王五... 很好... 王五, 你怎么样?
  • 关于 UML图表 语法，参考 这儿,

流程图

链接

长方形

圆

圆角长方形

菱形
  • 关于 Mermaid 语法，参考 这儿,

FLowchart流程图

我们依旧会支持flowchart.js的流程图语法：

Created with Raphaël 2.3.0 开始 我的操作 确认？ 结束 yes no
  • 关于 Flowchart流程图 语法，参考 这儿.

导出与导入

导出

如果你想尝试使用此编辑器, 你可以在此篇文章任意编辑。当你完成了一篇文章的写作, 在上方工具栏找到 文章导出 ，生成一个.md文件或者.html文件进行本地保存。

导入

如果你想加载一篇你写过的.md文件，在上方工具栏可以选择导入功能进行对应扩展名的文件导入，
继续你的创作。

  1. 注脚的解释 ↩︎

# 数据库 # java # 服务器
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

我测试了一个0.9B模型，它竟然能自动区分多人讲话）

avatar AI Agent技术社区
cover

从一张商品图到正式上架：实测店匠 Shoplazza Athena，AI Agent 不只是聊天框

avatar AI Agent技术社区
cover

【AI Agent】《2026年9月 AI Agent全栈开发技术选型专项面试宝典》

avatar AI Agent技术社区