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 约束共享状态

python
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']}")

预期输出

text
normalized_query=langgraph 状态怎么定义?
route=knowledge

这个例子中,节点返回的是与状态字段同名的更新字典。TypedDict 能让 IDE 和静态类型检查器理解字段及其类型,也能让图的状态结构更清晰;但它本身不会把任意运行时值自动转换成正确类型。需要严格运行时校验时,应在图边界显式校验输入,或采用具备运行时校验能力的模型。

明确谁读、谁写

共享状态字段的读写责任

当某个字段同时被多个节点修改时,就需要进一步定义合并策略;在只有单一路径、单一写入者的场景里,保持“一字段一主要写入者”最容易维护。尤其不要让一个节点顺手修改与当前职责无关的字段,否则后续排查状态变化来源会很困难。

类型约束不能替代状态设计

类型只解决“这个字段允许是什么形态”,并不替你决定“这个字段为什么存在、由谁维护、何时有效”。设计状态时优先保留跨节点真正需要共享的数据;只在单个节点内部使用的临时变量留在函数内部,不要塞进共享状态。

一个可维护的状态定义应该让读者只看类型和字段表,就能回答三个问题:谁产生这个值、谁依赖这个值、这个值在图的哪个阶段开始可靠。做到这一点,后续增加条件边、并行分支或检查点时,状态仍然不会失去边界。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

定义共享状态与类型约束

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通