LongGuard Skill 技能

LongGuard 是什么

LongGuard 是一款智能正转断路器（Circuit Breaker）中间件，专为 LangGraph、LangChain 或自定义的 Agent 执行循程设计。它能够实时监控 Agent 的思维链，发现循环后早期注入“Reflect & Pivot”指导，并在恢复失败后保证系统安全终止。

核心能力（四路循环检测器）

LongGuard 在每步执行时并行运行四个轻量级检测器：

检测器 1：工具重复（Tool Repeat） 检测工具被以完全相同的参数调用。实际案例：Agent 通过 web_search("apple stock 2026") 调用四次，参数没有任何变化。

检测器 2：语义振荡（Semantic Oscillation） 检测思维中在同概念间往复切换。实际案例：Agent 掩理“我应该搜索 A”，然后“不，B”，再然“关于 A”，再转回 B。

检测器 3：死尾输偏离（Dead-End Drift） 检测连续 5+步骤无新信息或观察结果为空。

检测器 4：Token 预算爆炸 监控单次执行消耗的 Token 数，达到阈值后强制终止，防止预算失控。

安装配置（三步应开）

第一步：安装

核心包（零重依负扩）：

pip install longguard

启用 LangGraph 集成：

pip install longguard[langgraph]

启用 LangChain 集成：

pip install longguard[langchain]

第二步：将 LongGuard 绑定到 LangGraph 工作流

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

# 1. 定义标准 LangGraph 工作流
workflow = StateGraph(AgentState)
workflow.add_node("agent", agent_node)
workflow.add_node("tools", tool_node)
workflow.add_edge("agent", "tools")
workflow.add_conditional_edges("tools", should_continue)

# 2. 包装 LongGuard — 就这一步！
workflow = add_guard_to_graph(workflow, GuardConfig())
app = workflow.compile()

# 3. 执行后获取执行分析
guard = workflow.__longguard__
print(guard.get_report().summary())

第三步：自定义 Agent 循环使用

from longguard import CircuitBreaker, GuardConfig, AgentStep

breaker = CircuitBreaker(GuardConfig(
    tool_repeat_threshold=3,    # 3次相同工具调用 ⇒ 触发
    max_tokens_per_run=50_000,  # 确保单次执行不超 5万 Token
))

for step in run_agent():
    decision = breaker.check(AgentStep(
        step_number=step.index,
        thought=step.thought,
        action=step.tool_name,
        action_input=step.arguments,
        observation=step.tool_output,
        tokens_used=step.tokens,
    ))

    if decision.action == "reflect":
        # 将恢复建议注入到 Agent 消息列表
        messages.append({"role": "user", "content": decision.inject_prompt})
    elif decision.action == "kill":
        print(f"安全停止: {decision.reason}")
        break

# 查看执行报告
print(breaker.report.summary())

使用步骤（四步完成一次完整流程）

步骤 1：安装 LongGuard

pip install longguard
pip install longguard[langgraph]  # 如果使用 LangGraph

步骤 2：定义您的 Agent 工作流

from langgraph.graph import StateGraph

workflow = StateGraph(AgentState)
workflow.add_node("agent", your_agent_node)
workflow.add_node("tools", your_tools_node)
workflow.add_edge("agent", "tools")
workflow.add_conditional_edges("tools", should_continue)

步骤 3：绑定 LongGuard 指控器

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

# 通过一行代码将完整工作流包装负责心
workflow = add_guard_to_graph(workflow, GuardConfig())
app = workflow.compile()

步骤 4：执行并获取执行报告

result = app.invoke({"messages": [("user", your_input)]})

# 访问 LongGuard 执行分析报告
guard = workflow.__longguard__
print(guard.get_report().summary())

适用场景（四种场景）

场景 1：长违書检索工作流 当 Agent 需要在大量文档中检索查询时，容易出现重复检索同一关键词的情况。LongGuard 能够在第 3次重复后提醒 Agent 换个思路，而非继续赛费 Token。

场景 2：工具键点检索 如果某个 API 调用固倦或网络请求正常无效，Agent 会尽联重试直到预算爆炸。LongGuard 的工具重复检测器能够在第 3次后就提醒替换方案或终止。

场景 3：多步骤代码生成 试图生成复杂代码时，Agent 易出现死尾小小改动的情况，没有新进展。LongGuard 通过 Reflect & Pivot 指导它重新评估问题定义，避免空转圈。

场景 4：代码审核工作流 当审核代码时，Agent 需要检查多个文件，如果文件名称误解或内容相似，易出现死循环。LongGuard 能够在这种情况发生前就干消。

适用人群

• LangGraph/LangChain 开发者：需要部署复杂 Agent 应用的工程团队
• Agent 运维工程师：负责监控和优化 Agent 执行效率的运维人员
• 云原生成工程：需要控制 Token 消耗、防止预算超支的运维团队
• 自定义 Agent 框架开发者：采用了自定义循环结构，需要实时监控执行状态

工作原理

LongGuard 采用状态机器设计：

1. 正常执行（CLOSED 状态）：无循环检测时，Agent 正常执行。
2. 反思指引（REFLECTING 状态）：检测到循环后，注入 Reflect & Pivot 指导，让 Agent 重新评估问题定义。
3. 恢复成功（返回 CLOSED）：如果 Agent 根据指导改道，系统返回正常执行状态。
4. 恢复失败（OPEN 状态）：如果继续无法恢复，系统安全终止执行，并输出原团和状态报告。

与传统方式对比

官方链接

• PyPI：https://pypi.org/project/longguard/
• GitHub：https://github.com/ENDEVSOLS/LongGuard
• 文档：https://endevsols.github.io/LongGuard/