基于李博杰《深入理解 AI Agent：设计原理与工程实践》第4章学习笔记（上篇）。
开篇：从《Her》中的 Samantha 说起
科幻电影《Her》里，AI 助手 Samantha 能主动整理邮件、识别情感复杂的信件并提议润色回复，能代表主角处理出版事宜，还能在不同沟通渠道间无缝切换。她的智能之所以动人，是因为她拥有强大的工具------连接语言"大脑"与真实数字世界的"手脚和感官"。
但今天的我们想构建这样的助手，要直面两个核心挑战：
- 工具选择的挑战：当数千个工具的说明文档足以撑爆上下文窗口时，Agent 如何准确高效地找到完成任务所需的那一个？如何从被动"选择"进化为主动"发现"？
- 异步与事件的挑战：Agent 如何管理耗时任务、处理随时到来的中断，响应邮件、日历、系统告警等外部事件，而不陷入同步等待的僵局？
一、五类工具的分类总览
理解工具设计差异，可以从两个特征审视每类工具：
- 调用方向：这次交互由谁发起？
- 作用对象：这次交互作用于什么？
| 工具类型 | 调用方向 | 作用对象 |
|---|---|---|
| 感知工具 | Agent 主动调用 | 获取信息 |
| 执行工具 | Agent 主动调用 | 改变世界 |
| 协作工具 | Agent 主动调用 | 驱动其他 Agent 或人类 |
| 用户沟通工具 | Agent 主动调用 | 向用户传递信息 |
| 事件触发工具 | Agent 注册、外部触发 | 驱动 Agent 开始执行 |
前四类由 Agent 主动调用；事件触发工具特殊------注册时 Agent 主动调用、声明自己关心什么事件，触发时由外部事件异步回调唤醒 Agent。没有它，Agent 只能在用户发起对话时被动响应，无法在指定时间自主行动，也无法对新邮件、系统告警做出反应。
二、工具设计的通用原则
2.1 能力表达形式：专用工具还是 Skill + 通用执行器
Agent 的能力有两种基本表达形态：
- 专用代码工具：结构化函数调用，确定性高、可测试，但每个工具占数百 token，数量膨胀会破坏 KV Cache。
- Skill + 通用执行器：用自然语言写 Skill 文档描述操作流程，Agent 通过终端或代码解释器执行，少量通用工具即可覆盖大量场景。
例如"部署应用"的 Skill 文档可写成三步命令（npm run build → docker build → kubectl apply），Agent 通过 bash 逐步执行，无需为每步创建专用工具。
选择取决于三个维度：参数复杂度 （嵌套对象、多字段校验用专用工具；简单参数用 CLI 同样可靠）、变更频率 （频繁变化的能力用 Skill 维护更便宜）、模型能力（SOTA 模型可用 Skill+执行器；较弱模型需要结构化 schema 引导）。
2.2 工具粒度的权衡：整合与分离
粒度过细导致工具数量激增，增加 LLM 选择负担；粒度过粗使单个工具过于复杂。工具超过 100 个时，即使最先进的模型也容易选错。
判断整合的核心标准是功能相似性和使用场景的重叠度 。以文档处理为例，extract_pdf_text、extract_docx_content、extract_pptx_content 共性都是"从文档提取文本"，更好的设计是统一的 read_document 工具，用 file_type 参数区分格式。但并非所有工具都该整合------图片 OCR 和视频解析虽然都是"内容提取"，参数形态、延迟差异大，强行合并反而让接口语义模糊。
2.3 工具的通用性设计
通用工具优于专用工具，除非存在明确的安全、权限或性能理由 。与其提供十几个专用计算器，不如提供通用的 code_interpreter 工具，在沙盒中装好 sympy、numpy、pandas，让 Agent 通过 Python 完成任意数学计算。
逻辑在于：LLM 本身有强大的思考和代码生成能力，提供通用工具相当于给 Agent 一个"元能力"，还能处理没想到的边缘场景。但通用性有边界------需要特殊权限、复杂配置或有安全风险的操作，封装良好的专用工具仍然必要（如各平台 grep 语法不同，专门的 grep 工具比自由发挥更好）。
2.4 工具描述的艺术
工具描述的核心是让 LLM 知道**"什么时候用"**，而不只是"能做什么"。"当需要获取实时信息或查找未知事实时使用"远比"搜索相关内容"有效。
关键要点：
- 边界同样重要 ：文件搜索工具要说明"只能按文件名匹配，不能搜内容"。大多数工具调用失败的根因，不是模型不知道工具能做什么，而是不知道工具不能做什么。
- 参数用具体例子 ：
timestamp：RFC3339 格式，例如 2024-03-15T14:30:00Z比单写"RFC3339 格式"有效得多。 - 描述返回值："返回 JSON 数组，每个元素含 title、url、snippet 三字段"能减少解析出错。
- 附 1-5 个真实调用示例：JSON Schema 表达不了调用方式和典型参数组合，加入示例后工具调用准确率可从约 72% 提升到 90%。
实用调试原则：Agent 频繁选错工具时，优先检查工具描述而不是怀疑模型能力。
2.5 参数传递的保真性
比功能缺失更隐蔽的反模式是静默输入转换------工具在执行前悄悄"修正"模型输入，导致实际操作偏离模型意图。书中以 Cursor 某版本为例：工具把中文弯引号静默转换为英文直引号，模型读取文件时看到弯引号、原样传入替换参数，却永远匹配失败------模型无法理解为什么"明明看到了却找不到"。
另一种是静默参数注入 ------工具在模型不知情时向命令追加参数。某 IDE 的 bash 工具给所有 git commit 自动附加 AI 标记参数，旧版 Git 不支持就导致反复失败。
基础原则：模型感知到的世界与工具操作的世界之间，不能存在系统性偏差。参数传递必须透明，确需规范化处理（如统一编码）必须在工具描述中说明。
2.6 工具设计的演进
三代演进：第一代直接 API 封装 （粒度过细，Agent 需协调多个工具）；第二代 ACI 原则 （Agent-Computer Interface，工具应对应 Agent 的目标而非底层 API 操作，对标 HCI）；第三代在单工具之上优化工具被调用、串联、发现的方式------示例驱动调用、动态工具发现、代码编排执行（LLM 一次性生成脚本，中间变量留在执行环境，只有最终结果返回，token 消耗可降低约两个数量级）。
三、工具生态：MCP 与工具选择的挑战
每个框架定义工具的方式都不一样------OpenAI 的 function calling、Anthropic 的 tool use、LangChain 的 Tool 抽象，工具开发者要为不同框架重复适配。**Model Context Protocol（MCP）**是 Anthropic 于 2024 年底发布的开放标准，相当于给 AI 工具生态制定通用的"插座标准"。
MCP 的关键设计
- 标准化的工具描述格式：每个工具通过 JSON Schema 定义参数类型、约束和描述。
- 传输层灵活：本地用 stdio，远程用 Streamable HTTP。
- 资源与工具分离：除可执行的工具外，MCP 还定义只读的资源（文件内容、数据库记录）和提示模板（prompts）。工具、资源、提示三类原语分别对应"模型可执行的操作""应用可读取的数据""用户可选用的模板"。
MCP 的生态价值是一次开发，处处可用------一个服务器可同时被 Cursor、Claude Desktop、OpenClaw 等任何兼容客户端使用。
MCP 的三个挑战
1. 同步调用的限制。MCP 主体仍是请求-响应式。通知、进度、采样等扩展原语都作用于保持连接的会话之内，无法唤醒一个当下没有运行的 Agent。跨会话、多事件源、离线唤醒的事件驱动架构需在协议之上另行构建。
2. 上下文开销管理 。仅仅 5 个 MCP 服务器就可能引入约 55,000 token 的工具定义开销，200K 窗口里没开始对话就用掉近三成。Cursor 的缓解方案：工具描述同步到文件夹，Agent 默认只看到名称索引，需要时再查定义------A/B 测试显示总 token 消耗减少 46.9% 。这与第二章的 KV Cache 友好设计、Skills 渐进式披露一脉相承：默认少给，按需加载。
3. 层次化组织与动态发现 。工具增长到上百个时，按信息源性质分类比扁平列表更有效：搜索工具、读取工具、解析工具、查询工具。Anthropic 实验显示，按需检索的方式使 Opus 4 的工具使用准确率从 49% 提升到 74%。从 MCP 到 Skills：MCP 解决互操作，Skills 解决选择过载------把"工具选择"问题转化为 LLM 擅长的"知识检索"问题。
MCP 的安全风险
每接入一个 MCP 服务器，等于把一段不受控制的文本注入 Agent 上下文，还可能把凭证交到别人手里。四类风险：
- 工具描述投毒：description 随工具定义进入上下文，恶意服务器可夹带指令------本质是提示注入的变种。
- 恶意或被劫持的服务器：供应链攻击或远程服务器被入侵。
- 同名工具遮蔽：恶意服务器用同名工具"遮蔽"正规工具，诱导 Agent 把含敏感参数的调用路由到攻击者手中。
- 凭证管理风险：Agent 代表用户持有 OAuth token 或 API key，被诱导用于非预期操作即产生真实损失。
缓解思路：把 description 当不可信输入审查、锁定服务器版本、为每个服务器配最小权限凭证。第五章将介绍 Simon Willison 的"致命三要素"（访问私有数据、暴露于不可信内容、对外通信能力）作为系统评估框架。
四、感知工具
感知工具是 Agent 获取外部信息的主要渠道，设计重点在于粒度、组织方式、输出格式的权衡。
返回信息量控制。一次搜索可能返回数万字符，一份 PDF 上百页。通用应对是集成上下文感知压缩------输出超过阈值（如 10000 字符）时基于查询意图自动压缩。
搜索类工具的返回格式与分页。返回值应是结构化候选列表（标题、位置、摘要片段），而非全文拼接；提供分页/游标参数，注明结果总数和获取下一页方式，由 Agent 决定是否继续翻页。
读取类工具的 offset/limit 与截断 。按需读取大文件片段；必须截断时显式可见（"已显示第 1-200 行，共 5000 行，可用 offset 继续读取"）。静默截断是危险的------Agent 会误以为看到全部内容而基于不完整信息做错误判断。
只读性的工程红利。感知工具不改变外部世界，因此结果可安全缓存、多个感知调用可放心并行------执行工具没有这种自由。
多模态感知的输出形态。纯文字内容用文本提取；布局敏感内容（UI 界面、复杂表格、设计稿）保留图像交给视觉模型。
小结与预告
本章上篇聚焦工具设计的根基：五类工具的分类框架、六条通用设计原则、MCP 生态与安全风险、感知工具的设计要点。下篇我们将继续走进执行工具 （安全约束的层次化设计）、协作工具 、事件驱动的异步 Agent （从 OpenClaw 看现实需求、事件处理机制、Sidecar 安全审查），以及主动工具发现（现有方法对比、Skills 如何把发现变成"按需查阅"）。
如果说上下文工程解决了 Agent 的"思考宽度"，工具设计则决定 Agent 的"行动能力"------而工具越多、越强大，安全与选择的挑战也越尖锐。这正是本书渐次展开的核心矛盾。