【Agent Harness 架构手册 #01】LangGraph 动态工具配额守卫实战：根治无限探索与 return_direct 报错不自愈

关注

原创 2026-10-18 11:40:10 303 阅读 AI 写同款· GEO 优化 ›

Linux Swap 子系统：架构、内存管理与虚拟化 Swap Linux Swap机制通过将不活跃内存页移至磁盘或压缩内存，扩展系统有效内存容量，缓解内存压力。传统架构中，逻辑Swap槽与物理存储绑定，导致资源浪费，尤其在使用Zswap等压缩技术时。为此，Vswap与Xswap提出虚拟化方案：前者以XArray实现灵活映射，支持多后端迁移；后者采用稀疏映射，简化管理但容量固定。二者在架构设计、资源记账与动态扩展上各有权衡，反映了内核开发中对性能、可维护性与灵活性的深层考量。阅读详情

玄同 765

AI Engineer

中国传媒大学 ｜ 数字媒体技术（游戏设计技术方向）

  ▍深耕领域 AI Agent 架构设计 Agent Harness 工程 Context Engineering 多智能体协同 & RAG
  ▍技术底座 Python TypeScript · LangChain MCP & Skills · FastAPI Milvus Docker
  ▍工程能力 专注 Agent 运行时架构、长上下文与 Prompt Cache 优化、LLM 全链路评测与工程化落地

「让 AI 交互更智能，让技术落地更高效」 ｜ 欢迎技术探讨 / 项目合作，关注解锁大模型与智能交互的无限可能！

【Agent Harness 架构手册 #01】LangGraph 动态工具配额守卫（Dynamic Tool Quota Guard）实战：根治模型“无限瞎探索”与 return_direct 报错不自愈

📚 《Agent Harness 架构手册：构建高可靠 AI 智能体运行时》五篇连载导航

#01 配额与自愈：LangGraph 动态工具配额守卫实战：根治无限探索与 return_direct 报错不自愈
#02 可观测交互：AI Agent 实时动态流（Action Feed）与阶段性结论合成引擎实战
#03 上下文投影：多轮对话上下文引擎实战：L1~L4 四级预算投影与无损回放
#04 零信任安全：企业级 Agent 零信任权限审计与 AST 行级安全注入：防止长对话中途撤权泄密
#05 自进化与重连：AI Agent 自进化经验蒸馏飞轮与 SSE 游标断点重连实战

欢迎来到全新连载专栏！在之前的文章里，我们聊过 AI Agent 上下文工程与 Prompt Cache 优化以及工具执行引擎安全护栏。从本篇开始，我们将通过 5 篇深度实战，系统拆解如何从零打造一套工业级 Agent Harness 运行时底座。

凡是用 LangGraph 或 ReAct 架构开发过在线业务 Agent（比如智能数据分析助手、自动化配置构建器）的同学，上线后几乎都会撞上这四个让人头皮发麻的失控现场：

一超步就直接抛 GraphRecursionError 崩溃：为了防死循环，你在编译图时设了 recursion_limit=25。结果模型查了 12 个表还没收敛，第 13 步直接触发硬异常中断，前功尽弃，前端用户只看到一行冰冷的 500 Internal Server Error。
“沙箱试探上瘾”与“校验通过后还在瞎逛”：模型明明已经调用 verify_sql_syntax 校验通过了 SQL 语句，下一步本该调用 submit_schema_proposal 提交成果，结果它突然又回头去调 fetch_catalog_tables 或连着跑 10 次 dryrun_sql 试探，白白烧光整轮预算。
return_direct=True 结束型工具报错直接裸奔：像 submit_schema_proposal、publish_report 这类结束型工具，通常会设置 return_direct=True（执行完立即结束本轮对话）。可万一模型传错了一个参数导致工具返回 "Error: missing required field"，图状态机竟然直接把这个报错当成最终答案甩给用户，根本不给模型改正重试的机会！
单轮疯狂读取文档撑爆 Token：模型一口气连续调用 8 次 read_doc，把十几万字的知识库原文塞进同一轮上下文，导致后续推理延迟飙升到 40 秒以上。

本文将手把手带你用 LangGraph AgentMiddleware + ContextVar 协程隔离状态机，打造一套生产级 「动态工具配额守卫中间件（Tool Quota Guard Middleware）」，一次性解决多维配额管控、验证后状态锁、结束型工具报错自愈（Command(goto="model")）与每 $N$ 步探索进度自动合成。

文章目录

- 【Agent Harness 架构手册 #01】LangGraph 动态工具配额守卫（Dynamic Tool Quota Guard）实战：根治模型“无限瞎探索”与 return_direct 报错不自愈

一、为什么单靠 `recursion_limit` 管不住生产级 Agent？（原理拆解篇）

1.1 从“给实习生一张无限额信用卡，超时直接开除”说起

为什么 LangGraph 自带的 recursion_limit 在生产环境里远远不够用？

我们可以把一个正在执行复杂任务的 Agent 比作 去商场采购的实习生，把工具调用（Tool Call）比作 刷卡消费：

粗暴的 recursion_limit（超时直接开除）：
你给实习生规定：“你最多只能进出商店 20 次，第 21 次保安直接把你架走，手里买好的东西全部作废！”——这就是 GraphRecursionError。它没有任何“温和提醒收敛”的过程，也不会区分实习生到底是在瞎逛（调用探索工具 search_docs），还是已经在收银台结账了（调用结束型交付工具 submit_proposal）。
生产级的动态工具配额守卫（Dynamic Tool Quota Guard）：
真正聪明的财务制度是怎么设计的？
1. 区分“逛街预算”与“结账通道”：逛街试探（非结束型工具 non_terminal）最多 12 次；一旦满 12 次，拦截继续逛街的请求，并返回一句明确的引导语：“探索预算已用尽，请立即基于已有信息回答或调用 request_user_input 向用户提问”，但收银台结账工具（terminals）永远畅通无阻！
2. 专项子额度管控（Sub-Budgets）：不仅管总次数，还管单项行为——比如“同一家店连续试穿（consecutive_probe_hits）不得超过 6 次”、“复印参考资料（doc_loaded_volume）单轮不得超过 24,000 字”。
3. 结账单填错允许当场重填（Terminal Error Retry）：实习生到收银台填错了一栏单据（结束型工具返回 Error:），收银员不会直接把错单甩给客户结束流程，而是把单据退回给实习生（Command(goto="model")），允许他最多重填 2 次！

下面的架构对比图清晰展示了 “粗暴 recursion_limit 裸奔模式” 与 “多维动态工具配额守卫状态机” 的本质区别：

1.2 四种 Agent 步数与工具管控方案全景对比

在设计 Agent 的循环控制层时，业界常见有四种做法。我们通过下面这张表格对比它们在真实线上环境的表现：

管控方案	超限后的用户体验	能否防止沙箱死磕与已验证后倒退？	`return_direct` 工具报错能否自愈？	并发协程安全性	推荐指数
方案 A：仅设 `recursion_limit`	直接抛 `GraphRecursionError`，整轮对话作废	否	否（报错原样吐给前端用户）	安全	⭐
方案 B：在 System Prompt 写“最多调 5 次工具”	模型不会精确数数，长链路下经常超调或过早放弃	否（软提示词无强制力）	否	安全	⭐⭐
方案 C：手写几十个条件边（Conditional Edges）	图拓扑变成意大利面条，每加一个工具都要改图结构	能，但维护成本极高	需侵入式改造每个节点	安全	⭐⭐⭐
方案 D：`AgentMiddleware` 声明式预算状态机（本文方案）	温和拦截探索工具并引导总结交付，100% 优雅软着陆	支持（内置连击上限与 `post_validate` 状态锁）	支持（自动捕获 Error 并 `goto="model"` 自愈）	基于 `ContextVar` + `Token` 100% 协程隔离	⭐⭐⭐⭐⭐

💡 选型建议：

不要把工具调用的业务状态机硬编码进 LangGraph 的节点拓扑（Nodes & Edges）里！
保持图拓扑极简（仅 model <-> tools），把配额、连击限制、状态锁与自愈路由全部收敛到 AgentMiddleware 的工具包装器中，既能按用户角色切换配置画像（Profile），又能做到对业务工具代码零侵入。

二、基础篇：3 分钟设计多角色预算画像（Profile）与 `recursion_limit` 对齐公式

在动手写拦截器之前，我们先解决第一个工程问题：不同角色的用户（比如“普通提问者 standard_user”、“高阶分析师 deep_analyst”、“资产构建者 architect”），他们的工具预算应该如何差异化定义？预算上限又该如何与底层 LangGraph 的 recursion_limit 精确对齐？

2.1 核心公式：为什么 `recursion_limit = 2 * max_non_terminal + 8`？

很多同学自己写了工具计数器（比如允许最多调用 12 次非结束型工具），结果图跑着跑着还是在到达 12 次之前抛出了 GraphRecursionError！

原因很简单：在 LangGraph 的 ReAct 循环里，每调用 1 次工具，图至少要走 2 个超步（Super-steps）：第 1 步是 model 节点生成 tool_calls，第 2 步是 tools 节点执行工具并返回 ToolMessage。
当非结束型工具刚好用满 max_non_terminal 次后，我们还需要留出余量（Headroom，通常为 8 步），让模型能够读取拦截提示、调用 1 次结束型工具（及最多 2 次报错重试）并生成最终回复！

因此，黄金对齐公式为：
$recursion_limit = 2 × max_non_terminal + 8 \text{recursion\_limit} = 2 \times \text{max\_non\_terminal} + 8$

2.2 多角色预算画像（Profiles）配置表与代码实现

我们可以用一张声明式配置字典 PROFILES，把三个角色的权限边界、探索工具集与交付工具集管理得井井有条：

配置字段	`architect`（构建者模式）	`deep_analyst`（高阶分析模式）	`standard_user`（普通问答模式）	字段工程含义说明
`max_non_terminal`	`18`	`16`	`12`	单轮允许调用非结束型（探索类）工具的最大次数
`probe_streak_limit`	`6`	`6`	`0`（禁用原始沙箱）	允许连续调用 `run_diagnostic_sql` / `dryrun_sql` 试探的最大连击数
`terminals`	`submit_schema_proposal`, `create_doc`, `request_user_input`	`request_user_input`, `publish_report`	`request_user_input`, `publish_report`	结束型交付工具集（不受探索预算限制，成功后锁定本轮）
`post_validate_block`	`dryrun_sql`, `fetch_catalog_tables`, `describe_tables`	空	空	一旦 `verify_sql_syntax` 校验通过后，立即禁止回头调用的试探工具
`budget_allow`	`verify_sql_syntax`	空	空	即使探索预算已满，仍破例放行的收尾校验工具

下面是完整的预算画像与 ContextVar 协程隔离状态定义代码：

from __future__ import annotations
import time
from contextvars import ContextVar, Token
from dataclasses import dataclass, field
from typing import Any

# 为结束型工具重试、最终回答合成预留的图步数余量
GRAPH_STEP_BUFFER = 8
CONSECUTIVE_PROBE_OPS = frozenset({"run_diagnostic_sql", "dryrun_sql"})
MAX_DOC_CHARS_PER_TURN = 24_000
MAX_FINALIZER_HEAL_COUNT = 2
MILESTONE_DIGEST_STEP_GAP = 3

PROFILES: dict[str, dict[str, Any]] = {
    "architect": {
        "max_non_terminal": 18,
        "terminals": frozenset({
            "submit_schema_proposal",
            "submit_schema_patch",
            "publish_doc_entry",
            "register_sop_playbook",
            "request_user_input",
        }),
        "post_validate_block": frozenset({
            "dryrun_sql",
            "inspect_raw_tables",
            "list_raw_tables",
        }),
        "exploration_block": frozenset({
            "dryrun_sql",
            "inspect_raw_tables",
            "list_raw_tables",
            "search_data_catalog",
            "search_tech_docs",
            "fetch_doc_section",
        }),
        "budget_allow": frozenset({"verify_sql_syntax"}),
        "probe_streak_limit": 6,
    },
    "deep_analyst": {
        "max_non_terminal": 16,
        "terminals": frozenset({"request_user_input", "generate_final_report"}),
        "exploration_block": frozenset({
            "run_python_sandbox",
            "run_diagnostic_sql",
            "search_data_catalog",
            "execute_sql_query",
            "search_tech_docs",
            "fetch_doc_section",
        }),
        "probe_streak_limit": 6,
    },
    "standard_user": {
        "max_non_terminal": 12,
        "terminals": frozenset({"request_user_input", "generate_final_report"}),
        "exploration_block": frozenset({
            "run_python_sandbox",
            "search_data_catalog",
            "execute_sql_query",
            "search_tech_docs",
            "fetch_doc_section",
        }),
        "probe_streak_limit": 0,
    },
}

@dataclass
class TurnQuotaTracker:
    """单次 Agent 运行期内的预算与状态追踪器（通过 ContextVar 协程级隔离）。"""
    tier_mode: str
    step_used_count: int = 0
    consecutive_probe_hits: int = 0
    syntax_check_ok: bool = False
    finalizer_invoked: bool = False
    started_at: float = 0.0
    original_prompt: str = ""
    steps_since_last_digest: int = 0
    recent_step_snapshots: list[dict[str, Any]] = field(default_factory=list)
    staged_milestone_card: dict[str, Any] | None = None
    finalizer_heal_attempts: int = 0
    doc_loaded_volume: int = 0
    script_fail_tally: int = 0
    script_circuit_tripped: bool = False

_interactive_run_ctx: ContextVar[TurnQuotaTracker | None] = ContextVar(
    "interactive_run_ctx", default=None
)

def compute_safe_graph_limit(tier_mode: str) -> int:
    """动态计算与当前 Profile 工具预算严格对齐的 LangGraph recursion_limit。"""
    cfg = PROFILES.get(profile, PROFILES["standard_user"])
    return 2 * int(cfg["max_non_terminal"]) + GRAPH_STEP_BUFFER

def activate_turn_tracker(tier_mode: str, *, original_prompt: str = "") -> Token[TurnQuotaTracker | None]:
    """在 Agent 会话入口绑定隔离状态，返回用于 finally 还原的 Token。"""
    return _interactive_run_ctx.set(
        TurnQuotaTracker(
            profile=profile,
            started_at=time.monotonic(),
            original_prompt=(original_prompt or "").strip(),
        )
    )

def release_turn_tracker(token: Token[TurnQuotaTracker | None]) -> None:
    """在 finally 块中安全重置 ContextVar，杜绝异步并发请求间的状态串扰。"""
    _interactive_run_ctx.reset(token)

三、进阶篇：六道前置拦截闸门与 `return_direct` 结束型工具报错自愈实战

有了状态对象 TurnQuotaTracker，接下来我们进入最核心的部分：如何在每次工具执行前后（awrap_tool_call）织起一張严密却不死板的安全控制网？

3.1 全链路架构拆解：单步工具执行的“事前六道闸门 + 事后状态跃迁 + 异常重路由”

当模型决定调用某个工具时，中间件会按以下三个阶段依次处理：

3.2 关键设计精讲：为什么需要 `_build_self_heal_redirect`？

在 LangGraph 中，当我们把 submit_schema_proposal（提交数据视图提案）或 generate_final_report（发布分析报告）标记为 return_direct=True 时，LangGraph 的 ToolNode 一旦执行完该工具，就会直接把边路由到 __end__ 节点结束本轮对话。

这带来了一个极其隐蔽的线上 Bug：
假设 submit_schema_proposal 内部有一层严格的 Schema 校验——要求模型必须传入刚刚通过 verify_sql_syntax 验证过的 SQL 引用句柄。如果模型忘了传或者传错了表名，submit_schema_proposal 会返回一条字符串："Error: 请先调用 verify_sql_syntax 校验 SQL 语句"。
由于 return_direct=True 的存在，大模型根本没机会看到这条报错！图直接终止，前端用户莫名其妙地收到了一句本该写给模型看的内部报错！

怎么破局？
我们在中间件里检查：如果当前工具属于 terminals（结束型工具），且返回内容匹配错误特征（如以 "Error:" 开头），同时重试次数 finalizer_heal_attempts < 2，我们就不直接返回 ToolMessage，而是返回一个 langgraph.types.Command(update={"messages": [ToolMessage(...)]}, goto="model")，强行把控制权拉回给 model 节点，让模型看着报错信息立刻补调 verify_sql_syntax 或修正参数再交一次！

3.3 完整可复用代码：`ToolQuotaGuardMiddleware` 核心实现

import json
from langchain_core.messages import ToolMessage
from langgraph.types import Command

LLM_ACTOR_NODE = "model"

def detect_finalizer_failure(content: str) -> bool:
    """判定结束型工具的输出是否为校验失败/执行错误。"""
    text = (content or "").strip()
    if text.startswith(("Error:", "SQL Error:", "[ERROR]")):
        return True
    try:
        data = json.loads(text)
        return isinstance(data, dict) and data.get("ok") is False
    except Exception:
        return False

class ToolQuotaGuardMiddleware:
    """在线 Agent 动态工具配额守卫与状态锁中间件。"""

    def __init__(self, tier_mode: str = "standard_user") -> None:
        self.tier_mode = profile if profile in PROFILES else "standard_user"

    def _build_rejection_reply(self, reason: str) -> str:
        """根据触发的具体拦截原因，生成极具指导性的中文收敛提示。"""
        if reason == "finalizer_invoked":
            return "Error: 本轮已成功调用结束型交付工具，请勿再并发或追加调用其它工具。"
        if reason == "knowledge_read_budget":
            return "Error: 本轮知识库正文读取字符预算（24,000字）已用尽，请直接基于已获取的信息作答或请求澄清。"
        if reason == "analysis_repair_exhausted":
            return "Error: 本轮 Python/SQL 沙箱分析的单次代码修复机会已用尽，请停止重试并向用户说明异常原因。"
        if reason == "post_validate":
            return (
                "Error: verify_sql_syntax 已校验成功！请勿再回头调用 dryrun_sql 或表结构探测工具，"
                "下一步请立即调用 submit_schema_proposal 提交提案，或调用 request_user_input 向用户确认。"
            )
        if reason == "consecutive_probe_hits":
            return (
                "Error: 已连续多次调用沙箱试探 SQL。请立即停止盲目试探，总结目前已发现的数据规律或卡点，"
                "若 SQL 已就绪请调用 verify_sql_syntax，若需用户补充口径请调用 request_user_input。"
            )
        return (
            "Error: 本轮探索工具调用预算已达上限。请勿再发起新的查询或检索，"
            "立即基于已有结果输出最终回答，或调用结束型工具完成交付。"
        )

    def _check_quota_violation(
        self, state: TurnQuotaTracker, cfg: dict[str, Any], op_name: str, terminals: frozenset[str]
    ) -> str | None:
        # 闸门 1：同轮已成功执行过结束型工具，拦截后续多余调用
        if state.finalizer_invoked and op_name not in terminals:
            return "finalizer_invoked"
        # 闸门 2：单轮知识库读取字符数超限
        if op_name == "fetch_doc_section" and state.doc_loaded_volume >= MAX_DOC_CHARS_PER_TURN:
            return "knowledge_read_budget"
        # 闸门 3：沙箱代码执行失败超过单次修复上限
        if op_name == "run_python_sandbox" and state.script_circuit_tripped:
            return "analysis_repair_exhausted"
        # 闸门 4：Architect（架构构建）模式下 SQL 验证已通过，禁止倒退回试探工具
        if self.tier_mode == "architect" and state.syntax_check_ok:
            if op_name in cfg.get("post_validate_block", frozenset()):
                return "post_validate"
        # 闸门 5：沙箱试探连击次数超限
        sandbox_cap = int(cfg.get("probe_streak_limit", 0))
        if sandbox_cap and op_name in CONSECUTIVE_PROBE_OPS and state.consecutive_probe_hits >= sandbox_cap:
            return "consecutive_probe_hits"
        # 放行结束型交付工具
        if op_name in terminals:
            return None
        # 闸门 6：总非结束型工具步数超限（但放行 budget_allow 中的收尾验证工具）
        if state.step_used_count >= int(cfg["max_non_terminal"]):
            if op_name in cfg.get("budget_allow", frozenset()):
                return None
            exploration_block = cfg.get("exploration_block")
            if exploration_block is None or op_name in exploration_block:
                return "budget"
        return None

    async def awrap_tool_call(self, request: Any, handler: Any) -> ToolMessage | Command:
        state = _interactive_run_ctx.get()
        if state is None:
            return await handler(request)

        cfg = PROFILES.get(self.tier_mode, PROFILES["standard_user"])
        terminals: frozenset[str] = cfg.get("terminals", frozenset())
        op_name = request.tool_call["name"]
        tool_call_id = request.tool_call["id"]

        # 1. 执行前置六道闸门检查
        block_reason = self._check_quota_violation(state, cfg, op_name, terminals)
        if block_reason is not None:
            return ToolMessage(
                content=self._build_rejection_reply(block_reason),
                tool_call_id=tool_call_id,
                name=op_name,
            )

        # 2. 执行底层真实工具
        result = await handler(request)
        content = str(result.content or "") if isinstance(result, ToolMessage) else str(result or "")

        # 3. 管控知识库读取字符配额
        if op_name == "fetch_doc_section":
            remaining = MAX_DOC_CHARS_PER_TURN - state.doc_loaded_volume
            if len(content) > remaining:
                state.doc_loaded_volume = MAX_DOC_CHARS_PER_TURN
                content = self._build_rejection_reply("knowledge_read_budget")
                result = ToolMessage(content=content, tool_call_id=tool_call_id, name=op_name)
            else:
                state.doc_loaded_volume += len(content)

        # 4. 事后更新状态机计数
        self._record_tool_outcome(state, op_name, terminals, content)

        # 5. 检查结束型工具是否报错，若报错且未超重试上限则通过 Command 退回 model 节点自愈
        if op_name in terminals and detect_finalizer_failure(content):
            if state.finalizer_heal_attempts < MAX_FINALIZER_HEAL_COUNT:
                state.finalizer_heal_attempts += 1
                return Command(
                    update={"messages": [ToolMessage(content=content, tool_call_id=tool_call_id, name=op_name)]},
                    goto=LLM_ACTOR_NODE,
                )
        return result

    def _record_tool_outcome(
        self, state: TurnQuotaTracker, op_name: str, terminals: frozenset[str], content: str
    ) -> None:
        if op_name in CONSECUTIVE_PROBE_OPS:
            state.consecutive_probe_hits += 1
        elif op_name not in terminals:
            state.consecutive_probe_hits = 0

        if op_name == "verify_sql_syntax" and ("SQL is valid" in content or '"ok": true' in content.lower()):
            state.syntax_check_ok = True

        if op_name in terminals:
            if not detect_finalizer_failure(content):
                state.finalizer_invoked = True
            return

        if op_name == "verify_sql_syntax":
            return

        state.step_used_count += 1

四、高阶技巧：已验证 SQL 作用域防篡改句柄与每 3 步探索进度自动合成

在上面的状态机里，还有两个让系统可靠性翻倍的高阶设计细节：「已验证 SQL 句柄作用域（Validated SQL Scope）」 与 「每 $N$ 步探索进度同步合成（Progress Synthesis）」。

4.1 怎么防止模型“校验时用 SQL-A，提交时偷偷改成 SQL-B”？

在构建数据视图或自动化配置时，模型经常会犯一个滑头错误：它调 verify_sql_syntax(sql_A) 校验通过了，但紧接着调 submit_schema_proposal(sql_B) 时，顺手改了一个字段名或加了一个未校验的 JOIN，结果把一条语法错误的 SQL 存进了生产库！

为了彻底堵死这个漏洞，我们在 activate_turn_tracker 时同步开启一个 verified_query_stmt 作用域：

每当 verify_sql_syntax(sql) 校验通过时，计算该 SQL 规范化后的短哈希 ID（例如 vsql_8f3a1c），存入当前协程的 ContextVar 字典中，并返回给模型：{"ok": true, "verified_query_stmt_ref": "vsql_8f3a1c"}；
当模型下一步调用 submit_schema_proposal 时，强制校核传入的 verified_query_stmt_ref 或 SQL 文本是否存在于本轮已验证池中。如果模型敢偷改一个字符，立即返回 "Error: 当前 SQL 未经过 verify_sql_syntax 校验"，并由刚才讲的 _build_self_heal_redirect 自动退回模型重走校验！

4.2 每 3 步探索工具自动合成阶段性进展（避免事件流时序错乱）

当 Agent 在后台连续调用 search_data_catalog -> search_tech_docs -> execute_sql_query 时，为了让前端用户实时看到高层次的推理进展（而不需要主模型每一步都停下来长篇大论），我们在预算中间件里维护了 steps_since_last_digest 计数器：

注意这里为什么不在后台开一个脱管的 asyncio.create_task 直接往 SSE 队列塞进度事件，而是在 awrap_tool_call 内部同步等待合成完毕、存入 state.staged_milestone_card，再由外层流式循环在 on_tool_end 后主动 pop_pending_milestone_card() 取走？
因为只有这样，才能 100% 保证 progress 事件永远严格出现在第 3 个工具的 tool_end 事件之后、第 4 个工具的 tool_start 事件之前，绝不会发生异步竞态导致的 UI 时间线乱序！

下面是已验证 SQL 句柄池与进度合成器的完整可复用实现：

import hashlib
from contextvars import ContextVar, Token

_verified_query_stmt_pool: ContextVar[dict[str, str] | None] = ContextVar("verified_query_stmt_pool", default=None)

def begin_verified_query_stmt_scope() -> Token[dict[str, str] | None]:
    """开启单轮已验证 SQL 句柄池作用域。"""
    return _verified_query_stmt_pool.set({})

def end_verified_query_stmt_scope(token: Token[dict[str, str] | None]) -> None:
    """销毁单轮已验证 SQL 句柄池。"""
    _verified_query_stmt_pool.reset(token)

def register_verified_query_stmt(sql: str) -> str:
    """当 verify_sql_syntax 校验通过时，登记规范化 SQL 并返回短句柄 ID。"""
    normalized = " ".join((sql or "").strip().rstrip(";").split())
    ref_id = "vsql_" + hashlib.sha256(normalized.encode("utf-8")).hexdigest()[:8]
    pool = _verified_query_stmt_pool.get()
    if pool is not None:
        pool[ref_id] = normalized
    return ref_id

def consume_verified_query_cache(ref_or_sql: str) -> str | None:
    """在 submit_schema_proposal 中校核传入的句柄或 SQL 是否已在本轮通过验证。"""
    pool = _verified_query_stmt_pool.get() or {}
    candidate = (ref_or_sql or "").strip()
    if candidate in pool:
        return pool[candidate]
    normalized = " ".join(candidate.rstrip(";").split())
    for valid_sql in pool.values():
        if valid_sql == normalized:
            return valid_sql
    return None

五、实战避坑指南：高频报错与一键解决速查表

在将动态工具配额守卫中间件集成到 LangGraph Agent 的过程中，如果遇到以下现象，可直接对照下表快速排障：

序号	遇到的报错或现象	背后的真正原因	一句话解决办法
01	工具预算明明只用了 10 次（上限 12 次），图却提前抛出了 `GraphRecursionError`	编译图时的 `recursion_limit` 设成了 `12`，忘了每次工具调用需要消耗 `model + tools` 2 个图超步	严格使用公式 `recursion_limit = 2 * max_non_terminal + 8` 动态注入 `RunnableConfig`
02	`Command(goto="model")` 触发时报错 `ValueError: Unknown node name 'model'`	在 `create_agent` 中挂载了 `before_model` 钩子，导致循环入口节点名称从 `"model"` 变成了前置节点名	动态提示词统一改用 `wrap_model_call` 中间件，并在单元测试中用图节点断言锁死入口节点名 `"model"`
03	模型在同一轮并发调用了 `[submit_schema_proposal, list_raw_tables]`，导致提案提交后又多跑了一次查询	模型在单次回复的 `tool_calls` 数组里同时塞了结束型工具与探索工具	在 `_record_tool_outcome` 中一旦 `submit_schema_proposal` 成功立即置 `state.finalizer_invoked = True`，同批后续工具在 `_check_quota_violation` 第一道闸门即被拦截
04	高并发 FastAPI 环境下，A 用户的工具调用次数莫名其妙加到了 B 用户的头上	将 `step_used_count` 存成了 Middleware 实例属性 `self.count`（单例跨请求共享）	严禁在 Middleware `self` 上存可变状态！所有运行期计数必须存于 `ContextVar[TurnQuotaTracker]` 并在 `finally` 中 `reset(token)`
05	`Builder` 模式下预算刚好用满 18 次，模型想调 `verify_sql_syntax` 校验最后写好的 SQL 却被拦截了	将 `verify_sql_syntax` 当成了普通探索工具一刀切封禁	在 `PROFILES["architect"]` 中配置 `"budget_allow": frozenset({"verify_sql_syntax"})`，为收尾校验留出绿色通道

结语

回顾本篇《Agent Harness 架构手册 #01》，我们用一套不到 200 行的 ToolQuotaGuardMiddleware，彻底扭转了 LangGraph ReAct 智能体在线上环境“要么无限空转、要么一超步就崩溃”的被动局面：

用立体配额替代单一死线：将工具划分为“探索型（exploration_block）”、“收尾校验型（budget_allow）”与“结束交付型（terminals）”，预算耗尽时只封堵探索、逼迫模型优雅收敛交付；
用单向状态锁阻断无效倒退：一旦 verify_sql_syntax 通过，立即开启 post_validate_block 锁死回头试探，并配合 ContextVar 已验证 SQL 句柄池杜绝“验 A 交 B”；
用 Command(goto="model") 救活 return_direct：让结束型工具在参数校验失败时能够自动退回模型自愈重试，把冰冷的报错消灭在内部循环中。

👉 下一篇预告（#02）：当我们的 Agent 在预算护栏内高速调用十几个工具时，怎么把枯燥生硬的 tool_start / tool_end 原始 JSON，变成前端界面上丝滑优雅、带业务意图与数据规模提炼的实时动态流？下一篇《告别满屏生硬 JSON：AI Agent 声明式 Action Feed（实时活动流）架构实战》我们不见不散！