一、工具与分类
一句话理解：
工具是Agent与外部环境交互的能力接口，使模型能够获取信息、执行动作、协同工作并响应事件。
模型负责判断“做什么”，工具负责把决策转化为真实世界中的观察或行动。
1.1、五类工具
| 类型 | 核心作用 | 典型能力 | 设计重点 |
|---|---|---|---|
| 感知工具 | 获取外部信息 | 搜索、网页读取、数据库查询、文件读取 | 控制信息量、来源与可信度 |
| 执行工具 | 改变外部状态 | 写文件、运行代码、发送邮件、调用业务API | 权限、确认、幂等与回滚 |
| 协作工具 | 调度其他Agent或人类 | 创建子Agent、任务委托、人工审批 | 任务边界、状态同步与责任归属 |
| 用户沟通工具 | 主动向用户专递信息 | 回复、通知、邮件、结构化卡片 | 渠道、时机、隐私与送达状态 |
| 事件触发 | 由外部事件唤醒Agent | 定时器、Webhook、告警和消息订阅 | 去重、并发、重试与事件持久化 |
1.2、调用方向
从交互方向看：
- 感知、执行、协作和用户沟通通常由Agent主动发起
- 事件触发由Agent提前注册关注条件，再由外部事件异步激活
- 工具执行结果会作为新的环境观察返回Agent，推动下一轮决策
由此形成基本闭环：
感知 → 决策 → 行动 → 环境反馈 → 再决策
1.3、各类工具的核心差异
感知工具：
重点是“看得准且不过量”，避免无关或恶意内容污染上下文。
执行工具：
重点是“做得安全且可恢复”，高风险操作必须经过权限检查和必要确认。
协作工作：
重点是“分工清晰”，只有任务可并行、需要专门能力或独立上下文时才值得委托。
用户沟通工具：
重点是“在正确的时间通过正确渠道专递正确信息”，对外发送本身属于有副作用的动作。
1.4、专业理解
这五类是一种面向工程实践的分类，并非严格互斥。例如发送邮件既可以被视为执行工具，也可以被视为用户沟通工具；定时器既包含Agent主动注册，也包含外部异步触发。
更稳定的判断方式是同时考虑两个维度：
- 方向：信息从环境进入Agent，还是动作从Agent作用于环境。
- 副作用：工具是只读观察，还是会改变外部状态。
核心结论：
感知工具决定Agent能看到什么，执行工具决定它能改变什么，协作工具决定它能调动谁，沟通工具决定它如何触达用户，事件工具决定它何时被唤醒。
二、工具设计的通用原则
一句话理解：
ACI (Agent -Computer Interface) 的目标，是把系统能力设计成Agent容易理解、正确调用且安全执行的接口。
工具不应该简单复制底层API，而应该围绕Agent要完成的目标组织能力。
2.1、能力的三种表达形式
| 形式 | 特点 | 适用场景 |
|---|---|---|
| 专用工具 | Schema明确、可验证、权限精细 | 高频、复杂参数、高风险操作 |
| 通用执行器 | 灵活、组合能力强 | 开放任务、数据处理、代码执行 |
| Skill | 自然语言流程，可按需加载和快速修改 | 领域方法、操作规范、频繁变化的流程 |
需要区分两个独立问题：
- 能力形态：一项能力做成工具、通用执行器还是Skill
- 披露策略：一次向模型展示多少项能力
2.2、选择原则
能力形态主要取决于：
- 风险与权限：高风险、不可逆操作使用专用工具
- 参数复杂度：嵌套参数和严格校验使用结构化Schema
- 变化频率：频繁变化的知识和流程适合Skill
- 任务开放度：难以预先穷举的任务适合沙箱化通用执行器
- 模型能力：能力较弱的模型更依赖明确、受限的接口
更专业的默认原则是：
使用完成任务所需的最小充分能力，而不是无条件优先通用工具。
通用执行器扩大了组合控件，也同时扩大了误操作和攻击面。
2.3、工具粒度
工具应围绕完整、内聚的用户目标设计：
- 避免把每个底层API端点都暴露成独立工具
- 合并输入、输出和使用场景高度相似的操作
- 不要把无关操作塞进一个过于复杂的万能工具
- 高频、风险不同或权限不同的操作应保持独立
判断标准：
一个工具最好对应一个清晰目标，并具有一致的权限、失败语义和副作用范围。
2.4、工具描述
工具描述应明确回答：
- 什么时候使用
- 什么时候不应使用
- 能做什么和不能做什么
- 每个参数的含义、格式和示例
- 返回值的结构
- 可能出现的错误
- 执行成本、延迟和副作用
当Agent频繁选错工具时，应优先检查工具之间是否边界重叠、描述模糊或缺少反例。
2.5、参数保真
一句话理解：
模型提交的参数、工具实际执行的参数和返回给模型的结果必须一致且可解释。
工具层不应：
静默修改字符、编码或路径
未告知模型就追加参数
自动纠正输入却不返回修正结果
隐藏实际执行的命令或请求
如果必须规范化输入，应：
- 在接口文档中明确说明
- 返回规范化后的实际参数
- 记录完整审计日志
- 允许模型验证最终状态
核心原则：
- 模型看到的世界，必须与工具实际操作的世界一致。
2.6、代码编排
通用执行器可以让模型生成代码，一次性组合多个操作：
- 中间数据保留在执行环境中
- 只将最终结构化结果返回上下文
- 减少模型与工具之间的多轮往返
- 降低Token消耗和端到端延迟
但代码编排必须运行在受限沙箱中，并设置网络、文件、时间、CPU、内存和权限边界。
核心结论：
好工具不是功能最多的工具，而是目标清晰、边界明确、参数忠实、结果可验证，并且只授予完成任务所需的最小能力。
三、工具生态：MCP与Skill Hub
一句话理解：
MCP统一工具与数据服务的连接协议，Skill Hub负责领域指令、模板和脚本的分发。
两者解决的问题不同：
- MCP解决“Agent如何连接和调用外部能力”
- Skill Hub解决“Agent如何发现、安装和复用能力包”
3.1、MCP
MCP采用客户端—服务器架构：
- MCP服务器：暴露工具、资源和提示模板
- MCP客户端：发现能力、发起调用并接收结果
- 传输层：支持本地进程或远程服务
MCP定义三类主要原语：
| 原语 | 作用 |
|---|---|
| Tools | 执行具有行为或副作用的操作 |
| Resources | 读取文件、记录等数据 |
| Prompts | 提供可复用的提示模板 |
核心价值：
使用统一协议屏蔽不同Agent框架的接口差异，使用同一能力能够被多个兼容客户端复用。
注意：
MCP只统一连接和调用方式，不保证工具设计合理、执行安全或返回结果可信。
3.2、Skill Hub
Skill通常是包含以下内容的能力包：
- SKILL.md领域指令
- 参考文档和示例
- 模板与资源文件
- 可选的执行脚本
Skill Hub本质上是能力包注册表，负责发现、安装、更新和版本管理，而不是运行时通信协议。
3.3、MCP与Skill的选择
- 需要结构化参数、稳定接口和远程服务时，适合MCP
- 需要表达流程、经验和领域方法时，适合Skill
- 高风险操作应优先使用权限受限的专用工具
- Skill可以指导Agent调用MCP工具，两者可以组合使用
简单概括：
MCP提供“可调用的能力”，Skill提供“使用能力的方法”。
3.4、上下文与Token成本
Token成本不由MCP或Skill本身决定，而主要取决于宿主的能力披露策略：
- 全量加载所有工具Schema，成本高且容易干扰工具选择
- 只常驻名称和摘要，完整定义按需加载，成本更低
- Skill通常只常驻简短元数据，正文在使用时加载
因此应区分：
能力如何接入与一次向模型展示多少能力是两个独立问题。
3.5、第三方能力风险
MCP和Skill都会引入新的供应链与信任边界。
主要风险包括：
- 工具描述或Skill指令中的提示注入
- 本地脚本或MCP服务器执行恶意代码
- 远程服务器泄露凭证和请求数据
- 工具返回结果被篡改
- 同名工具遮蔽可信工具
- 自动更新引入供应链攻击
- 过度授权导致影响范围扩大
风险大小不能简单按“MCP还是Skill”判断，而应评估：
代码来自哪里、运行在哪里、拥有什么权限、能够访问哪些数据，以及是否存在独立审批与审计。
3.6、安全原则
- 审查工具描述、Skill正文及附带脚本
- 固定版本和内容哈希，禁止未经审核的静默更新
- 使用明确命名空间避免工具遮蔽
- 为每个服务器配置独立的最小权限凭证
- 在沙箱中执行第三方本地代码
- 限制文件、网络和敏感数据访问
- 高风险调用增加人工确认
- 记录工具来源、有效参数、执行结果和版本
- 将工具描述与返回内容视为不可信输入
核心结论：
MCP降低了能力接入成本，Skill Hub降低了经验和流程的复用成本；生态越开放，越需要把版本、权限、沙箱和供应链审查作为默认基础设施。
四、工具太多怎么办：层次化组织与主动工具发现
一句话理解：
当工具数量增长时，应让Agent先看到能力索引，再按任务需要加载具体工具，避免全量工具定义占用上下文并干扰选择。
4.1、两个独立决策
- 能力形态：一项能力做成专用工具、通用执行器，还是Skill
- 披露策略：当前任务让模型看到哪些能力、看到多少细节
即使工具通过MCP接入，也不意味着必须一次展示全部Schema。
4.2、三种组织方式
| 方式 | 做法 | 适用情况 |
|---|---|---|
| 层次化索引 | 按服务或功能分组，先展示名称与简述，选中后加载详情 | 工具集较大、分类相对稳定 |
| 主动工具发现 | Agent提出能力需求，搜索工具匹配并加载候选 | 长任务、后续需求难以预知 |
| Skills按需查阅 | 常驻简短目录，使用时读取流程、脚本或参考资料 | 领域流程和可组合能力较多 |
核心流程可以概括为：
识别当前需求 → 定位能力类别 → 加载少量候选 → 选择并调用
4.3、主动发现的关键设计
- 先匹配相关服务或工具组，再匹配具体工具
- 候选描述要说明适用场景和使用边界
- 匹配不足时明确返回“未找到”，允许Agent改写需求
- 已加载的工具要在后续轮次保持可发现，避免重复搜索
- 工具发现本身也要受权限过滤，不能先暴露再检查权限
一次性按用户原始问题筛选工具，可能漏掉执行中才出现的新需求。因此，复杂任务需要允许Agent在中途再次发现工具。
4.4、上下文与缓存
按需加载减少初始Token开销，但新工具首次加载仍有成本。实现时应尽量保持稳定前缀不变，并遵循所用模型API支持的动态工具加载协议。
缓存友好的原则是保留已有前缀、追加新信息；具体如何表示和复用工具Schema，取决于API与运行时。
不能假定把任意Schema作为普通消息追加后，模型就一定能够调用该工具。
4.5、工程取舍
- 工具较少时，直接提供清晰的完整定义通常最简单
- 工具较多但任务可预测时，按任务预筛选和分组即可
- 工具众多且任务路径动态变化时，引入主动发现
- Skill适合按需提供操作方法；需要严格参数与权限控制的动作仍由工具执行
工具发现增加了检索、加载和路由环节，应同时评估任务成功率、误选率、漏选率、延迟和Token成本，不能只看上下文缩短了多少。
核心结论：
大规模工具系统的关键，是让Agent在每一步看到“当前需要的少量能力”，并在需求变化时继续发现新能力。
五、感知工具
一句话理解：
感知工具负责从外部环境获取信息，并以模型能够有效使用的形式返回。
感知工具的关键不只是“读到数据”，还要让Agent知道：数据来自哪里、是否完整、是否及时，以及如何继续查看细节。
5.1、输出设计
- 搜索先返回候选：提供标题、来源、位置和摘要，由Agent决定读取哪一项
- 大内容按需读取：支持分页、游标或offset/limit
- 截断必须显式标记：说明已返回范围、总量及继续读取的方法
- 保留来源信息：附带链接、文件位置、时间和版本，便于核查
- 按任务压缩：输出过长时提取与当前问题相关的内容，同时保留回查原文的入口
核心原则：
让模型先定位，再深入；不要把大量原始内容一次性塞入上下文，也不要静默丢弃内容。
5.2、缓存与并行
感知操作通常不修改外部状态，因此适合缓存和并行执行。但需要控制：
- 时效性：天气、股价等动态数据应设置有效期
- 权限：缓存必须区分用户、租户和授权范围
- 一致性：并行读取时，数据可能来自不同时间的快照
- 资源限制：遵守外部服务的速率与并发限制
“只读”描述的是对数据源的访问性质；下载文件等工具如果会写入本地环境，仍需管理其写入副作用。
5.3、多模态感知
面对图片、音频、视频和复杂文档，有三种主要处理方式：
| 方式 | 做法 | 适用情况 |
|---|---|---|
| 原生多模态 | 将原始内容交给支持相应模态的主模型 | 图表、界面、版式等视觉关系重要 |
| 提取为文本 | 先做文本提取、OCR或转录，再交给语言模型 | 文字是主要信息、成本敏感 |
| 工具化分析 | 调用专用多模态模型回答具体问题，返回分析结果 | 主模型不支持该模态，或仅需局部分析 |
选择依据是任务需要保留哪些信息：
纯文字重内容提取；图表、表格对应关系和界面布局重视觉保真；只需回答局部问题时，可先调用专用分析工具。
注意，OCR和多模态分析都可能出错。涉及数值、表格或关键判断时，应保留原始文件位置，支持回查。
核心结论：
好的感知工具应返回“足够作出下一步判断的信息”，并让Agent能够按需深入、核对来源和识别信息缺口。
六、执行工具
一句话理解：
执行工具将Agent的决策变成对文件、系统或外部服务的实际操作；设计重点是控制副作用，并确认操作是否真正成功。
6.1、执行前：约束与审批
- 参数校验：检查类型、格式、路径和命令参数，异常输入应明确拒绝
- 权限控制：限制可访问的文件、网络、数据和API能力
- 风险分级：根据可逆性、影响范围和财务后果决定审批方式
- 操作预览：在发送、删除、付款等关键操作前展示将要执行的内容
模型可以辅助判断风险，但权限检查和高风险操作的最终放行必须由独立的执行层控制。黑名单和第二个模型的审查都不能单独充当安全边界。
6.2、执行中：隔离与门控
- 通用代码和命令工具应限制文件、网络、进程及资源访问
- 为执行设置时间、CPU、内存和输出上限
- Sidecar可以并行评估工具调用风险，但被门控的动作必须等审查通过后才能执行
- 连续拒绝或失败时应停止重试，并交由用户或人工判断
venv只隔离软件依赖，不提供安全沙盒。隔离强度应根据输入可信度、可访问凭证和操作风险选择。
6.3、执行后：验证与反馈
工具返回“调用成功”，不等于用户目标已经完成。应尽可能检查真实结果：
- 写入文件后读取、解析或运行测试
- 修改配置后检查服务实际状态
- 创建订单后查询订单记录
- 将错误、验证结果和可恢复建议返回Agent
这样才能形成：
执行 → 观察实际状态 → 验证 → 修正或结束
6.4、超时、取消与重试
执行工具必须说明：调用超时或取消时，副作用是否可能已经发生。
- 能支持幂等键的操作，使用唯一操作ID防止重复执行
- 状态不明时先查询服务端结果，再决定如何恢复
- 无法保证幂等的操作，不应自动盲目重试
- 对外转账、发信等操作应保留明确的操作记录与确认机制
“先查询后变更”也可能遇到并发竞态，因此不能代替服务端幂等或事务保障。
6.5、输出与审计
- 长输出返回摘要、关键错误和可读取的完整结果位置
- 截断必须显式标注，避免Agent误以为看到了全部
- 记录调用者、目标、有效参数、审批结果、执行状态和耗时
- 对敏感参数和凭证进行脱敏
核心结论：
可靠的执行工具要把“允许执行什么”“实际执行了什么”“最终发生了什么”分别说清楚。Agent可以提出和调整行动，真正的权限、执行与结果核验应由Harness和外部系统共同保证。
七、协作工具
一句话理解：
协作工具让主Agent把适合拆分的任务委托给其他Agent或人类，并负责传递上下文、跟踪状态和整合结果。
7.1、子Agent的适用场景
子Agent适合承担边界清晰、可以独立验证的子任务，例如：
- 不同专业领域需要独立的提示词、工具或知识库
- 多个互不依赖的任务可以并行处理
- 需要独立视角进行搜索、分析或审查
- 子任务会产生大量中间上下文，不宜占用主Agent窗口
拆分本身存在通信、等待和整合成本。高度耦合、规模很小或需要频繁共享状态的任务，通常由主Agent直接完成更高效。
7.2、任务交接设计
一次可靠的委托至少应说明：
- 目标：需要解决什么问题
- 边界：允许做什么，哪些事项必须上报
- 上下文：已知事实、约束、相关文件和已有结论
- 来源：区分用户指令、主Agent说明和外部工具结果
- 输出契约：返回格式、证据要求、完成标准和失败状态
来源标记有助于保持信息边界，但不能单独阻止提示注入。来自网页、文件和工具的内容仍应视为不可信数据，不能自动提升为指令。
上下文传递可以采用两种方式：
| 方式 | 优点 | 风险 |
|---|---|---|
| 最小化传递 | 成本低、隔离性好、减少无关信息 | 可能遗漏关键约束 |
| 提炼后传递 | 信息更完整，适合复杂任务 | 增加延迟，并可能在摘要中产生失真 |
无论采用哪种方式，权限都不应随上下文自动继承。子Agent只能获得完成任务所需的最小工具和权限。
7.3、协作接口
协作工具通常包含三组原语：
- 生命周期管理：创建、查询、等待和取消子Agent
- 消息传递：补充要求、回答澄清问题和汇报进展
- 能力发现：列出可用Agent、职责、权限和运行状态
这些原语可以支持同步、异步、流式和多轮协作。选择方式主要取决于任务耗时、依赖关系，以及中间结果是否有价值。
取消操作还需要明确语义：取消请求发出后，子Agent是否已经执行了外部操作、哪些结果仍需回收，不能简单假定所有副作用都已停止。
7.4、结果整合与责任边界
子Agent返回结果不等于主任务已经完成。主Agent仍需：
- 检查结果是否满足原始要求
- 比较不同结果的证据、假设和时间范围
- 处理冲突、缺失和失败
- 必要时追问或重新分配任务
- 向用户给出统一且可追溯的最终结论
子Agent应显式报告不确定性、使用的来源、未完成事项和建议的下一步。主Agent不能把多个答案简单拼接后直接交付。
7.5、人工介入
HITL适用于模型不能独立决定的价值判断、授权动作和高风险例外，例如发送重要通知、修改关键配置或处理规则冲突。
请求人工协助时，应提供：
- 待决定的问题及推荐选项
- 相关证据、风险和影响范围
- 响应期限及超时后的行为
- 批准、拒绝或修改的明确入口
超时后的默认行为应与风险匹配。对于不可逆或高影响操作，“无人响应”通常意味着暂停或拒绝，而不是自动批准。
通知本身也会产生外部副作用，因此需要控制收件人、敏感信息、发送频率和渠道权限，避免重复通知或泄露数据。
7.6、反馈闭环
人类的批准、拒绝和修改理由可以形成改进数据，但不应把单次反馈直接固化为普遍规则。应先区分：
- 可重复验证的规则，可进入知识库或Skill
- 特定用户的稳定偏好，可进入受权限控制的记忆
- 高度情境化的判断，应保留在审计轨迹中
- 经筛选和脱敏的高质量案例，才适合作为训练数据
核心结论：
有效的协作不是简单增加Agent数量，而是把任务边界、上下文交接、最小权限、状态管理和结果验收设计清楚；主Agent可以委托工作，但不能委托最终责任。
实验
实验链接
参考
参考博客
