
设想一个画面:你的支付节点超时后 200 毫秒,支付渠道那边才真正扣款成功。你的图状态显示"什么都没发生",渠道说"卡已经扣了",而 LangGraph 按照默认配置,正准备再扣一次。
这不是假设。langgraph 1.2 引入了 per-node timeout 和 node 级 error handler,大家的注意力都在功能本身,但真正危险的是超时和重试、副作用搅在一起的方式——这个组合极容易配错。
结账 Agent 有个节点负责扣款。渠道偶尔卡住,于是你很"负责"地给它加个超时:
builder.add_node(
"charge_customer", charge_customer,
timeout=TimeoutPolicy(run_timeout=10),
retry_policy=RetryPolicy(max_attempts=3),
)看上去没毛病。但文档里写得很清楚,第一次尝试花了 11 秒时会发生什么:
1. LangGraph 抛 NodeTimeoutError,并清掉这次尝试的所有写入;
2. NodeTimeoutError 默认可重试,重试策略从头重跑节点;
3. 如果渠道在第 10.2 秒其实已经提交了扣款,第二次尝试就又扣了一遍。
LangGraph 给你三种机制,它们按固定顺序组合:一次尝试抛异常(超时也只是一种异常)→ 重试策略决定是否再来 → 重试耗尽后才轮到 error_handler。
状态是对的,世界不是。 checkpoint 写在 super-step 边界而不是函数中间,失败尝试的写入会被丢弃——这个保证只覆盖图。容错文档说得很直白:重试给节点执行的是 at-least-once 语义,而支付、邮件、外部写操作都在 checkpoint 边界之外。所以超时做了它该做的事:清掉图状态。但它清不掉一笔扣款。
重试还会放大最坏情况:超时时钟每次尝试都会重置,三次 10 秒 run_timeout 可能让节点占用约 30 秒再加退避(默认初始间隔 0.5 秒、因子 2、带抖动)。拿这个数对一下你自己的延迟预算。
解法不是更聪明的超时,而是让重复执行变得无害。文档给了具体规则:幂等键必须能从已经持久化的 state 推导出来。在节点里现生成一个 UUID 是错的——如果进程在节点返回前挂了,这个键从没进 checkpoint,重试就会铸一个新键。
async def charge_customer(state: State) -> dict:
key = f"charge:{state['order_id']}" # 跨重试、跨恢复都稳定
charge = await payments.create_charge(
customer_id=state["customer_id"], amount=state["amount"],
idempotency_key=key)
return {"charge_id": charge.id}
def route_charge_failure(state, error: NodeError) -> Command:
timed_out = isinstance(error.error, NodeTimeoutError)
return Command(
update={"charge_outcome": "unknown" if timed_out else "failed"},
goto="reconcile_payment")
async def reconcile_payment(state) -> dict:
# 本地没有回执 = "未知",不是"没发生"
status = await payments.lookup(f"charge:{state['order_id']}")
return {"charge_outcome": status}两个细节:键来自本来就在 state 里的 order_id;error handler 不瞎猜,而是路由到一个专门问渠道"到底发生了什么"的节点。这正合文档的忠告——把缺失的本地状态当"未知",补偿前先查渠道。handler 通过类型注解拿到注入的 NodeError,所以靠类型就能区分超时和拒付,不用解析字符串。
TimeoutPolicy 有两个限制。run_timeout 是永不刷新的硬墙上时间;idle_timeout 在有进展时重置,而默认 refresh_on="auto" 下,"进展"的范围长得惊人:state 写入、流式块、子任务调度、stream-writer 调用,以及节点及其后代发出的任何 LangChain 回调事件(包括 LLM token 和工具调用)。
对包着 Agent 循环的节点,这是对的默认值。但副作用是:一个空转的节点——比如反复重试一个抖动的工具,同时子链不停发回调——在 idle 时钟眼里可以永远"健康"。如果你想让"idle"表示"我的代码明确说还活着",就收窄它:
async def ingest(state, runtime: Runtime) -> dict:
async for batch in fetch_batches():
await process(batch)
runtime.heartbeat() # 唯一能重置时钟的东西
return {"status": "done"}
builder.add_node("ingest", ingest,
timeout=TimeoutPolicy(idle_timeout=30, refresh_on="heartbeat"))runtime.heartbeat() 在非 idle 计时尝试里是空操作,所以可以无条件留在代码里。用 Send 扇出时还能按 item 单独覆盖超时。
timeout= 的同步节点在编译期就会被拒,因为同步 Python 无法安全地在进程内取消。文档建议阻塞 I/O 用 asyncio.to_thread——但注意,取消等待的协程并不会停掉线程,阻塞调用在超时"触发"后可能还在跑。interrupt() 通过 GraphBubbleUp 抛出,跳过重试策略和 error handler。人在回路的暂停不会触发你的补偿逻辑。set_node_defaults 不被子图继承。顶层设的超时保护不了嵌套图,每个图得各设各的。大家期待"超时"带来的,是一个卡住的 Agent 被解开。1.2 实际交付的,是一种更诚实的失败模型:图在 super-step 层面是事务性的,世界不是,中间的缝隙是你的问题。
我以前把节点超时归到可靠性特性里,现在把它看成一个开关——它把慢失败变成重试,而重试只有在里面的工作可安全重复时才可靠。给一个有副作用的节点加上 timeout,你就已经做了一个关于"重复"的决定,不管你有没有写下来。所以审视每个带 timeout= 的节点,唯一的问题是:它跑两遍有没有事?如果答案是"我得查查",那这个超时还没准备好上线。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。