LongGuard：为LangGraph装上熔断器，终结Agent失控循环

如果你在生产环境中运行AI Agent，很可能亲眼见过它们「实时烧钱」的场景：一个模糊的工具返回（比如「Access Denied」或「Item not found」）就足以让Agent陷入认知死循环，反复调用同一个工具二十几次，直到LangGraph抛出GraphRecursionError崩溃为止。等到它真正挂掉时，你已经烧掉了5万token、丢失了对话状态，还向用户返回了一个未处理的异常。

针对这一痛点，EnDevSols团队开源了他们内部使用的中间件——LongGuard，一个专为LangGraph设计的「熔断器」（Circuit Breaker）。它的目标很明确：动态捕获并从这些失控循环中恢复，而不是简单地让程序崩溃。

LongGuard项目介绍

为什么内置的recursion_limit不够用

LangGraph本身提供了recursion_limit来防止无限循环，但这只是一个「粗暴的撞车护栏」（blunt crash barrier）。它能阻止程序永远跑下去，却做不到以下几件事：

无法区分Agent是在做有意义的多步推理，还是在原地打转；
无法在崩溃之前介入并尝试纠正；
崩溃后不保存状态，直接把异常甩给用户；
无法控制成本——等到触发limit时，钱早就花出去了。

换句话说，recursion_limit只是最后一道死亡线，而生产环境真正需要的是一套能提前感知、主动干预的机制。这正是LongGuard试图填补的空白。

四种失控模式的实时检测

LongGuard的核心是嵌入到你的StateGraph中，在Agent的每一步都以亚毫秒级速度评估四种失败模式：

1. 相同工具调用（Identical tool calls）

通过对工具参数进行快速的SHA-256哈希，在滑动窗口内捕获参数完全一致的重复调用。这种确定性哈希方式万无一失，且几乎没有延迟开销。

2. 语义震荡（Semantic oscillation）

更隐蔽的情况是，LLM换了措辞但本质上还卡在同一个思维循环里。LongGuard通过分析embedding的方差来识别这种「换汤不换药」的死循环。

3. 死胡同漂移（Dead-end drift）

如果Agent连续走了5步以上却没有发现任何新的观察结果（用Jaccard相似度衡量），说明它可能已经陷入了无效探索，熔断器会被触发。

4. Token速率（Token velocity）

追踪每一步滚动的token消耗量，用来捕获指数级膨胀的「独白」——那种越写越长、越陷越深的自我对话。

这四种模式覆盖了从最明显的重复调用到最隐蔽的语义卡顿，形成了一张相对完整的Agent失控检测网。

反思与转向：不是简单地杀掉进程

LongGuard最有意思的设计在于它的恢复机制。它没有在检测到循环时立刻终止运行，而是采用了标准的熔断器状态机：CLOSED → REFLECTING → HALF_OPEN → OPEN。

当检测到循环时，它会向Agent注入一个针对性的系统提示，例如：

"Stop calling search. You've attempted this 3 times with zero new information. Change your strategy."（停止调用搜索，你已经尝试了3次且没有任何新信息，请改变策略。）

这一「Reflect & Pivot」（反思与转向）的思路很关键：

如果Agent据此调整了策略（pivot），熔断器就会重置，让流程继续；
如果Agent依然固执地重复，熔断器会干净地终止运行，保存状态，并输出一份结构化的审计报告。

这种「先劝、再断」的两段式设计，比一刀切的崩溃要优雅得多，也更贴合真实生产场景的容错需求。

硬性预算上限：告别账单惊吓

除了循环检测，LongGuard还内置了一个覆盖40多个模型的定价引擎，允许你为每次运行设置硬性的美元预算上限：

GuardConfig(model="gpt-4o", max_cost_usd=0.50)

一旦某次运行的成本达到上限，熔断器就会跳闸。对于成本敏感的生产部署来说，这是一个非常实用的安全阀，彻底避免因Agent卡住而产生的意外账单。

集成方式也极为简洁，只需一行包装即可：

from langgraph.graph import StateGraph
from longguard.integrations.langgraph import add_guard_to_graph
from longguard import GuardConfig

workflow = StateGraph(AgentState)
# ... 你的标准节点和边 ...

# 一行代码包装推理节点：
workflow = add_guard_to_graph(
    workflow,
    GuardConfig(model="gpt-4o", max_cost_usd=0.50)
)
app = workflow.compile()

权衡与局限：语义检测可能过度敏感

值得一提的是，作者坦诚地指出了工具的权衡取舍：

确定性哈希（相同工具调用检测）：万无一失，零延迟，可以放心使用；
语义震荡检测器：这是需要注意的部分。如果你的Agent正在执行一个真正复杂的多步推理路径，但在评估器看来「像是重复」，语义检测器可能会过于激进地误判。此时需要针对具体场景调整默认阈值。

这意味着LongGuard并非开箱即用的万能方案，对于推理链本身就长而复杂的Agent，使用者需要投入一定的调优成本。

工程实践上的加分项

从工程角度看，LongGuard在依赖管理和代码质量上做得比较克制：

MIT许可证：商用友好，集成无法律顾虑；
完全类型标注（fully typed）：对IDE和大型代码库友好；
不强制引入重型ML依赖：不会因为一个熔断器就往你的技术栈里塞一堆机器学习包。

这些细节反映出团队对生产环境实际约束的理解——生产级工具的价值不仅在于功能本身，还在于它是否「轻量、可控、不添乱」。

小结

LongGuard解决的是一个非常具体但普遍存在的Agent工程痛点：失控循环导致的token浪费与账单失控。它的防护思路可以概括为三个层次：

多维度检测——从哈希级的精确匹配到embedding级的语义分析，覆盖四种常见失控模式；
主动恢复——通过注入提示引导Agent「反思与转向」，而非直接崩溃；
硬性成本兜底——用预算上限彻底堵住账单漏洞。

对于任何在生产环境中运行LangGraph Agent的团队来说，这是一个值得关注的开源方案。当然，语义检测的阈值调优以及尚未覆盖到的边缘场景，仍需要在实际使用中逐步验证。项目欢迎社区提交PR和Issue，共同完善这套熔断机制。