LangGraph 1.2+ 新特性：set_node_defaults，批量统一节点策略

前言

在用 LangGraph 开发 Agent 图的时候，经常会遇到一个痛点：图里面十几个节点，大部分都需要配置重试、超时、异常捕获。

如果每个 add_node 都手动写一遍 retry_policy、timeout，代码大量重复，改基线策略时要逐个节点修改，维护起来非常麻烦。

LangGraph 1.2.0 新增了 set_node_defaults，一句话概括：给整张图设置节点默认策略，批量复用重试 / 超时 / 缓存 / 错误处理器，单个节点还能单独覆盖。

核心作用

set_node_defaults 是构建器（StateGraph）上的链式方法，在 compile() 之前调用。作用：为当前图所有节点预设一套默认运行策略，避免重复传参。

支持 4 项默认配置：

retry_policy：节点失败重试策略
timeout：节点执行超时策略
cache_policy：节点结果缓存策略
error_handler：节点异常兜底处理函数

优先级规则（非常关键）

add_node 单独传入策略 > set_node_defaults 全局默认策略

单个节点自定义参数会直接覆盖全局默认，适合：大部分节点共用基线，少数节点特殊定制。

生效范围⚠️

retry_policy / timeout：作用所有节点，包括错误处理器节点
cache_policy / error_handler：仅普通业务节点，不会作用到 error_handler 自身，防止异常处理函数再次报错造成无限递归
不会自动继承到子图 subgraph ，子图需要单独调用 set_node_defaults

最简可运行示例

python 复制代码

from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START
from langgraph.types import RetryPolicy, TimeoutPolicy
from langgraph.errors import NodeError

# 定义状态
class State(TypedDict):
    msg: str

# 全局统一异常兜底
def global_error_handler(state: State, error: NodeError):
    return {"msg": f"节点捕获异常：{error.error}"}

def node_a(state: State):
    return {"msg": "执行节点A"}

def node_b(state: State):
    return {"msg": "执行节点B"}

builder = (
    StateGraph(State)
    # 设置全局节点默认策略
    .set_node_defaults(
        retry_policy=RetryPolicy(max_attempts=3), # 默认重试3次
        timeout=TimeoutPolicy(run_timeout=30),    # 默认30秒超时
        error_handler=global_error_handler,
    )
    .add_node("node_a", node_a)
    # node_b单独覆盖重试次数，优先级高于全局默认
    .add_node("node_b", node_b, retry_policy=RetryPolicy(max_attempts=5))
    .add_edge(START, "node_a")
)

graph = builder.compile()
res = graph.invoke({"msg": "start"})
print(res)

适用场景

✅ Agent 图包含大量 LLM、工具调用节点，统一配置重试和超时，提升生产稳定性 ✅ 需要统一全局异常兜底，不用每个节点写 try/except ✅ 大部分节点共用一套策略，少量节点单独特殊配置

版本提醒

set_node_defaults 1.2.0 版本才加入，1.0 /1.1 版本无此 API，升级版本前注意代码兼容性。

小结

set_node_defaults 本质是减少样板代码，统一图的容错基线。

全局配置一次，所有节点继承
单节点可按需覆盖，灵活可控
子图不会自动继承，子图需要单独配置

在生产级 Agent 开发中，这个 API 可以大幅简化大图维护，非常推荐。