LangGraph 1.2.0 发布：新增 set_node_defaults 统一节点策略配置

LangGraph 1.2.0 新增批量节点策略配置能力，支持统一设置重试、超时、缓存与错误处理器。

LangGraph 1.2.0 正式发布：节点策略配置迎来重大简化

LangGraph 官方于近期推出 1.2.0 版本，其中最值得关注的新特性是新增 set_node_defaults 方法，允许开发者在构建图时统一配置所有节点的默认运行策略，显著减少重复代码与维护成本。该功能需在 compile() 编译前调用，生效于当前图的所有普通节点。

核心功能与技术细节

set_node_defaults 是 StateGraph 构建器上的链式方法，支持配置以下四种默认策略：

retry_policy：节点失败重试策略，用于处理临时性故障
timeout：节点执行超时策略，防止任务无限挂起
cache_policy：节点结果缓存策略，提升重复调用效率
error_handler：节点异常兜底处理函数，统一异常捕获逻辑

关键优先级规则为：单节点 add_node 传入的策略会覆盖全局默认策略。这意味着开发者可为大多数节点设置共享基线，仅对特殊节点进行单独定制。

生效范围方面存在明确区分：

retry_policy 与 timeout 作用于所有节点，包括错误处理器节点
cache_policy 与 error_handler 仅作用于普通业务节点，不会作用于错误处理器自身，以避免异常处理函数再次报错造成无限递归
子图（subgraph）不会自动继承父图的默认策略，需单独调用 set_node_defaults

使用场景与代码示例

在生产级 Agent 开发中，当图结构包含十几个甚至更多节点（通常涉及 LLM 调用与工具调用）时，此前必须在每个 add_node 调用中重复传入 retry_policy、timeout 等参数。这不仅造成大量样板代码，还使得策略基线变更时需要逐个节点修改，维护效率低下。

新版本下，代码结构得以大幅简化：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
builder = (
    StateGraph(State)
    .set_node_defaults(
        retry_policy=RetryPolicy(max_attempts=3),
        timeout=TimeoutPolicy(run_timeout=30),
        error_handler=global_error_handler,
    )
    .add_node("node_a", node_a)
    .add_node("node_b", node_b, retry_policy=RetryPolicy(max_attempts=5))
    .add_edge(START, "node_a")
)

上述示例中，node_a 使用全局默认的 3 次重试，而 node_b 单独覆盖为 5 次重试，单节点定制与全局配置可灵活共存。

落地建议

立即适用：适用于中大型 Agent 图项目，尤其是节点数超过 5 个、且多数节点需要相同容错配置的场景
建议再等等：若项目当前稳定运行于 LangGraph 1.1 或更早版本，且节点数量较少（≤3 个）或策略差异较大，升级优先级可降低；此外需注意该 API 仅在 1.2.0+ 版本可用，低版本无此功能

写在最后

set_node_defaults 的本质是将运行时策略从节点层面提升至图层面，体现了 LangGraph 在生产可用性上的持续演进。这一变更虽非颠覆性创新，但通过减少样板代码与统一错误处理，显著改善了开发者体验与长期可维护性。

主站 | Komari