M4Medium★ Agent 生产必备 · 止损门控Part M · LLM 评测与 Agent/RAG 算子
Agent 工具循环熔断与幂等调用护栏
针对 ReAct/Tool Agent 常见死循环重复调参、Token 失控与超时重放重复扣款故障,实现步数/循环熔断与幂等键缓存。
⏱️ 时间复杂度:
O(|ArgsJSON|) 哈希校验💾 空间复杂度:
O(MaxSteps)🎯 免登录实战自测闭环(先做再看答案)
按「机制回忆 → 关键行填空 → 边界反例 → 追问与错题记录」顺序自测,进度自动保存在本地。
Step 1 · 机制口述与数值稳定性自检
Step 2 · 核心代码关键行补全
import hashlib
import json
class AgentToolGuard:
"""Bounded cycle-detection, budget cap, and idempotency guard for tool-calling agents."""
def __init__(self, max_steps: int = 8, max_identical_calls: int = 2):
self.max_steps =
self.max_identical_calls = max_identical_calls
self.steps = 0
self.call_counts = {}
self.idempotency_cache = {}
def invoke(self, tool_name: str, args: dict, idempotency_key: str, fn) -> dict:
if self.steps >= self.max_steps:
return {"status": "HALTED", "reason": "max_steps_exceeded"}
self.steps += 1
sig = f"{tool_name}:{hashlib.sha256(json.dumps(args, sort_keys=True).encode()).hexdigest()[:12]}"
self.call_counts[sig] = self.call_counts.get(sig, 0) + 1
if self.call_counts[sig] > self.max_identical_calls:
return {"status": "HALTED", "reason": "cycle_detected"}
if idempotency_key and idempotency_key in self.idempotency_cache:
return {"status": "CACHED_IDEMPOTENT", "result": self.idempotency_cache[idempotency_key]}
result =
if idempotency_key:
self.idempotency_cache[idempotency_key] = result
return {"status": "EXECUTED", "result": result}
Step 3 · 反例与边界断言核对
Step 4 · 面试追问盲答与错题记录
Q1: 当 Agent 触发
cycle_detected 或 max_steps_exceeded 熔断时,后端应如何收尾才能兼顾用户体验?💡
实战一句话记忆口诀
步数设天花板,参数排序哈希抓死循环,写操作必须挂幂等键防重放
📐 核心数学公式与机理推导
### 生产级有界 Agent 三道确定性防线
开放式 ReAct 循环在工具报错或结果不理想时极易不断用完全相同参数重试(Infinite Retry Loop),导致账单暴涨或反复写库:
1. 步数与预算上限:
2. 参数哈希死循环检测:对
3. 外部写操作幂等键(Idempotency Key):对发邮件、扣款、创建工单等非只读操作携带请求唯一
开放式 ReAct 循环在工具报错或结果不理想时极易不断用完全相同参数重试(Infinite Retry Loop),导致账单暴涨或反复写库:
1. 步数与预算上限:
max_steps 与 Token 上限强制熔断,兜底进入总结降级;2. 参数哈希死循环检测:对
(tool_name, canonical_args) 求规范化哈希签名,若连续重复超过阈值立即拒绝并提示 LLM 换策略或终止;3. 外部写操作幂等键(Idempotency Key):对发邮件、扣款、创建工单等非只读操作携带请求唯一
idempotency_key,重试命中缓存直接回放结果,绝不二次生效。🔄 张量维度与形状流转说明
tool_name, args, idempotency_key -> check max_steps -> check args hash repeat -> check idempotency cache -> execute & store
🛡️ 数值稳定性自检与边界要点
- 序列化
args做哈希前必须加sort_keys=True,防止字典键顺序不同绕过重复调用检测 - 区分只读工具与写状态工具:高危写操作应结合人工二次审批断点(HITL Interrupt)与幂等键使用
💻 完整参考代码实现
import hashlib
import json
class AgentToolGuard:
"""Bounded cycle-detection, budget cap, and idempotency guard for tool-calling agents."""
def __init__(self, max_steps: int = 8, max_identical_calls: int = 2):
self.max_steps = max_steps
self.max_identical_calls = max_identical_calls
self.steps = 0
self.call_counts = {}
self.idempotency_cache = {}
def invoke(self, tool_name: str, args: dict, idempotency_key: str, fn) -> dict:
if self.steps >= self.max_steps:
return {"status": "HALTED", "reason": "max_steps_exceeded"}
self.steps += 1
sig = f"{tool_name}:{hashlib.sha256(json.dumps(args, sort_keys=True).encode()).hexdigest()[:12]}"
self.call_counts[sig] = self.call_counts.get(sig, 0) + 1
if self.call_counts[sig] > self.max_identical_calls:
return {"status": "HALTED", "reason": "cycle_detected"}
if idempotency_key and idempotency_key in self.idempotency_cache:
return {"status": "CACHED_IDEMPOTENT", "result": self.idempotency_cache[idempotency_key]}
result = fn(**args)
if idempotency_key:
self.idempotency_cache[idempotency_key] = result
return {"status": "EXECUTED", "result": result}
🧪 本地测试与正确性断言
可直接复制到本地 Python / Jupyter 验证:
exec_count = 0
def charge_user(amount):
global exec_count
exec_count += 1
return f"charged_{amount}"
guard = AgentToolGuard(max_steps=6, max_identical_calls=2)
r1 = guard.invoke("charge", {"amount": 50}, "tx_100", charge_user)
r2 = guard.invoke("charge", {"amount": 50}, "tx_100", charge_user) # network retry replay!
r3 = guard.invoke("charge", {"amount": 50}, "tx_100", charge_user) # 3rd identical loop triggers cycle break
assert exec_count == 1, "Idempotency key must execute mutating action only once"
assert r1["status"] == "EXECUTED" and r2["status"] == "CACHED_IDEMPOTENT"
assert r3["status"] == "HALTED" and r3["reason"] == "cycle_detected"
print("✓ Agent loop-breaker & idempotency guard assertion passed")🎯 核心工程追问与标准应答
Q1:当 Agent 触发
cycle_detected 或 max_steps_exceeded 熔断时,后端应如何收尾才能兼顾用户体验?不要直接返回 500 报错;应切入确定性 Fallback 收尾节点,把当前已成功收集到的只读证据摘要呈现给用户,明确指出哪一步工具卡住并给出可点击的人工继续/改写问题入口,同时记录 Trace 供离线评测复盘。
⚡
想检验本题的肌肉记忆?进入 3 阶闪卡主动回忆盲测
隐藏答案遮罩,自测:审题锚点 ➔ 数理公式机理 ➔ 工业标杆代码与连环追问。3 分钟攻破认知盲区!