文章目录
- 1.状态 (State)
-
- [1.1 TypedDict字典定义(推荐)](#1.1 TypedDict字典定义(推荐))
- [1.2 @dataclass定义](#1.2 @dataclass定义)
- [1.3 Pydantic定义](#1.3 Pydantic定义)
- [1.4 三种定义状态方法的区别](#1.4 三种定义状态方法的区别)
- 2.节点(Node)
- 3.Edge(边)
- [4. 举例](#4. 举例)
-
- [4.1 graph = builder.compile() 实例化](#4.1 graph = builder.compile() 实例化)
- [4.2 result = graph.invoke({"cur_id":"start"})](#4.2 result = graph.invoke({"cur_id":"start"}))
- [4.3 绘制可视化流程图](#4.3 绘制可视化流程图)
1.状态 (State)
langgraph 运行时共享的数据结构,承载图运行时所需要的上下文信息,是节点之间传递信息的核心载体.
1.1 TypedDict字典定义(推荐)
python
# 1 定义状态
class OverAllState(TypedDict):
# 日志类型还是 list[str] 更新的方式不是覆盖 add 是追加
logs: Annotated[list[str],add]
cur_id: str
1.2 @dataclass定义
注意:
1.节点可以返回字典,一般会自动转化为状态类;
2.访问状态属性需要使用".",而不再是\[\]的方式;
python
class OverAllState:
# 日志类型还是 list[str] 更新的方式不是覆盖 add 是追加
logs: Annotated[list[str],add]
cur_id: str
1.3 Pydantic定义
python
# 1 定义状态
class OverAllState(BaseModel):
# 日志类型还是 list[str] 更新的方式不是覆盖 add 是追加
logs: Annotated[list[str],add]
cur_id: str
1.4 三种定义状态方法的区别
三种写法都能描述同一份状态结构,但在类型校验、默认值、访问方式和运行时行为上差别明显,实际选型时可按下面的对比来取舍。
| 维度 | TypedDict(普通字典) | @dataclass | Pydantic(BaseModel) |
|---|---|---|---|
| 运行时类型校验 | 无,仅静态类型提示 | 无,仅静态类型提示 | 有,实例化时校验并转换类型 |
| 访问方式 | state["cur_id"] |
state.cur_id |
state.cur_id |
| 默认值支持 | 不支持,需在节点里自行兜底 | 支持,字段可直接赋默认值 | 支持,字段可直接赋默认值 |
| 嵌套结构 / 复杂校验 | 弱 | 一般 | 强,支持嵌套模型、约束、自定义校验器 |
| 序列化 | 天然是 dict,最省事 | 需 asdict() 转换 |
内置 model_dump() / model_validate() |
| 性能开销 | 最低 | 低 | 略高(有校验与转换成本) |
| 与 LangGraph 契合度 | 官方示例最常用,节点返回 dict 即可 | 可用,但节点返回 dict 时需注意自动转换 | 可用,适合状态结构复杂、需要强校验的场景 |
几点实践建议:
- 入门与简单场景优先用
TypedDict:它最贴近 LangGraph 官方示例,节点直接返回 dict,框架按dict.update()的方式增量合并,心智负担最小。 - 需要默认值或方法时用
@dataclass:字段可以带默认值,也能挂一些辅助方法;但要注意节点返回字典时框架会做自动转换,访问属性要用.而不是[]。 - 状态复杂、需要强校验时用 Pydantic:比如字段有取值范围约束、嵌套子模型、需要从外部 JSON 反序列化,Pydantic 的校验和序列化能力能省掉大量手写判断。
- Reducer 与定义方式无关 :无论用哪种写法,
Annotated[list[str], add]这类 Reducer 都照常生效,决定的是「同名字段如何合并」,而不是「用什么类来定义状态」。
一句话总结:结构简单选 TypedDict,要默认值选 dataclass,要校验和序列化选 Pydantic;三者可以混用,但同一个图里建议保持统一,避免风格割裂。
2.节点(Node)
langgraph具体执行单元,通常为一个函数. 执行逻辑,并返回 状态 (State),字典 , 框架拿到这个字典后,会像 Python 的 dict.update() 方法一样,把新数据增量合并到全局状态中。
3.Edge(边)
定义节点之间固定的执行顺序,还通过条件边根据当前状态实现动态路由与分支决策;同时,它负责连接 START 和 END 等虚拟节点,构建出完整的执行闭环。
4. 举例
python
from langgraph.graph import StateGraph,START,END
from typing import TypedDict, Annotated
from operator import add
# 1 定义状态
class OverAllState(TypedDict):
# 日志类型还是 list[str] 更新的方式不是覆盖 add 是追加
logs: Annotated[list[str],add]
cur_id: str
# 2 定义节点
def node_1(state:OverAllState) -> OverAllState:
pre_id = state["cur_id"]
return {
"logs": ["node_1 运行完毕"],
"cur_id": pre_id + ", node_1"
}
def node_2(state:OverAllState) -> OverAllState:
pre_id = state["cur_id"]
return {
"logs": ["node_2 运行完毕"],
"cur_id": pre_id + ", node_2"
}
# 3 定义边
# 3.1 创建图 获取建造者
##创建图,其中state_schema是类型,必须的入参
builder = StateGraph( state_schema=OverAllState)
# 3.2 添加节点
## 组装边
builder.add_node(node_1)
builder.add_node(node_2)
# 3.3 添加边
## 绘制流程
builder.add_edge(START,"node_1")
builder.add_edge("node_1","node_2")
builder.add_edge("node_2",END)
# 4 获取图
## builder校验并实例化
graph = builder.compile()
# 5 运行图
## builder启动/调用
result = graph.invoke({"cur_id":"start"})
print(result)
运行结果:

4.1 graph = builder.compile() 实例化
graph = builder.compile() 的作用将图结构(StateGraph)编译成一个可执行的运行时实例; 在 LangGraph 中,StateGraph 本身只是一个静态的结构定义,它包含了节点、边、状态类型等信息,但还不能直接运行。只有调用 .compile() 方法后,LangGraph 才会:
- 校验图的完整性:检查是否有孤立节点、是否定义了入口点(START)、边是否连通等,确保图结构合法。
- 注入运行时引擎:将图结构转换为 CompiledStateGraph 对象,这个对象实现了 LangChain 的 Runnable 接口,支持 invoke()、stream()、batch() 等标准调用方式。
- 绑定状态管理机制:将 OverAllState 的类型注解、Reducer(如 add)等规则固化到运行时,确保后续每个节点执行时都能正确读写和更新状态。
- 可选地集成持久化与断点:你可以在 compile() 时传入 checkpointer 参数,让图具备记忆能力,支持从历史状态恢复或人工干预。
4.2 result = graph.invoke({"cur_id":"start"})
- 接收输入: 拿到你传入的 {"cur_id": "start"}。
- 结合 Schema: 拿出之前定义的 OverAllState 类(作为蓝图)。
- 创建/合并状态:
- 它会创建一个内部的状态对象 OverAllState。
- 它会把你传入的 initial_state 填充进去。
- 对于你没传的字段(比如 logs),如果定义了默认值或 Reducer(如 add),它会进行初始化处理(例如初始化为空列表)。
4.3 绘制可视化流程图
- 代码描述
python
raw_mermaid = graph.get_graph().draw_mermaid()
print(raw_mermaid)
>
---
config:
flowchart:
curve: linear
---
graph TD;
__start__([<p>__start__</p>]):::first
node_1(node_1)
node_2(node_2)
__end__([<p>__end__</p>]):::last
__start__ --> node_1;
node_1 --> node_2;
node_2 --> __end__;
classDef default fill:#f2f0ff,line-height:1.2
classDef first fill-opacity:0
classDef last fill:#bfb6fc
- 图描述
python
from IPython.display import display, Image
png_bytes = graph.get_graph().draw_mermaid_png()
png = Image(png_bytes)
display(png)
