文章目录Multi Schema用法状态类型状态之间的关系设计规范源码层面的约束状态的记录状态的访问案例案例执行过程分析1. 输入状态2. 全局状态3. 私有状态4. 输出状态Multi Schema用法状态类型LangGraph支持在一个图中使用多个状态 Schema用于区分图的外部输入、外部输出、内部共享状态以及节点间的临时状态。常见状态类型可以分为以下几类全局状态 / 内部状态图内部主要使用的状态创建StateGraph时传递给state_schema参数。它通常包含图运行过程中需要读写的大部分字段。输入状态图对外接收输入时使用的状态创建StateGraph时传递给input_schema参数。它用于约束调用图时允许传入哪些字段。输出状态图最终对外返回结果时使用的状态创建StateGraph时传递给output_schema参数。它用于约束图运行结束后只返回哪些字段。私有状态图内部节点之间传递的临时状态通常不作为图的输入也不作为图的最终输出。它可以通过节点函数的入参类型注解声明并在节点返回值中写入。需要注意输入状态和输出状态主要面向图的边界即“图如何接收外部输入”和“图如何返回外部结果”而全局状态和私有状态主要面向图内部节点之间的数据传递。状态之间的关系设计规范本节主要说明LangGraph状态设计中的规范。以下规则属于工程上的最佳实践违反这些规范未必一定导致程序报错但容易降低代码的可读性和可维护性。输入状态和输出状态通常应是全局状态的子集输入状态描述图对外需要接收的数据输出状态描述图最终需要返回的数据。通常情况下它们都应该是全局状态的一部分。如classInputState(TypedDict):username:strclassOutputState(TypedDict):graph_output:strclassOverAllState(TypedDict):username:strnickname:strgraph_output:str其中InputState和OutputState的所有字段均存在于OverAllState中。私有状态和全局状态应尽量避免字段重名私有状态的定位是图内部某些节点之间传递的临时字段。如果私有状态字段和全局状态字段重名虽然某些情况下程序仍然可以运行但容易让人误以为该字段是全局共享字段从而造成理解混乱。因此推荐让私有状态字段和全局状态字段保持清晰边界。节点函数应明确声明入参状态类型和返回状态类型节点函数的第一个参数通常是当前节点可读取的状态。通过类型注解声明该参数可以明确表达该节点需要读取哪些字段。同时给节点函数声明返回状态类型也可以帮助阅读者理解该节点会更新哪些字段。例如defnode_1(state:InputState)-OverAllState:return{nickname:Dear state[username]}节点函数中不应该访问入参状态类型中不存在的字段节点实际接收到的状态会按照其入参类型进行裁剪。因此如果节点入参声明为InputState就不应该在节点内部访问InputState中不存在的字段。例如defnode_1(state:InputState)-OverAllState:return{nickname:state[username]}如果在该函数中访问state[nickname]而nickname不属于InputState运行时就可能抛出KeyError。节点函数返回的字典应尽量和返回类型注解保持一致从 Python 类型注解的角度看函数返回类型只是静态提示运行时不会自动强制校验。从 LangGraph 的运行机制看节点返回的是对状态的部分更新不是完整状态。只要返回字段已经被图记录为可用状态字段LangGraph 就可以将其作为状态更新处理。不过从工程规范上讲节点返回字典中的字段最好和函数返回类型注解保持一致这样更利于阅读、调试和维护。源码层面的约束本节从底层机制角度说明LangGraph如何记录、裁剪和更新状态。状态的记录LangGraph的状态并不是简单保存在一个普通字典中而是会被拆分成多个可读写的状态字段。每个状态字段在底层通常对应一个Channel。这些状态字段会在不同阶段被记录到状态图中。StateGraph记录状态字段的核心方法是_add_schema()_add_schema()会解析传入的状态 Schema并将其中声明的字段记录到图中使这些字段成为图运行时可以读写的状态字段。创建StateGraph时会记录state_schema、input_schema和output_schema中的字段当创建状态图时builder StateGraph( OverAllState, input_schemaInputState, output_schemaOutputState )LangGraph 会解析这些 Schema并将其中涉及的字段加入图的状态管理体系。调用add_node()添加节点时也可能记录节点入参声明的状态 Schema当添加节点时LangGraph会根据节点函数第一个参数的类型注解推断该节点的输入状态类型。如果这个输入状态类型之前没有被图记录过LangGraph 也会通过_add_schema()将其加入图中。这也是私有状态能够生效的原因。例如classPrivateState(TypedDict):greeting:strdefnode_3(state:PrivateState)-OutputState:return{graph_output:state[greeting]}当node_3被添加到图中时PrivateState中的greeting字段会被记录到图中从而成为图内部可以传递的状态字段。总结全局状态、输入状态、输出状态通常在创建StateGraph时被记录。私有状态通常在调用add_node()添加节点时根据节点入参类型注解被记录。被记录后的状态字段底层会成为图运行时可以读写的状态字段。状态的访问调用图时输入会按照input_schema进行约束当调用图时graph.invoke({username:小黄})如果创建图时声明了input_schema那么外部输入会按照input_schema进行约束。如果没有声明input_schema则通常按照state_schema作为图的输入 Schema。因此input_schema的作用不是“只让第一个节点可见”而是约束图的外部输入结构。此处的约束是指按照schema裁剪输入只保留schema中出现的状态字段节点接收到的状态会按照节点入参类型进行裁剪每个节点能读取哪些字段主要取决于该节点第一个参数的类型注解。例如defnode_1(state:InputState)-OverAllState:...此时node_1接收到的state会按照InputState进行裁剪。即使图的全局状态中还有其他字段node_1也不应该访问不属于InputState的字段。如果访问了入参状态中不存在的字段例如state[nickname]就可能抛出KeyError节点返回的是状态更新而不是完整状态节点函数不需要返回完整状态只需要返回本节点想要更新的字段。例如defnode_1(state:InputState)-OverAllState:return{nickname:Dear state[username]}这里虽然返回类型注解是OverAllState但函数实际只返回了nickname一个字段。这是允许的因为 LangGraph 会把节点返回值视为对状态的部分更新。节点返回值的应用主要由字段名称和图中已记录的状态字段决定节点返回的字典会根据字段名称写入对应状态字段并按照该字段的Reducer规则进行合并。需要注意的是函数返回类型注解主要用于表达代码意图不是严格的运行时写入边界。也就是说如果某个字段已经被图记录为可用状态字段那么节点即使没有在返回类型注解中声明该字段也可能仍然可以返回并更新它。不过为了代码清晰仍然推荐让节点的返回值和返回类型注解保持一致。最终输出会按照output_schema进行裁剪图运行完成后最终返回给外部调用方的结果会按照output_schema进行裁剪。因此output_schema的作用不是“只让最后一个节点可见”而是约束图最终对外暴露哪些字段。例如图内部状态中可能同时存在username nickname greeting graph_output但如果output_schema只包含graph_output那么最终graph.invoke()的返回结果就只会包含graph_output。案例下面通过一个简单案例说明四类状态的定义和使用。fromtypingimportTypedDictfromlanggraph.graphimportStateGraph,START,ENDclassInputState(TypedDict):username:strclassOutputState(TypedDict):graph_output:strclassOverAllState(TypedDict):nickname:strusername:strgraph_output:strclassPrivateState(TypedDict):greeting:strdefnode_1(state:InputState)-OverAllState:# 向全局状态写入数据return{nickname:Dear state[username]}defnode_2(state:OverAllState)-PrivateState:# 从全局状态读取数据写入私有状态return{greeting:state[nickname], 早上好~}defnode_3(state:PrivateState)-OutputState:# 从私有状态读取数据写入输出状态return{graph_output:state[greeting] 很高兴认识你}builderStateGraph(OverAllState,input_schemaInputState,output_schemaOutputState)builder.add_node(node_1,node_1)builder.add_node(node_2,node_2)builder.add_node(node_3,node_3)builder.add_edge(START,node_1)builder.add_edge(node_1,node_2)builder.add_edge(node_2,node_3)builder.add_edge(node_3,END)graphbuilder.compile()print(graph.invoke({username:小黄}))输出如下{graph_output:Dear 小黄, 早上好~ 很高兴认识你}案例执行过程分析上述案例中各类状态的作用如下。1. 输入状态classInputState(TypedDict):username:strInputState用于约束图的外部输入。因此调用图时只需要传入{username: 小黄}2. 全局状态classOverAllState(TypedDict):username:strnickname:strgraph_output:strOverAllState是图内部主要使用的状态 Schema。其中username来自图的输入nickname由node_1写入graph_output由node_3写入并最终作为图的输出返回。3. 私有状态classPrivateState(TypedDict):greeting:strPrivateState用于节点之间传递临时数据。在本例中defnode_2(state:OverAllState)-PrivateState:return{greeting:state[nickname], 早上好~}node_2写入了greeting字段。随后defnode_3(state:PrivateState)-OutputState:return{graph_output:state[greeting] 很高兴认识你}node_3通过PrivateState读取greeting字段并生成最终输出。4. 输出状态classOutputState(TypedDict):graph_output:strOutputState用于约束图最终返回给外部调用方的数据。虽然图内部运行过程中还存在username、nickname、greeting等字段但最终结果只返回{graph_output:Dear 小黄, 早上好~ 很高兴认识你}这是因为图创建时声明了output_schemaOutputState所以最终输出会按照OutputState进行裁剪。