第 19 章：Agent 通用工具箱 — 与框架无关的公共设施

编排框架会换（第 18 章决策树每半年重画一次），但一套 Agent 系统真正每天在用的公共设施很少换：工具怎么注册、人怎么审批、钱怎么记账、坏了怎么回放。本章把这些"瑞士军刀"一次配齐——它们与 LangGraph / CrewAI / OpenAI SDK 都解耦，换框架时可以整箱搬走。

---

19.1 为什么需要「工具箱层」

一个跑了三个月的生产 Agent，代码里占比最大的往往不是编排逻辑，而是下面这些横切关注点：

┌──────────────────────────────────────────┐
│              你的业务 Agent               │
├──────────────────────────────────────────┤
│  🛡️ Guardrails   🔐 审批网关              │
│  📊 成本追踪      🧪 回放调试              │
│  🔧 工具注册      🌐 数据基建              │
├──────────────────────────────────────────┤
│        编排框架（随时可换）                │
└──────────────────────────────────────────┘

判断标准：任何一段代码，如果换框架时你不想重写，它就该进工具箱层。

---

19.2 工具注册中心

不要在代码里散落 @tool 装饰器了事。生产级工具注册需要每工具一份元数据卡：

TOOL_REGISTRY = {
    "web_search": ToolCard(
        desc="搜索公开网页",          # 给模型看的一句话
        cost_per_call=0.002,         # 预估美元成本，供预算闸门使用
        risk="low",                  # low / medium / high（决定是否需审批）
        timeout_s=15,
        rate_limit="60/min",
        fallback="raise",            # 失败策略：raise / degrade / skip
    ),
    "send_email": ToolCard(
        desc="给白名单联系人发邮件",
        cost_per_call=0.0,
        risk="high",                 # 触发 19.3 的审批网关
        allowlist="contacts.vip",
    ),
}

三个工程要点：

1. 描述即契约：desc 会进 system prompt（第 27 章上下文预算），写得含糊模型就会瞎调。
2. 风险分级驱动审批：risk 字段不是摆设，它直接决定调用前是否暂停等人。
3. 注册中心是审计起点：第 16 章的 trace 里每条工具调用都应能反查到 ToolCard。

---

19.3 审批网关（Human-in-the-Loop）

第 3 章的 interrupt 和第 9 章的 permission model 都是框架内实现。工具箱层的审批网关要做成框架无关的三段式：

工具调用请求
    → ① 规则引擎判定（白名单 / 风险级 / 金额阈值）
    → ② 需审批 → 挂起任务 + 推送审批卡（IM / 邮件 / 控制台）
    → ③ 人批准 → 带签名放行；拒绝 → 返回结构化拒绝原因（喂回模型）

关键设计：拒绝原因要喂回模型（"用户拒绝了：预算超限"），模型下一轮才会调整策略而不是反复撞墙。审批记录本身进审计日志——这是第 25 章权限体系支柱的证据链。

---

19.4 成本追踪器

第 15 章讲的是"怎么省"，这里讲"怎么记"。三个维度缺一不可：

维度	用途	示例
按 Agent	找出最烧钱的智能体	researcher 占 62% 成本
按任务	定价与毛利核算（第 29 章变现的前提）	单份报告成本 ¥0.83
按工具	砍掉性价比最低的调用	web_search 月均 4,200 次

最小实现不需要平台：每次工具调用前后记 (agent, task_id, tool, tokens, usd) 一行，落到 SQLite 就够用；到需要跨服务聚合时再上 Langfuse（第 16 章）。

💡 成本追踪与第 29 章直接联动：你说不清单份产出的成本，就不可能给它定价。

---

19.5 回放与重放

调试 Agent 最痛的不是"报错"，而是"结果不对但没有现场"。解法是轨迹持久化 + 确定性重放：

1. 轨迹持久化：每轮记录 (prompt 版本, 模型版本, 工具调用及响应摘要, 随机种子)。
2. 确定性重放：工具响应用录制快照而不是真实调用——重放不花钱、不出网、结果可复现。
3. 回归测试：把线上翻车轨迹直接变成第 30 章的评测用例（"事故的化石层"）。

MiniHarness（examples/11-mini-harness）的失败恢复支柱里已有最小可用的状态快照实现，回放层可以直接叠在它上面。

---

19.6 Guardrail 工具集

四道闸，按顺序架设：

1. 输入过滤：prompt 注入特征、敏感信息（正则 + 小模型双保险）。
2. 输出校验：JSON schema 断言 + 内容安全（第 30 章单元级评测的用例来源）。
3. 越权检测：工具参数里出现目标资源之外的 ID（如给非白名单邮箱发信）——这是 19.2 allowlist 的运行时强制执行。
4. 熔断降级：同一工具连续失败 N 次 → 自动摘除并告知模型"该工具暂不可用"（第 25 章失败恢复支柱的组件化）。

---

19.7 数据基建：把「网页 → 语料」外包出去

Agent 访问互联网的自建方案（requests + BeautifulSoup）在 2026 年已经不划算：反爬、JS 渲染、清洗分块都是无底洞。按第 28 章的结论，这类"脏活"外包给专职基建：

需求	首选	备选
网页 → Markdown/结构化	firecrawl	Jina Reader
通用搜索 API	Tavily	Serper / Brave Search API
本地/私有数据	第 6 章 LlamaIndex RAG	Dify 知识库

接入模式：统一包一层 ToolCard 注册进 19.2 的注册中心，成本与限流就自动纳入 19.4 的记账——这就是工具箱层"整箱搬走"的意义。

---

19.8 本章小结

• 工具箱层的判断标准：换框架时不想重写的代码。
• 六件套：工具注册（元数据卡）→ 审批网关（三段式）→ 成本追踪（三维记账）→ 回放（确定性重放）→ Guardrails（四道闸）→ 数据基建（外包给专职服务）。
• 每一件都与全书方法论挂钩：审计（16 章）、权限（25 章）、评测（30 章）、定价（29 章）。
• 先记账，再定价；先回放，再迭代——工具箱层的两句话箴言。

---

下一章

→ 第 20 章：OpenAI Codex CLI 详解

📚 串联阅读：第 15 章 成本优化 → 第 16 章 可观测性 → 第 25 章 Harness Engineering → 第 29 章 Agent 经济 → 第 30 章 评测体系