一、工具与分类一句话理解工具是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、MCPMCP采用客户端—服务器架构MCP服务器暴露工具、资源和提示模板MCP客户端发现能力、发起调用并接收结果传输层支持本地进程或远程服务MCP定义三类主要原语原语作用Tools执行具有行为或副作用的操作Resources读取文件、记录等数据Prompts提供可复用的提示模板核心价值使用统一协议屏蔽不同Agent框架的接口差异使用同一能力能够被多个兼容客户端复用。注意MCP只统一连接和调用方式不保证工具设计合理、执行安全或返回结果可信。3.2、Skill HubSkill通常是包含以下内容的能力包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可以委托工作但不能委托最终责任。实验实验链接参考参考博客
