LangGraph 1.2+ set_node_defaults：集中配置节点默认策略

作者：袖梨 2026-09-16

随着 Agent 图中的业务节点不断增加，重试、超时和异常兜底等运行策略很容易散落在多次 add_node 调用中，不仅代码冗余，后续调整基线配置也十分费力。LangGraph 提供的 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

最简可运行示例

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)