文章目录先说结论5.1 使用 Overwrite 绕过 reducer为什么需要 Overwrite代码示例运行结果说明适用场景实战提醒5.2 使用独立的输入 / 输出模式为什么要区分输入、输出和内部状态参数含义代码示例结果说明这个设计的价值实战建议5.3 在节点间传递私有状态一个典型例子代码示例一次执行后你会看到什么这种设计适合什么场景这里最容易误解的一点三个能力放在一起怎么理解最清楚1. Overwrite2. input_schema / output_schema / state_schema3. 节点间私有状态实战里怎么选场景 1字段需要继续累积场景 2字段需要整段替换场景 3对外接口和内部状态不一致场景 4中间敏感数据只允许局部流转常见坑点坑 1以为所有状态更新都应该走 append坑 2把内部中间字段直接暴露给输出坑 3把“最终不输出”和“节点不可见”混为一谈坑 4状态设计过早贪大总结这一篇专门讲 LangGraph 里三个很容易被忽略、但一旦做复杂工作流就绕不过去的能力Overwrite、独立的输入/输出模式以及节点间私有状态传递。先说结论如果已经会写最基础的StateGraph接下来最该补的不是更多节点而是状态管理能力。因为真实项目里问题通常不是“图不会跑”而是某个字段到底该追加还是覆盖用户输入、内部状态、最终输出能不能分开中间节点的敏感数据怎么在节点之间传递但不暴露给外部这三个问题刚好对应本文的三个主题使用Overwrite绕过 reducer使用独立输入/输出模式控制图的边界在节点之间传递私有状态5.1 使用 Overwrite 绕过 reducer在 LangGraph 中reducer用来控制状态更新的处理方式。默认情况下每个状态键都可以配置自己的 reducer 函数用于决定多个节点更新同一个字段时应该如何合并。最常见的例子就是消息列表正常对话时新消息通常会追加到messages中但某些场景下我们并不想追加而是希望直接覆盖旧值这时就需要Overwrite。为什么需要 Overwrite可以想象一个聊天系统平时的消息流转都是不断往消息列表后面追加内容但如果用户点击“清空上下文并重新开始”这时就不应该继续 append你要的不是“合并”而是“整段替换”也就是说reducer 负责“怎么合”Overwrite负责“这次别合了直接替换”代码示例fromlanggraph.graphimportStateGraph,START,ENDfromlanggraph.typesimportOverwritefromtyping_extensionsimportAnnotated,TypedDictimportoperatorclassState(TypedDict):messages:Annotated[list,operator.add]defadd_message(state:State):return{messages:[first message]}defreplace_messages(state:State):# 绕过 reducer直接替换整个 messages 列表return{messages:Overwrite([replacement message])}builderStateGraph(State)builder.add_node(add_message,add_message)builder.add_node(replace_messages,replace_messages)builder.add_edge(START,add_message)builder.add_edge(add_message,replace_messages)builder.add_edge(replace_messages,END)graphbuilder.compile()resultgraph.invoke({messages:[]})print(result)运行结果说明如果没有Overwrite最终的messages往往会变成[first message,replacement message]但用了Overwrite之后最终结果会变成[replacement message]也就是直接覆盖原状态而不是走operator.add的追加逻辑。适用场景清空聊天记录并重新开始重置工作流上下文覆盖缓存字段重新生成某一段中间结果异常恢复时替换错误状态实战提醒Overwrite很好用但不要滥用。因为一旦使用覆盖语义意味着你跳过了原本的状态合并规则。适合“明确要重置”的场景不适合日常状态流转。一句话总结默认用 reducer 合并只有在确实要“整段替换”时再用Overwrite。5.2 使用独立的输入 / 输出模式默认情况下LangGraph 使用单一状态模式也就是输入是这份状态节点内部流转是这份状态最终输出还是这份状态这在小 Demo 里很方便但真实业务里往往不够优雅。因为我们通常希望输入模式只暴露用户需要传入的字段输出模式只返回用户真正关心的结果内部状态保存节点间流转所需的完整信息换句话说内部状态不一定应该完全暴露给外部。为什么要区分输入、输出和内部状态以一个问答系统为例输入用户的问题question输出模型答案answer内部可能还会有retrieved_docs、tool_calls、rewrite_count等中间字段这些内部字段对系统很重要但对调用方并不友好也没必要都返回。这时就可以使用StateGraph的这几个参数input_schemaoutput_schemastate_schema参数含义参数名作用input_schema定义图接收的输入结构output_schema定义图最终返回的输出结构state_schema定义图内部完整状态结构代码示例fromlanggraph.graphimportStateGraph,START,ENDfromtyping_extensionsimportTypedDict# 1. 输入模式只接收 questionclassInputState(TypedDict):question:str# 2. 输出模式只返回 answerclassOutputState(TypedDict):answer:str# 3. 内部完整状态同时包含输入和输出classOverallState(InputState,OutputState):passdefanswer_node(state:InputState):理解用户问题并生成答案return{question:state[question],answer:fAnswer to:{state[question]},}builderStateGraph(OverallState,input_schemaInputState,output_schemaOutputState,)builder.add_node(answer_node,answer_node)builder.add_edge(START,answer_node)builder.add_edge(answer_node,END)graphbuilder.compile()resultgraph.invoke({question:What is LangGraph?})print(result)结果说明输出会是{answer:Answer to: What is LangGraph?}注意一点question虽然存在于内部状态中但因为output_schemaOutputState所以它不会出现在最终返回结果里这个设计的价值这类模式在工程里非常有用尤其适合下面几类场景API 开发输入输出契约清晰微服务避免内部字段直接外泄数据管道明确每一步的边界Agent 系统内部状态可以复杂外部接口保持简洁实战建议如果图已经开始出现这些字段debug_infointermediate_resulttrace_idtool_resultsensitive_data那就说明很可能已经不适合继续用“单一状态模式”了。这个时候尽快拆出对外输入模式对外输出模式内部完整状态后面维护成本会低很多。5.3 在节点间传递私有状态在复杂图里经常会有一种需求某些中间数据对后续节点很重要但这些数据不应该出现在最终输出里甚至不应该被所有节点看到这就是“私有状态”的问题。一个典型例子假设要做一个报告生成流程节点 1从数据库读取原始数据其中包含敏感信息节点 2清洗和脱敏这些数据节点 3基于清洗后的结果生成最终报告这里有个核心要求节点 1 和 节点 2 之间需要共享敏感数据但 节点 3 不应该看到原始敏感数据最终输出更不应该包含这些内容这时就可以通过节点特定输入 / 输出类型来实现局部传递。代码示例fromlanggraph.graphimportStateGraph,START,ENDfromtyping_extensionsimportTypedDict# 公共状态最终对外可见classOverallState(TypedDict):final_result:str# 节点1的私有输出classNode1Output(TypedDict):sensitive_data:str# 节点2需要的输入classNode2Input(TypedDict):sensitive_data:strdefnode_1(state:OverallState)-Node1Output:第一步获取包含敏感信息的原始数据private_data这是敏感信息print(Node1: 获取到敏感数据但不会暴露给最终输出)return{sensitive_data:private_data}defnode_2(state:Node2Input)-OverallState:第二步处理敏感数据输出清洗结果print(fNode2: 正在处理敏感数据:{state[sensitive_data]})return{final_result:清理后的处理结果}defnode_3(state:OverallState)-OverallState:第三步只消费公开结果不接触敏感信息print(fNode3: 只看到最终结果:{state[final_result]})return{final_result:state[final_result] - 完成}builderStateGraph(OverallState)# 这里顺序执行三个节点builder.add_sequence([node_1,node_2,node_3])builder.add_edge(START,node_1)graphbuilder.compile()responsegraph.invoke({final_result:initial})print(response)一次执行后你会看到什么Node1: 获取到敏感数据但不会暴露给最终输出 Node2: 正在处理敏感数据: 这是敏感信息 Node3: 只看到最终结果: 清理后的处理结果 最终输出: {final_result: 清理后的处理结果 - 完成}从这个过程可以看出sensitive_data在节点 1 和节点 2 之间传递成功它没有进入最终输出节点 3 只看到清洗后的结果这就是私有状态传递的价值。这种设计适合什么场景数据处理中间步骤的临时字段认证流程token、验证码、密钥片段金融或订单系统原始明细与脱敏结果分离Agent 工具链工具原始返回和最终摘要分离错误处理内部错误详情与对外错误消息分离这里最容易误解的一点很多人会以为“只要字段不在最终output_schema中就算私有状态了。”这不完全对。因为“最终不输出”和“只在特定节点间传递”是两个层次的问题output_schema解决的是“对外暴露什么”节点专属输入输出类型解决的是“哪些节点能看到什么”也就是说不返回给外部不等于不在内部传播真正的私有状态需要你在节点间显式控制可见范围三个能力放在一起怎么理解最清楚你可以把这三者理解成三个不同层面的控制能力1.Overwrite解决的是状态更新时到底是合并还是覆盖2.input_schema/output_schema/state_schema解决的是图的输入边界、输出边界、内部状态边界怎么划分3. 节点间私有状态解决的是某些中间数据应该在谁和谁之间流动不应该被谁看到如果把它们组合起来你对 LangGraph 的状态管理就已经不再停留在“能跑”的层面而是进入“可控、可维护、可上线”的层面。实战里怎么选如果你在写 LangGraph 工作流可以按这个判断顺序来场景 1字段需要继续累积选 reducer比如operator.addadd_messages适用于消息历史日志列表检索结果集合场景 2字段需要整段替换选Overwrite适用于重置上下文覆盖缓存清空后重新开始场景 3对外接口和内部状态不一致拆分input_schemaoutput_schemastate_schema适用于API 服务复杂 Agent 编排内部字段较多的工作流场景 4中间敏感数据只允许局部流转使用节点特定的输入 / 输出状态定义适用于敏感字段处理脱敏链路内部审核与对外结果分离常见坑点坑 1以为所有状态更新都应该走 append并不是。有些字段天然就是“覆盖型”这时继续 append 只会让状态越来越脏。坑 2把内部中间字段直接暴露给输出这在 Demo 里看起来无所谓但在正式接口里会带来两个问题返回结构混乱泄露内部实现细节坑 3把“最终不输出”和“节点不可见”混为一谈前者是输出层控制。后者是节点级状态可见性控制。这两个不是一回事。坑 4状态设计过早贪大很多人一开始就把所有字段都堆进一个大TypedDict里后面越改越难。更好的方式是先定义最小公共状态再按节点职责拆出局部状态最后用输入 / 输出模式划边界总结LangGraph 的强大不只体现在“能把节点连起来”更体现在它对状态流转的控制力。这篇讲的三个点本质上对应三个非常关键的问题Overwrite控制更新方式输入 / 输出模式控制对外边界私有状态控制内部可见性如果想把 LangGraph 从 Demo 写到真实项目这三个能力迟早都要补上。最后用一句话收尾图结构决定流程状态设计决定系统质量。