LangGraph从0.6.x升到1.0.6后，text-to-SQL agent开始把同一个坏查询重试20次直到recursion_limit触发——版本升级引入的“重试风暴”在状态图里到底该靠bounded-loop还是靠换路来兜底？

目录

一、导语：一个“看起来像死循环”的升级事故

把 LangGraph 从 0.6.x 升到 1.0.6，本应是一次常规的依赖更新。但不少 text-to-SQL agent 的维护者在升级后发现，原本偶发的“SQL 执行失败—重写—再执行”流程，变成了对同一条坏查询的机械重放：生成节点输出的 SQL 一字不差，校验节点给出同样的错误，路由边再次把控制流送回生成节点，直到 recursion_limit 被触发、整张图以异常终止。从外部看，这像是一个死循环；从图内部看，每一步都是“合法”的状态转移。

这类现象值得单独讨论，原因有三。其一，它暴露的不是某个 API 的兼容性问题，而是状态图这种编程范式里“重试”语义的脆弱性：重试次数、重试对象与重试前提分散在节点、边和外部执行器三处，任何一处语义漂移都会让“有限重试”退化为“无限重放”。其二，text-to-SQL 是当前落地最广的 agent 形态之一，其失败模式具有代表性——错误往往来自数据库方言、schema 链接和语义歧义，而非单纯的网络抖动，因此“原样重试”在信息论意义上几乎不可能带来新结果。其三，社区中关于“该用 bounded-loop 还是该换路”的争论，实际上混淆了两个不同层次的问题：前者是控制流的可终止性保证，后者是搜索空间的切换策略，二者并非互斥选项。

本文的主线是“状态契约漂移”：升级本身没有制造 bug，它只是让原本被隐式约定掩盖的状态契约显性化，从而把潜在缺陷放大为可观测的故障。围绕这条主线，下文将依次回答：如何判定一次重试风暴、1.0.x 改变了哪些契约、bounded-loop 与换路各自解决什么、以及在真实工程中如何组合使用。

二、背景与问题定义：重试风暴的判定标准

2.1 什么是“重试风暴”

本文把重试风暴（retry storm）定义为：在一个带反馈边的 agent 状态图中，连续多次重试所依据的输入信息（此处指待执行的 SQL 文本及其附加上下文）在语义上等价，且重试次数超过预设的业务上限，最终由框架级保护（如 recursion_limit）而非业务逻辑终止流程的现象。这个定义包含三个可检验要素：输入等价性、次数越界、终止主体错位。

输入等价性是最容易被忽视的一条。很多团队在日志里看到“重试了 20 次”，就默认 agent 在“尝试不同方案”，但若把每次生成的 SQL 做规范化（去空白、统一大小写、展开别名）后计算哈希，会发现 20 次里有 18 次完全相同。次数越界指超过了业务侧声明的最大修复轮数，例如团队约定“最多重写 3 次”。终止主体错位则指流程不是被业务判断（如“放弃并返回澄清请求”）结束，而是被框架的递归保护强行打断——后者意味着状态图缺少显式的退出路径。

笔者认为，把“是否由框架保护终止”作为判定条件，比单纯看重试次数更有工程价值。框架保护是最后一道防线，它被触发本身就说明业务层的失败处理不完备；而次数越界可能只是阈值设得偏紧。

2.2 为什么 text-to-SQL 特别容易触发

text-to-SQL 的失败分布与通用对话 agent 不同。根据 Spider、BIRD 等基准的公开分析，执行错误（execution error）与结果错误（wrong result）是两类主要失败，前者包括列名不存在、类型不匹配、聚合函数误用、方言语法差异等。这类错误的共同点是：它们由“当前 SQL 与数据库 schema 的交互”决定，而不是由随机性决定。换言之，在温度参数为 0 或低温度采样下，把同样的 prompt、同样的 schema 上下文、同样的错误信息再次喂给模型，输出趋同是高概率事件。

这就引出一个关键推论：对 text-to-SQL 而言，“重试”只有在改变了输入信息时才有意义。改变输入的方式包括注入更精确的错误解释、裁剪或重排 schema 上下文、切换到不同的生成策略（例如从直接生成改为分步生成）、或更换执行目标（例如换一个等价视图）。如果重试没有改变这些，它就不是搜索，而是重放。本文评述：许多 agent 框架把“重试”实现为“再次调用同一节点”，这在网络请求场景下合理，在语义生成场景下却是错误抽象。

2.3 一个可操作的判定指标

为了让讨论可复现，本文建议用三个指标刻画重试行为，均可在现有 tracing 数据上计算，无需改动业务代码：

上表区间为本文基于若干公开 agent 评测报告与工程经验的整合估计，属模拟性经验值，用于建立基线而非精确阈值。读者应在自己的数据集上重新标定。若 R 高而 G 低，说明重试在重放；若 T 显著大于 0，说明退出路径缺失。这两个信号同时出现，基本可以确认重试风暴。

三、机制剖析：0.6.x 到 1.0.6 到底变了什么

3.1 状态合并语义的显性化

LangGraph 的核心抽象是“带类型化状态的图”：节点读取状态、返回状态更新，框架按 reducer 合并。0.6.x 时代，不少实现依赖默认的覆盖式合并，并在节点里直接修改传入的字典；1.0.x 强化了状态 schema 的声明与校验，对未声明字段、类型不匹配的更新更为严格。这一变化本身是进步，但它让“重试计数器放在哪里”这个问题暴露出来。

典型故障模式是：重试计数被放在一个未被 reducer 正确累加的字段上，或者被放在节点内部的局部变量里。升级后，状态更新被更严格地隔离，计数不再跨轮次保留，于是“最多 3 次”的判断永远为假，循环失去上界。本文评述：这不是框架的回归，而是把“隐式共享可变状态”这一反模式从“碰巧能跑”变成“明确不能跑”。升级只是触发器，缺陷早已存在。

3.2 路由与中断恢复的行为差异

1.0.x 在中断（interrupt）、检查点（checkpointer）与恢复语义上做了较多调整，目的是让“人在回路”和“失败续跑”更可靠。副作用是：当一次执行因异常被中断并恢复时，某些条件边的判定所依赖的字段可能来自检查点快照，而非最新一轮的节点输出。如果错误分类字段（如 last_error_type）没有被正确写入检查点，恢复后的路由会读到旧值，从而重复选择“重试”分支。

这类问题在日志上的表现极具迷惑性：每一轮的错误信息看起来都对，路由判断看起来也“符合条件”，但判断所依据的状态与工程师以为的状态不是同一个版本。诊断时应优先比对检查点快照与节点实际返回值，而不是只读应用日志。

3.3 执行器错误分类的粒度问题

text-to-SQL 的执行器通常返回结构化的错误对象。升级过程中，若数据库驱动或连接池库同步升级，错误码与异常类型的映射可能变化。原本被归为“可重试”的语法错误，可能因为异常类层级变化而被归入“未知错误”，进而落入默认的“重试”分支。反过来，原本应重试的瞬时错误也可能被误判为永久错误。

这里的关键认识是：错误分类是重试策略的前提，而错误分类本身是脆弱的、依赖外部库版本的。把“是否重试”完全交给异常类型判断，等于把控制流的可终止性外包给了第三方库的版本兼容性。笔者认为，稳健的做法是在执行器之上加一层显式的、版本无关的错误归一化层，把底层异常映射到有限的、业务定义的错误类别上，并为每个类别规定唯一的重试语义。

3.4 一条因果链的还原

把上述三点串起来，可以得到一条可检验的因果链：状态 schema 收紧 → 重试计数未正确累加 → 上界判断失效；检查点语义变化 → 错误分类字段读到旧值 → 路由重复选择重试分支；执行器异常映射变化 → 错误类别漂移 → 默认分支兜底为重试。三者叠加，就形成了“同一坏查询被重放 20 次”的可观测现象。单独修复任何一环都可能降低频率，但只有同时处理状态契约、路由契约与错误契约，才能消除该类故障。

升级前（隐式契约）                     升级后（显式契约暴露缺陷）
节点内局部计数 ──┐                    状态 schema 校验 ──→ 计数丢失
默认覆盖合并   ──┼──→ 碰巧能终止      检查点快照     ──→ 路由读旧值
异常类型直判   ──┘                    异常映射漂移   ──→ 默认走重试
                                        ↓
                                  同一 SQL 重放 → recursion_limit

四、bounded-loop：把“重试”变成可证明有界的结构

4.1 定义与最小实现

bounded-loop 指在状态图中为重试路径显式引入一个受状态管理的计数器，并在条件边上以该计数器为唯一判据之一决定是否继续循环。其要点不是“加个 if”，而是让计数成为图状态的一部分、由 reducer 保证单调递增、并在检查点中持久化。这样，无论中断恢复还是并发分支，上界都可证明。

from typing import TypedDict, Annotated
import operator

class SQLAgentState(TypedDict):
    question: str
    schema_ctx: str
    sql: str
    error_type: str          # 归一化后的错误类别
    error_detail: str
    retry_count: Annotated[int, operator.add]   # 单调累加
    tried_sql_hashes: Annotated[list[str], operator.add]

MAX_RETRY = 3

def route_after_execute(state: SQLAgentState) -> str:
    if state["error_type"] == "ok":
        return "finalize"
    if state["retry_count"] >= MAX_RETRY:
        return "give_up"          # 业务退出路径，先于框架保护
    if state["error_type"] in ("syntax", "schema_mismatch"):
        return "rewrite"
    return "switch_route"         # 非可重写错误，换路

这段代码的关键在于三点：计数器使用可累加的 reducer；退出判断先于重试判断；错误类别驱动不同分支而非统一重试。本文评述：很多“bounded-loop 无效”的报告，根源是计数器没有用 reducer，导致每轮被覆盖为 1，上界永远达不到。升级到 1.0.x 后这类问题更容易暴露，因为状态更新被更严格地校验。

4.2 为什么它只解决“可终止”，不解决“有效”

bounded-loop 的价值是保证流程一定会结束，且结束方式由业务定义（give_up 分支可以返回澄清请求、返回部分结果或转人工）。但它不保证重试是有效的：如果每轮输入不变，3 次有界重试仍然是 3 次无效重放，只是从“20 次”降到“3 次”。因此 bounded-loop 是必要条件而非充分条件。把两者混为一谈，是当前讨论中最常见的概念错误。

要提升有效性，必须在循环体内引入“信息注入”步骤：把执行器的结构化错误、失败 SQL 片段、相关 schema 的精确片段组合成新的上下文，再交给重写节点。可验证的判据是信息增益率 G：若 G 长期低于阈值，说明循环体没有产生新信息，此时应缩短上界或直接换路。

4.3 上界怎么定：一个基于成本的计算框架

上界不应拍脑袋。可以用期望成本模型：设单次重写的 token 成本为 C_r，单次执行成本为 C_e，第 k 次重试相对首次的成功概率增量为 p_k，放弃后转人工的成本为 C_h。则继续重试的期望收益需满足 Σp_k·V > (C_r+C_e)，其中 V 为成功解决带来的价值。实践中 p_k 随 k 快速衰减，通常在 k=2 到 3 后趋近于零，这与公开的 agent 修复轮次统计趋势一致（具体数值随任务与模型而异，需自行标定）。

笔者认为，把上界写成配置项而非硬编码，并配套记录每轮的实际增益，是让 bounded-loop 从“防呆”升级为“可调优”的关键。团队可以按错误类别设置不同上界：语法错误给 2 次，schema 链接错误给 3 次，权限类错误给 0 次直接换路。

五、换路：从“修同一个查询”转向“换一种解法”

5.1 换路的三种形态

换路（route switching）指在检测到当前解法路径不可行时，切换到另一条具有不同假设的生成或执行路径。在 text-to-SQL 场景中，至少有三种可操作的换路形态：其一是生成策略切换，例如从“一次性生成完整 SQL”切换到“先选表再选列再拼装”的分步生成；其二是 schema 上下文切换，例如从全量 schema 切换到基于检索的 Top-k 相关表列；其三是执行目标切换，例如从直接查询基表切换到查询预建视图或物化结果。

三种形态的共同点是：它们改变了问题的求解空间，而不是在同一个空间里重复采样。这正是换路与重试的本质区别。本文评述：把换路实现为“换一个 prompt 再试一次”，往往退化为重试的变体；真正的换路应当伴随可观测的假设变化，例如候选表集合变化、生成中间产物结构变化。

5.2 触发条件：什么时候该换路而不是重试

一个实用的判据是错误类别的“可修复性”。若错误信息明确指向局部可修正项（如某列名拼写、某函数参数个数），重试加精确错误注入是高效的；若错误指向结构性歧义（如问题涉及的表关系在 schema 中不唯一、聚合口径不明），继续重写同一路径的收益极低，应换路。可以用一个简单的决策表落地：

5.3 换路的成本与风险

换路不是免费的。它增加了图的分支数、状态字段与测试矩阵，也引入了“路径选择错误”这一新失败模式：agent 可能在两条路径间来回切换而不收敛。因此换路必须与有界性结合——每条路径各自有上界，且全局有一个总轮次上界。否则只是把单点重试风暴扩散为多点重试风暴。

另一个风险是可解释性下降。当最终结果来自第三条路径时，用户与运维都需要知道“为什么放弃了前两条”。因此换路节点应写入结构化的路径轨迹（tried_routes），并在最终输出中保留摘要。这既是可观测性要求，也是事后评估换路策略是否有效的数据基础。

六、对比与局限：两种兜底策略的边界条件

把 bounded-loop 与换路放在同一张表里对比，可以更清楚地看到它们解决的是不同层次的问题。前者属于控制流安全，后者属于搜索策略。工程上正确的问法不是“二选一”，而是“在哪个层次上先保证安全，再优化效果”。

局限方面，bounded-loop 无法提升单路径的成功率，且如果错误分类本身不可靠，上界判断会建立在错误前提上。换路则依赖“存在另一条可行路径”这一假设，在 schema 本身缺失必要信息时，换路同样无解，此时正确动作是向用户澄清而非继续尝试。本文评述：两类策略的共同盲区是“问题本身不可解”，因此一个完整的兜底设计必须包含“识别不可解并优雅退出”的能力，这恰恰是 recursion_limit 无法提供的。

从可靠性工程的角度看，这与分布式系统中的重试语义有相通之处：重试必须区分幂等与非幂等、瞬时与永久错误，并配合退避与熔断。agent 的“重试”虽然不涉及网络，但其语义复杂度更高，因为它重试的是一个生成过程。把经典的重试模式（如指数退避、熔断、舱壁）迁移到 agent 图时，需要重新定义“失败”与“同一请求”，这正是状态契约要解决的问题。

七、工程落地：诊断步骤、代码改造与评估方案

7.1 五步诊断法

第一步，抽取一次失败会话的完整 tracing，按轮次列出节点输入输出，重点看 SQL 文本与错误类别。第二步，对每轮 SQL 做规范化哈希，计算重试重复率 R。第三步，检查重试计数所在字段是否使用可累加 reducer，以及检查点快照中该字段的值是否单调。第四步，检查条件边读取的错误类别字段是否与执行器最新返回一致。第五步，确认是否存在先于 recursion_limit 的业务退出分支。五步中任一步不通过，都对应一个明确的修复点。

诊断时建议同时打开框架的调试与可视化能力，把图结构、状态快照与边判定结果放在同一时间轴上比对。LangGraph 官方文档提供了持久化与可视化相关的教程，可作为排查起点：LangGraph 官方文档。关于 agent 评估的一般方法，可参考 AgentBench 论文 与 检索增强 agent 实践教程。

7.2 状态图改造清单

改造应遵循“先安全、后有效”的顺序。先补齐状态契约：为所有跨轮次字段声明类型与 reducer，为错误类别建立归一化枚举，为每条路径设置独立上界与全局上界。再优化有效性：在重写节点前插入错误解释与 schema 片段注入，在换路节点写入路径轨迹。最后补齐退出路径：为不可解问题设计澄清请求或部分结果返回，确保 recursion_limit 只作为最后防线。

# 错误归一化层（版本无关）
ERROR_MAP = {
    "syntax": {"retryable": True,  "route": "rewrite"},
    "schema_mismatch": {"retryable": True,  "route": "schema_retrieval"},
    "ambiguous": {"retryable": False, "route": "clarify"},
    "permission": {"retryable": False, "route": "give_up"},
    "unknown": {"retryable": False, "route": "give_up"},
}

def normalize_error(exc) -> str:
    msg = str(exc).lower()
    if "syntax" in msg or "near" in msg:
        return "syntax"
    if "does not exist" in msg or "unknown column" in msg:
        return "schema_mismatch"
    if "permission" in msg or "denied" in msg:
        return "permission"
    return "unknown"

这段归一化层的意义在于把“是否重试”的决策从第三方异常类型中解耦出来。本文评述：归一化规则本身也需要测试与版本管理，建议把它作为独立模块维护，并用历史失败样本做回归，避免规则随业务漂移而失效。

7.3 评估方案与数据预处理

评估应同时覆盖“是否终止”与“是否有效”。建议构造一个包含三类样本的回归集：可局部修复的语法错误、需要换路的 schema 歧义、以及不可解问题。对每类样本记录重试重复率、信息增益率、框架终止占比与最终解决率。数据预处理方面，若使用公开 text-to-SQL 数据集（如 Spider、BIRD），需说明：去除执行超时样本、对 schema 做统一大小写与别名展开、对问题做去重、按数据库划分训练/评估以避免泄漏。这些步骤直接影响指标可比性，必须在报告中写明。

需要强调的是，本文给出的指标区间与成本模型均为基于公开资料与工程经验的整合估计，属模拟性参考，不构成对任何具体系统的性能断言。读者应以自身 tracing 数据为准进行标定。关于 text-to-SQL 评测的细节，可参考 Spider 数据集主页 与 BIRD 基准。

八、结论与展望：把“重试”当作一等公民来设计

回到最初的问题：重试风暴该靠 bounded-loop 还是靠换路？本文的结论是，二者不在同一层次上竞争。bounded-loop 是控制流的安全带，负责让流程一定以业务可接受的方式结束；换路是搜索策略的方向盘，负责在一条路径不可行时改变假设。缺少前者，任何策略都可能被框架保护粗暴打断；缺少后者，有界重试仍可能是无效重放。正确的工程顺序是先补齐状态契约与退出路径，再按错误类别分流重试与换路，最后用可观测指标持续校准。

从更一般的角度看，这次升级事故提示我们：agent 框架的演进正在把过去依赖隐式约定的行为显性化。这对工程实践是好事，但要求团队把“重试”从随手写的 while 循环，提升为有状态、有分类、有上界、有退出的一等公民。展望未来，随着 agent 评测体系（如轨迹级评估、失败模式分类）的成熟，重试策略有望像分布式系统的重试库一样，形成可复用、可配置、可验证的标准组件。本文评述：在那之前，最务实的一步，是先把重试计数器放进状态、把退出分支画进图里。

主要参考文献