AI Agent / 系统课时
定义共享状态与类型约束
定义共享状态与类型约束
共享状态是节点之间最重要的接口合同。这一节用 TypedDict 明确状态字段的名称、类型与读写责任,再用一个可运行的小图验证:调用方写入原始问题,后续节点只读取需要的字段并返回局部更新。
学习目标
- 能用
TypedDict、NotRequired和Literal描述共享状态的数据形态。 - 能为每个状态字段明确写入者、读取者与更新时机。
- 能区分静态类型约束与运行时数据校验,避免把类型提示当成自动校验器。
把状态定义成接口合同
状态字段不应随着节点增多而随意添加。先列出真正需要跨节点共享的数据,再为每个字段规定类型和责任边界,可以让节点之间的依赖显式化。
下面这个状态只包含三个字段:调用方提供 query,normalize 节点写入 normalized_query,choose_route 节点根据规范化后的问题写入 route。后两个字段在图启动时还不存在,所以用 NotRequired 表示它们不是初始输入的必填项。
| 字段 | 类型 | 主要写入者 | 主要读取者 |
|---|---|---|---|
query |
str |
调用方 | normalize |
normalized_query |
str |
normalize |
choose_route |
route |
Literal["knowledge", "fallback"] |
choose_route |
后续路由逻辑 |
用 TypedDict 约束共享状态
from typing import Literal, NotRequired, TypedDict
from langgraph.graph import END, START, StateGraph
class AgentState(TypedDict):
query: str
normalized_query: NotRequired[str]
route: NotRequired[Literal["knowledge", "fallback"]]
def normalize(state: AgentState) -> dict[str, str]:
# 只负责把原始问题转成后续节点统一使用的形式。
normalized = state["query"].strip().lower()
return {"normalized_query": normalized}
def choose_route(
state: AgentState,
) -> dict[str, Literal["knowledge", "fallback"]]:
# 该节点只依赖 normalize 已经产出的 normalized_query。
route = (
"knowledge"
if "langgraph" in state["normalized_query"]
else "fallback"
)
return {"route": route}
builder = StateGraph(AgentState)
builder.add_node("normalize", normalize)
builder.add_node("choose_route", choose_route)
builder.add_edge(START, "normalize")
builder.add_edge("normalize", "choose_route")
builder.add_edge("choose_route", END)
graph = builder.compile()
result = graph.invoke({"query": " LangGraph 状态怎么定义? "})
print(f"normalized_query={result['normalized_query']}")
print(f"route={result['route']}")预期输出
normalized_query=langgraph 状态怎么定义?
route=knowledge这个例子中,节点返回的是与状态字段同名的更新字典。TypedDict 能让 IDE 和静态类型检查器理解字段及其类型,也能让图的状态结构更清晰;但它本身不会把任意运行时值自动转换成正确类型。需要严格运行时校验时,应在图边界显式校验输入,或采用具备运行时校验能力的模型。
明确谁读、谁写

当某个字段同时被多个节点修改时,就需要进一步定义合并策略;在只有单一路径、单一写入者的场景里,保持“一字段一主要写入者”最容易维护。尤其不要让一个节点顺手修改与当前职责无关的字段,否则后续排查状态变化来源会很困难。
类型约束不能替代状态设计
类型只解决“这个字段允许是什么形态”,并不替你决定“这个字段为什么存在、由谁维护、何时有效”。设计状态时优先保留跨节点真正需要共享的数据;只在单个节点内部使用的临时变量留在函数内部,不要塞进共享状态。
一个可维护的状态定义应该让读者只看类型和字段表,就能回答三个问题:谁产生这个值、谁依赖这个值、这个值在图的哪个阶段开始可靠。做到这一点,后续增加条件边、并行分支或检查点时,状态仍然不会失去边界。