《AI Agents in Depth》学习笔记（四）：工具

4.2.1 能力表达形式：专用工具还是 Skill + 通用执行器#

• 专用代码工具：结构化函数调用，确定性高、可测试；但每个工具占数百 token，数量膨胀会破坏 KV Cache。
• Skill + 通用执行器：自然语言 Skill 文档描述流程（如”1. npm run build；2. docker build；3. kubectl apply”），Agent 经终端/代码解释器执行，少量通用工具覆盖大量场景。

三维决策：参数复杂度（嵌套对象、多字段联合校验适合结构化 schema 引导；简单参数走 CLI 同样可靠）、变更频率（频变能力用 Skill——改文本远比改代码+测试+部署轻松；稳定底层操作做专用工具）、模型能力（SOTA 模型可用 Skill + 执行器表达更多能力；弱模型需要 schema 引导）。

4.2.2 工具粒度：整合与分离#

粒度过细→数量激增（超过约 100 个工具时最先进的 LLM 也易选错）；过粗→单个工具过于复杂。整合标准是功能相似性与使用场景重叠度：extract_pdf_text/extract_docx_content/extract_pptx_content 应整合为 read_document（file_type 参数区分）——降低认知负担、描述更清晰、便于扩展。但参数形态、延迟特性差异大的功能（图片 OCR vs 视频关键帧提取）强行合并反而语义模糊；参数集差异大或使用频率极高的保持独立。

4.2.3 通用性设计#

**通用工具优于专用工具，除非存在明确的安全、权限或性能理由。**与其做四则运算计算器，不如提供沙盒中装好 sympy/numpy/pandas 的 code_interpreter——LLM 本身有强大的思考与代码生成能力，应利用而非限制；一个 Python 解释器可代替数十个专用工具，还能处理预先没想到的边缘场景。边界：需特殊权限、复杂配置或有安全风险的操作仍需封装良好的专用工具（生产库写操作要精细权限与审计；各 OS grep 语法不同，专门的 grep 工具更好）。

4.2.4 工具描述的艺术#

• 核心是让 LLM 知道**“什么时候用”**而非只是”能做什么”：“当需要获取实时信息或查找未知事实时使用”胜过”搜索相关内容”。
• 边界比能力更重要：明确做不到什么、不接受什么输入。多数调用失败的根因不是不知道工具能做什么，而是不知道不能做什么。
• 参数用具体例子代替抽象规范：“phone：E.164 格式（国家代码+号码，无空格），例如 +8613888888888”——复杂任务中确认格式只占模型注意力一小部分，可套用的例子省去额外思考。
• 描述返回值结构（“JSON 数组，每元素含 title、url、snippet”）与执行代价（“大型网站需 5-10 秒；只要元信息请用 get_page_metadata”）。
• 附 1-5 个真实调用示例：JSON Schema 表达不了调用方式与典型参数组合（时间戳秒还是毫秒、过滤条件如何嵌套）；加示例后调用准确率在一些基准上可从约 72% 提升到 90%。

4.2.5 参数传递的保真性#

两种隐蔽反模式：静默输入转换——工具悄悄”修正”输入。案例：Cursor 某版本把中文弯引号静默转成英文直引号，模型读文件看到弯引号、原样传入 old_string，替换却报”未找到匹配”；写入方向同样被篡改。模型反复失败且无法自行诊断。静默参数注入——某 IDE 的 bash 工具给所有 git commit 自动附加”AI 生成”标记参数，旧版 Git 不支持时怎么改提交信息都报错。

4.2.6 工具设计的三代演进#

第一代：直接封装 API，每个端点一个工具，粒度过细。第二代：ACI（Agent-Computer Interface）原则——对标 HCI，研究 Agent 如何与计算机交互，核心是让工具对 Agent 友好：工具对应 Agent 的目标而非底层 API 操作（粒度、通用性、描述规范皆属此阶段）。第三代：优化工具被调用（示例驱动）、发现（动态工具发现）与串联（代码编排执行）的方式——LLM 一次性生成脚本，中间变量留在执行环境，只返回最终结果（像领导一次写好操作手册而非每步邮件往返）；抓取多网页批量提取字段时页面全文不进上下文，token 消耗可降约两个数量级，属第五章”代码作为通用 Agent 元能力”范式。

4.7.1 为什么需要异步#

同步 Agent 像只会排队的柜台，真正的助手像灵活的秘书——多个事项按紧急程度决定先后、可暂停切换。同步模式撑不起三项核心能力：异步执行是常态（长任务不应阻塞交互）、事件优先级动态判断（取消当前操作/入队/并行）、中断与恢复的流畅性。

事件驱动架构：不轮询”有没有新消息”，而是新消息到达自动触发处理；所有输入、输出、思考与外部交互统一建模为事件流（原书图4-2 展示事件源→事件队列→Agent 处理流程的整体架构）。

4.7.2 从 OpenClaw 看事件驱动的现实需求#

OpenClaw 经 Gateway 控制平面接收多渠道消息并路由到 Agent 运行时，内置三种自动化机制：Hooks（响应 Agent 生命周期事件，类似 GitHub Actions 触发器）、Cron（按 cron 表达式执行周期任务）、Heartbeat（每隔 N 分钟唤醒检查，凭判断力避免警报疲劳）。但真正让 Agent 在无用户消息时”自己动起来”的只有 Cron 和 Heartbeat，而二者都是时间驱动；Hooks 只被动响应框架内部事件。短板：对内置渠道之外的第三方事件源（新邮件、API 回调、紧急通知）缺乏即时接入通道，只能等下一个周期才察觉。

PineClaw（Pine AI 的 OpenClaw 插件；Pine 代替用户打真实电话：协商账单、取消订阅、保险理赔）不容此延迟：通话中随时需要用户立即提供 OTP 验证码、几秒内接听三方通话、确认降价方案。5 分钟心跳轮询下客服早已挂断，秒级轮询又造成大量无效请求。解法是 Channel 机制——在 Gateway 与 Pine API 间建实时事件通道，关键事件即时推送，响应延迟从分钟级降到秒级。核心结论：真正的”主动服务”不仅需要 Agent 能定时检查世界，更需要世界能主动通知 Agent。

4.7.3 事件触发工具#

• 定时器（set_timer）：处理依赖物理时间的事件。一次性定时器用于明确时间点（周六收到”给 DMV 打电话”，设”下周一上午 10<00> 致电”）；循环定时器用于周期任务与对不支持推送的服务定时轮询——Heartbeat 即其系统化。
• 后台任务监控（monitor_shell）：长后台命令若不断轮询浪费 token，等完全结束又无法及时发现问题、卡死时无法介入；Claude Code 的 monitor 工具允许监控新增输出或含特定关键词的输出。
• 外部事件通道（connect_channel）：把新邮件、API 回调、IM 消息实时推送给 Agent（PineClaw Channel 即典型实现）。

设计要点：清晰的触发条件与过滤规则（防无关事件唤醒浪费算力）；事件载荷（payload）含足够上下文（减少唤醒后的额外查询）。

4.7.4 用户沟通工具#

多数 Agent（Claude Code、Manus 等）的 assistant 消息直接发给用户，用户必须打开指定 session 对话。OpenClaw 打破此范式：session 对用户透明，双方随时互发消息而非一问一答——“活人感”如秘书异步沟通。此时消息用专门的工具发送，可附图片文件、按紧急程度附推送提醒；进一步有结构化卡片、提醒邮件乃至生成式 UI（HTML 交互界面）。设计上支持异步消息（用户不一定在线）、已读/未读追踪、多渠道消息一致性。

类别边界：同样是”发通知”，对象是审批者/协作者归协作工具，是最终用户本人才归用户沟通工具——区别不在渠道，在”通知谁、为什么通知”。通知机制同时是用户召回机制：扩展到 IM、短信、邮件、电话、推送多渠道，按紧急程度、用户状态、内容性质、用户偏好综合选择；长任务完成时主动召回注意力，定期任务帮助用户建立交互习惯。

4.7.5 虚拟身份与隔离执行环境#

（本质是执行环境基础设施，与沙盒一脉相承；放在此节因独立常驻、随时代表用户行动的 Agent 最需要它。）

架构选择：直接管理用户个人账号，还是独立虚拟身份？直接管理便捷，但 Agent 出错或被攻破时用户全部数字身份暴露。更稳妥的是独立虚拟身份——专属通讯账号、存储、计算环境（如秘书有自己的办公电话和邮箱）；身份的明确性反而增强沟通真实性。落地在虚拟电脑（VM/容器）与虚拟手机（Android 模拟器）：Agent 有自己的账号、家目录、凭证，操作可追溯可审计，出错不影响宿主与真实设备——沙盒隔离代码执行，虚拟设备隔离整个数字身份。

两个现实挑战：①反自动化机制——CAPTCHA 与 IP 信誉检测拦截数据中心 IP，实践中常需住宅代理网络（真实家庭 IP）；②必须以用户本人身份登录时——用 HITL 认证：VNC/RDP 远程桌面让用户在可视化环境中亲自登录（可看到 Agent 操作的完整界面），会话令牌有效期内复用，平衡自主性与安全性。主 Agent 与虚拟环境的数据交换用共享文件系统（卷挂载如 /workspace/shared）：传递文件路径引用而非内容拷贝，避免占用上下文窗口。

4.7.6 事件处理机制#

骨架是事件循环（event loop）：每轮从队列取事件→追加轨迹→调用一次 LLM→执行工具→回到循环（同 Go 的 for-select 结构）。关键性质：事件只在每轮循环的边界被消费——LLM 推理、工具执行期间新事件先排队，到安全点（一段推理结束、一次工具返回）再统一处理；取消也在安全点检查（如 Go 的 ctx.Done()）。三种策略的区别只在对待安全点的方式：等下一个自然安全点（队列式）、主动提前制造安全点（取消式）、另起循环不等安全点（并行式）。

结构化事件建模：输入不只来自用户，每个输入按四维建模——来源（用户/联系人/陌生人/系统）、渠道（电话、短信、邮件、定时器、异步工具结果等）、内容（文本、情感、紧急度、是否需回复）、上下文（是否回复既有对话、与当前任务关联）：

1
{
2
  "source": {"type": "email", "sender": "client@example.com"},
3
  "channel": "gmail_webhook",
4
  "content": {"subject": "退款请求", "body": "订单 #12345 希望退款..."},
5
  "context": {"priority": "high", "customer_tier": "vip", "related_orders": ["#12345"]}
6
}

统一建模使 Agent 在多方通信中保持清晰认知，避免把用户输入误当工具结果、或把藏指令的工具结果误当用户指令（提示注入）。

三种处理策略（原书图4-3）：

• 取消式（Cancellation-Based）：紧急事件，本质是提前制造安全点——停止当前操作（取消流式响应/发取消信号）→清空队列→队列事件与紧急事件一起追加轨迹→立即重新调用 LLM 评估局势（例：用户喊”停止！我说错了”）。
• 队列式（Queued）：常规事件——入队不打断→等当前操作完成→工具返回时检查队列、一次性追加→LLM 综合处理。批量提效：搜索期间用户补充”只看最近一个月”，结果返回时两事件一起呈现，省一次往返。
• 并行（Parallel）：独立轻量查询（主任务分析数据时用户问天气）。三特征：与主任务无关、需快速响应、执行成本低。在并行推理会话中独立执行并立即返回，查询与响应追加主轨迹并明确标记”与主任务并行执行”防混淆。

紧急度判定：紧急——user.interrupt、supervisor.instruction、agent.interrupt、标记紧急的外部触发（系统告警、支付失败）；非紧急——常规输入、tool.result、timer.trigger 等。硬编码规则有局限，语义决定策略（“马上停下”取消式、“天气怎么样”并行式、“报告用中文发我”队列式），建议用轻量级分类 LLM 作事件路由器。

实验 4-4（★★★）：事件驱动邮件处理 Agent——邮件、IM/短信、GitHub、定时器、Webhook、系统事件统一入队，每个事件触发一次独立思考循环。验证：会议邀请自动查日历冲突并起草回复、客户投诉标高优并通知、营销广告归档，全程无需用户介入。

4.7.7 工程实现：让同步模型支持异步打断#

核心思想：常态下让 LLM 看到标准同步轨迹，只在打断时插入占位符修复格式。五条规则：

1. LLM 输出时立即记录 assistant message（thinking、content、tool call）。
2. 工具完成时才记录 tool result（执行中轨迹处于”部分完成”状态）。
3. 工具执行中被打断→为未完成工具生成占位符响应（“工具正在后台执行，请优先处理新事件”），追加打断事件、重新调用 LLM——LLM 视角里 assistant message 仍有配对的 tool result。
4. LLM 思考中被打断→直接丢弃当前思考，不写入轨迹，新事件追加后开新一轮。
5. 非打断事件入队等批处理，当前周期完成后一次性追加。

示例：起草邮件时 search_contacts 未返回、用户问天气→生成占位符→处理天气→联系人结果到达后作为新事件追加→继续起草。优势：常态轨迹完美同步，对同步训练的 LLM 最友好。残留风险：模型可能”编造”未返回的工具结果——训练数据里工具调用后几乎总跟着真实结果，模型没学过”结果还没回来”。故实践中只在真正紧急时打断，非紧急一律排队。

批量事件的注意力分散：模型被训练为对最新输入做反应，批量事件时往往只关注最后一个。两层干预——提示词声明”确保全面考虑所有信息”；Agent 状态栏为每个事件加显式标记并在末尾汇总：

1
[未处理事件 1/4] Tool result from database_query：...
2
[未处理事件 2/4] User 补充说明：只看北京地区的数据
3
[未处理事件 3/4] 系统提醒：报告截止时间还有 30 分钟
4
[未处理事件 4/4] User 询问：进度如何？
5
（末尾汇总：上面有 4 个未处理事件……请确保回应涵盖所有信息。）

4.7.8 深层矛盾与未来方向#

占位符、异步接口、状态栏标记本质都是用提示工程弥补训练不足的过渡方案。真正解法需训练范式转变——类似机器人领域 VLA（Vision-Language-Action，视觉-语言-动作）模型面对感知-动作延迟的路径。下一代模型需经异步环境强化学习获得三种能力：①理解轨迹中事件的异步穿插（tool call 之后可能是新 user 消息而非 tool result；被打断的思考中间状态保留、处理完继续而非重来）；②恢复被打断的任务与思考（记得未完成任务，尤其避免误以为被打断的工具已完成的幻觉）；③批量事件的综合处理。配套基础设施：异步环境模拟器（工具延迟、随机打断）+异步能力专项奖励。

“持续思考”不必等下一代模型：约两百行编排逻辑即可让现成文本思考模型变成持续思考（continuous-time）Agent——规则 4 的升级版：不丢弃半截思考，而是把交互建成一条不间断思维流——随时强行合上 <think> 块、把新观察作为普通消息注入、让模型接着解码。它利用被浪费的资源：模型每秒生成上千 token，而工具调用/用户说话要几秒——等待都是”白赚的算力”。由此长出边等边想（基于半截信息提前思考、甚至抢先调工具，多个模型家族零样本复现）与边做边想（输出中途纠正自己）。更关键的发现在训练侧：用”LLM 当裁判”式奖励，模型学会藏起思考换好评、客观指标反而变差；只有可验证、保信息覆盖度的目标才有实打实收益——编排让行为成为可能，训练让行为变好。

实验 4-5（★★★）：并行执行+打断——异步工具执行（长命令期间即答”现在几点”）、事件批处理（连发”用日语回复""整理成网页”完成时一并处理）、打断取消、并行任务状态查询（三个每秒 3%/2%/1% 的脚本，最快者完成后查其余进度、取消未过 50% 的那个）。

4.8.1 现有工具发现方法#

全量注入在上千工具时失效；检索式预筛选的内在局限是按初始查询做一次性匹配——“Debug the file”实际可能牵出文件访问、代码分析、命令执行等多步跨领域工具链，开始时无法预见。

从被动选择到主动发现：Agent 在执行中意识到能力缺口时，主动用自然语言声明”我需要什么能力”，系统动态匹配注入。代表工作 MCP-Zero：系统提示词不预置任何工具 schema，Agent 在思考中生成结构化请求块（“GitHub 服务器：搜索仓库并返回元数据”），经服务器级→工具级两层语义路由匹配注入，约 2800 个工具上比全量注入节省约 98% token。工程等价方案：系统提示词只留少数基础工具+一个”工具搜索工具”（Anthropic 的 Tool Search Tool 属此类）。共同点：Agent 声明缺口、系统按需注入。

层次化匹配与降级：工具按服务器分组（类似手机 App），先定位服务器再匹配工具，搜索空间从”数千工具”缩为”数十服务器×每个数十工具”。依赖离线构建、增量更新的嵌入索引；两层相似度都低于阈值时明确返回”未找到”，让 Agent 改写需求、用基础工具手工实现或创造新工具（第八章）。

动态加载与 KV Cache：若全部工具定义放静态前缀，每加载新工具整段缓存失效。破解：新 schema 追加到上下文末尾，静态前缀保持稳定、缓存完全复用，状态栏只维护简短工具名列表。已成主流默认架构：OpenAI Responses API 的 tool_search + defer_loading: true（schema 以 tool_search_output 追加末尾）；Claude Code 对 MCP 工具默认延迟加载（tool_reference blocks 按需注入）；Codex CLI 的 tool_search（BM25 检索）默认开启。澄清易误解处：“追加到末尾”只发生在发现那一轮——此后 schema 块固定在轨迹原位置、成为普通历史消息，后续轮次持续命中缓存；真正导致重算的只有 Prompt Cache TTL 过期和修改/移除/重排已加载的工具集。原书图4-9 展示多轮发现后的上下文全貌：静态前缀只含系统提示词+核心工具+搜索元工具，历次发现的 schema 散落轨迹各处、固定于首次注入位置——“工具定义必须在上下文最前面”不再是铁律；代价是模型须在后训练中学会理解散落各处的定义，弱模型还易生成非法调用格式，需 RL 专门训练（第七章）。

实验 4-6（★★★）：Qwen3-4B + 120+ 工具。对照组全量注入（超 50K tokens）——4B 模型指令遵循严重退化：查股价错选 Web Search 而非 Yahoo Finance 工具、“忘记”工具导致失败。实验组：system prompt 仅留 web_search、code_interpreter、discover_tools 元工具；discover_tools 按嵌入相似度返回 3-5 个候选及完整 schema，新定义追加对话历史、状态栏更新工具名列表。预期：准确率与完成率显著提升——主动发现让小模型在上百工具场景保持可用。

4.8.2 Skills：把工具发现变成”按需查阅”#

与上节最大不同：不需要”嵌入索引+语义匹配”基础设施。

• 一层层查而非一次性全暴露：启动时只见薄薄的目录（每个 skill 的 name + description，合计数百 token）；当前上下文真需要某能力时才读对应 sub-skill，再顺引用往下读脚本/子文档。“发现”由上下文里的实际需要驱动，而非任务开始时的一次性预匹配——即渐进式披露（Progressive Disclosure）。
• 像查工具书/维基百科：没人从头读到尾，顺索引按需精确查阅。Agent 靠通用文件阅读能力（grep、读文件）翻阅目录即可，不必把”发现工具”建模为特殊的语义检索。
• KV Cache 新问题与解法：同一批 skill 会跨会话、跨用户、在不同位置反复加载，每次随历史从头 prefill 成本不小。解法是第二章的”可编辑、可组合的 KV Cache”：每个 skill 的 KV 表示预编译缓存一次，RoPE 重定位”粘贴”到任意位置，以 O(L) 而非 O(L²) 代价拼接；小改动以”勘误笔记”增量修正——skill 从”每次重新 prefill 的文本”升级为”可复用、可组合的缓存对象”。