一篇把工具契约、注册过滤、结果预算、渲染机制讲透

很多人理解 AI Agent，还停留在“给模型接几个函数”这一步。真正拉开差距的，不是工具数量，而是这套工具系统有没有做到：定义清楚、注册有序、默认保守、预算可控、执行可见、扩展不乱。

最有价值的地方，不是单纯罗列 40 多个工具，而是把一个成熟 AI 编码 Agent 的“工具骨架”拆开给你看：工具到底应该长什么样，为什么默认值要保守，为什么工具不能一股脑全扔给模型，为什么输出结果必须分层限流，为什么界面一定要做成“意图—进度—结果”三阶段展示。

如果你正在做自己的 AI 编程助手、企业内知识型 Agent、自动化运维 Agent，甚至是普通业务场景里的多工具助手，这一套方法都能直接拿去用。因为它解决的是所有 Agent 都会遇到的几个老问题：工具怎么接才安全、怎么给模型看才省 token、怎么执行才不乱、怎么展示才让用户放心。

01. 为什么说工具系统才是 AI Agent 的“手和脚”

大模型最擅长的是在文本里推理，但真正的业务动作却发生在文本之外。读文件、改文件、跑命令、搜内容、调用外部服务、拉取网络信息，这些都不是模型“嘴上说说”就能完成的，必须靠工具去落地。

所以，一个成熟 Agent 的核心不是“会不会回答”，而是“能不能把意图变成真实动作，再把动作结果稳稳地喂回模型”。从这个角度看，工具系统就是连接两个世界的桥梁：

第一头连着模型的推理世界。模型会生成调用意图、参数、顺序和下一步计划。

另一头连着真实执行世界。文件系统、终端、网络、权限规则、状态变化、异常回传，全部都在这里发生。

这也是为什么这套设计不是“平铺一串工具数组”那么简单，而是一条完整流水线：定义 → 注册 → 过滤 → 调用 → 限流 → 渲染。每一步都在解决一个很具体的工程问题。

02. Tool 接口：先把“工具说明书”写清楚，模型才用得稳

成熟工具系统的第一原则，不是先写执行逻辑，而是先定义契约。因为模型本质上并不“懂”你的工具，它只能看见工具名称、描述、参数结构、结果形式和允许范围。契约不清楚，模型就会乱调用；契约够清楚，模型才能稳定地用。

工具定义拆成了几个关键部分：name、description、prompt、inputSchema、call、checkPermissions、validateInput、maxResultSizeChars，以及一组 render 方法。

这几项看起来像普通字段，实际上每一个都很关键：

name 是工具唯一标识。后面的权限规则匹配、埋点分析、传输协议、名称冲突处理，全都离不开它。

description 不是静态字符串，而是一个函数。这个设计特别聪明。因为同一个工具在不同权限模式下，应该给模型不同的提醒。比如某些命令被长期禁止，那工具描述里就可以提前告诉模型“别试这些动作”，把错误拦在调用之前。

inputSchema 决定了模型能传什么参数。这里采用基于 Zod 的 schema 思路，本质上就是：先用统一规则定义参数形状，再自动转成 JSON Schema 给模型。好处有两个，一是运行时能严格校验，二是模型拿到的参数边界也更明确。

call 才是工具真正干活的地方。但这里也不是“接个参数直接执行”那么粗糙，它还会拿到上下文、权限检查回调、父消息信息，甚至进度更新回调。也就是说，执行不是孤立动作，而是运行在整套治理框架里的。

checkPermissions 和 validateInput 分别解决两件事：这个参数合法不合法、这个动作有没有权限做。很多团队把这两件事混在一起，最后逻辑越来越乱；分开后，结构会清楚很多。

maxResultSizeChars 则是在一开始就给结果大小设边界。它不是锦上添花，而是上下文治理的第一道闸门。

最后还有一组非常容易被忽略、但体验价值极高的渲染方法：工具刚被调用怎么显示，执行中怎么显示，完成后怎么显示，权限拒绝时怎么显示，并发分组时怎么显示。你会发现，这一套设计根本不是“后端函数列表”，它从一开始就把模型、执行器、权限系统、终端界面当成一体来设计。

字段	作用	为什么重要	建议
name	唯一标识	权限、埋点、协议传输都要靠它	命名稳定、避免歧义
description	告诉模型“这工具是干嘛的”	描述越准，误调用越少	做成动态函数更好
inputSchema	定义参数结构	限制模型输入边界	用统一 schema 系统管理
call	执行真实动作	决定工具能力上限	不要绕开上下文和权限
checkPermissions	权限判断	避免危险动作越权执行	和输入校验分开
maxResultSizeChars	结果大小预算	防止上下文爆炸	每个工具单独设值
render*	终端可见性	决定用户信任感	至少做意图+结果展示

03. buildTool() 工厂函数：高手做系统，最怕的不是“限制太多”，而是“默认太松”

最值得拿去复用的设计之一，就是 buildTool() + 保守默认值。

很多团队做工具注册时，会把默认值设得很“友好”：默认可并发、默认只读、默认安全、默认可展示。这样看起来开发体验很好，但长期看风险很大。因为真正的事故，往往不是有人故意写坏，而是有人“忘了声明”。

这套设计反过来做：如果你没有明确声明，就按最危险、最保守的情况处理。

比如，一个新工具忘了写 `isConcurrencySafe`，系统不会假设它安全，而是直接认定它不能并发。忘了写 `isReadOnly`，系统也不会乐观地当成只读，而是直接按可能写入处理。

这背后其实是一种非常典型的工程哲学：失败关闭，而不是失败开放。

什么叫失败关闭？就是当系统信息不完整、开发者没有声明、运行时无法确定时，优先选择更安全的限制，而不是放行。这样做的直接收益有三个：

第一，降低“漏声明”带来的事故概率。真正的线上问题，大量都来自遗漏而不是复杂 bug。

第二，让安全属性变成显式设计。工具开发者必须主动说清楚：我是不是只读、我能不能并发、我是否可用。

第三，让整个工具生态越来越可治理。因为所有工具都被迫暴露关键属性，后面做权限系统、调度系统、执行策略时，成本会低很多。

Grep 是一个很典型的“安全型工具”：它明确声明自己是只读，而且可并发。Bash 则不是一刀切，而是根据输入内容动态判断。也就是说，系统并不是简单给工具贴标签，而是允许工具根据参数语义做更细粒度的判断。这个思路非常重要：安全属性不一定是工具级别的，它也可以是输入级别的。

真正成熟的默认值，应该先假设危险，再由工具作者主动声明安全

默认属性	保守默认值	背后逻辑
isEnabled	true	工具默认可存在，但不代表可随便执行
isConcurrencySafe	false	不能确定时，先别并发
isReadOnly	false	不能确定时，先按可能写入处理
isDestructive	false	默认非破坏性，但仍需结合权限判断
checkPermissions	allow	通用权限系统先兜底

04. 工具注册不是“全部暴露”，而是三层过滤后再给模型看

很多人做 Agent 工具接入时，习惯做一张注册表，把所有工具直接丢给模型。这种做法在工具数量少时还能凑合，但一旦工具多起来，就会立刻出现几个问题：token 开销大、模型选择困难、实验功能污染主流程、内部工具和公开工具混在一起、权限规则失去边界。

工具必须分层过滤。

第一层是启动期或编译期的条件加载。某些工具受 Feature Flag 控制，没开就根本不进入最终产物；有些工具则受环境变量控制，只在特定身份、特定场景下存在。这样做比运行时 if 判断更彻底，因为没启用的代码从源头上就不出现了。

第二层是基础工具池组装。也就是先把“理论上可能可用”的工具放进一个统一池子里，形成全量注册表。这个阶段解决的是登记问题，不是权限问题。

第三层才是运行时过滤。比如用户永久拒绝某些工具、某个模式下隐藏某些基础工具、某个工具当前环境不可用，这些都应该在真正发给模型前再过滤一遍。

经过这三层之后，才得到模型真正能看到的工具列表。

更妙的是，这套设计还考虑到了 MCP 扩展工具。最终合并时，不是简单拼接，而是先保证内置工具优先，再按名称稳定排序。为什么排序也要设计？因为排序一乱，提示缓存就容易失效；工具越多，缓存越值钱，排序越不能随意。这不是代码洁癖，这是成本控制。

这里还藏着一个非常实用的小思路：简单模式。当场景只需要核心工具时，系统只暴露最少的一组，比如读、改、执行三类基础能力。这样既能降低首轮 token 消耗，又能减少模型的决策负担。很多企业内部 Agent 其实特别适合这种模式，因为它们的任务边界本来就窄，没必要把几十个工具全部暴露。

05. 工具结果为什么必须设预算？因为“看得全”不等于“用得好”

Agent 领域有一个很常见的误区：觉得工具返回越多越好，最好把全部结果都丢给模型。乍看很合理，实际上很危险。

原因很简单：模型不是数据库，也不是日志平台。它靠上下文窗口工作，一旦一个工具输出过长，不但会挤掉后续关键信息，还会让模型在大段噪声里失去判断力。结果往往不是“更聪明”，而是“更糊涂”。

所以Claude做了两层预算控制。

第一层是单工具预算。 每个工具都有自己的 `maxResultSizeChars`。Grep 这种搜索工具上限更紧，因为搜索范围一旦放大，结果很快就会淹没上下文；Bash 稍微宽一些，因为命令输出常常带有错误堆栈、测试摘要、编译信息，模型需要适当多看一点；FileRead 则是个特殊例子，它不走普通的“过长转存”策略，而是用自己的大小规则控制，目的是避免形成循环引用。

第二层是单消息聚合预算。 这一步很多团队最容易漏。因为模型一个回合里可能会并行调用多个工具，这些结果最终会一起拼进一条消息里。单个工具都没超标，不代表总和不会爆掉。所以还必须对“这一轮全部工具结果之和”再做一次上限控制。

这套设计的本质，不是简单截断，而是做一件更聪明的事：超限时，把完整内容放到外部持久化位置，回给模型的是预览 + 线索，而不是一股脑塞满上下文。

这样做的收益特别现实：

第一，保证模型看见关键摘要，而不是被巨量细节淹没。

第二，保证工具并发时，上下文不会瞬间雪崩。

第三，给后续“需要时再追读”留下空间。也就是说，模型先判断有没有必要深挖，再决定是否读更多内容。

结果预算不是抠门，而是上下文窗口治理的生命线

控制项	典型值	作用
DEFAULT_MAX_RESULT_SIZE_CHARS	50,000 字符	默认硬顶，防止单工具失控
MAX_TOOL_RESULTS_PER_MESSAGE_CHARS	200,000 字符	防止并行工具总量爆炸
MAX_TOOL_RESULT_TOKENS	100,000 token	从 token 角度再加一道限制
MAX_TOOL_RESULT_BYTES	400,000 字节	从字节层面控制输出体积
TOOL_SUMMARY_MAX_LENGTH	50 字符	限制摘要过长

06. 三阶段渲染：为什么成熟 Agent 不会只给你一个“转圈圈”

如果说前面的设计是“让模型用得稳”，那三阶段渲染解决的就是“让用户看得懂”。

很多 AI 工具体验差，不是因为能力不够，而是因为过程完全不可见。用户只看到一句“正在处理中”，然后要么等很久，要么突然蹦出一大坨结果。中间到底在干什么，用户根本不知道。

这一章把工具展示拆成三个阶段：

第一阶段：工具被调用时立刻展示。 哪怕参数还没完全流式传完，界面也先把工具名称和已知参数显示出来。这里最关键的点是 `Partial<Input>`。也就是说，系统承认一件事实：流式参数在早期可能是不完整的，但 UI 不能因此什么都不显示。

第二阶段：执行过程有进度反馈。 像 Bash、子 Agent 这种长任务，一定要能把过程不断冒出来。标准输出、标准错误、子任务消息流，都可以成为进度的一部分。这一步本质上是在建立用户信任：我不是卡住了，我是在持续工作。

第三阶段：完成后展示结果。 这里还分精简模式和详细模式。普通状态下给摘要，避免刷屏；需要排障时再看完整输出。这说明渲染不是简单打印字符串，而是一种“按场景切换的信息展示策略”。

更进一步，如果一轮里并行跑了多个同类工具，比如好几个 Grep 搜索，还可以做分组展示。这样终端既不乱，又不会丢信息。

这一套机制看似是前端体验，实际上对 Agent 成功率也有帮助。因为用户一旦能看懂工具在干什么，就更愿意在关键时刻手动干预、授权、修正目标。可见性，不只是体验优化，也是协作效率优化。

意图先出现、过程要可见、结果再收口，才是让人放心的 Agent 交互

07. 三个代表性工具：Bash、Grep、FileRead，分别暴露三种设计哲学

真正理解一个工具系统，不能只看抽象接口，还要看具体工具怎么落地。最有代表性的，是 Bash、Grep 和 FileRead。

先说 Bash。 这是最复杂的一类工具，因为 shell 命令的语义空间几乎是无限的。你不能简单把它归类为“可并发”或“不可并发”、“只读”或“非只读”。同样是 Bash，`git status` 和 `git push`、`ls` 和 `rm -rf`，安全性质完全不同。所以它必须根据输入命令内容动态判断是否只读、是否能并发，还要考虑复合命令、管道、目录切换、文件变更追踪，以及必要时的沙箱隔离。Bash 工具之所以难，就难在它不是单一动作，而是一整片可编程空间。

再看 Grep。 这是一个典型的“天然安全搜索工具”。它的语义边界非常清楚：查找，不修改。于是它可以明确声明自己是只读且可并发。这样的工具最适合成为模型的大脑外部检索器，因为模型可以放心高频调用它，而系统也更容易调度它。

最后看 FileRead。 它最特别的地方，是结果大小策略。正常工具太长会转存并返回预览，但读文件本身就是为了拿到内容，如果读出的内容又被转成一个外部引用，模型还得再追读一次，就容易绕圈。所以它采用的是另一种思路：直接控制读出来的内容规模，而不是读完再转存。这看似只是一个小策略，实际上体现了非常重要的设计意识：同样是“结果很长”，不同工具的最佳治理方式并不相同。

所以，真正成熟的工具系统不会给所有工具套同一套模板，而是根据工具本身的语义和输入结构做差异化设计。

Bash、Grep、FileRead 三类工具，恰好覆盖复杂执行、并发搜索和内容直读三大模式

08. 工具太多怎么办？答案不是“都给模型”，而是延迟加载 + ToolSearch

当工具数量继续变多，尤其接入大量 MCP 扩展后，新的难题出现了：就算每个工具都定义得很好，光把这些 schema 全量发给模型，也会非常贵。

这时，Claude给出的办法是“延迟加载”。

核心思路很简单：

一开始，不把所有工具完整定义都送进去。

对于必须首轮直接可用的核心工具，照常完整加载。

对于大量低频或扩展型工具，只先告诉模型：有这么个工具，它大概能干什么，但先不给完整参数结构。

当模型真的需要时，再通过一个专门的检索型工具，按关键词去查这些工具的完整定义，找到合适目标后再精确调用。

这就像一个大型商场的导购系统。你没必要一进门就把每家店全部说明书都读一遍；你只需要先知道“这层大概卖什么”，等你明确要买某类东西，再去看那家店的详细介绍。

这套机制里，`searchHint` 的作用特别关键。它相当于每个工具留给搜索器的一句“能力标签”。写得好，模型更容易搜到正确工具；写得差，模型就可能搜偏。

这也是为什么真正的工具系统，不只是“把函数暴露给模型”，而是要考虑发现机制。工具越来越多时，工具发现本身就会变成独立问题。

当工具规模上来后，先给名字、再按需拉取 schema，会比全量暴露更省上下文

站在工程视角看，延迟加载至少解决了三件事：

第一，降低首轮 token 压力。模型第一次对话不必背着一大包低频工具说明。

第二，降低选择复杂度。模型面对的可见空间更小，更容易先做对方向判断。

第三，给大规模扩展留出空间。你可以持续接入新工具，而不至于让初始提示越来越臃肿。

09. 最值得普通团队抄走的 6 个工程方法

如果你要自研 Agent 工具系统，这 6 个动作几乎都能直接照搬

方法一：统一契约先行。 别让每个工具自己决定参数格式、权限方式、结果格式和展示行为。越早统一，后面越省事。

方法二：默认值一定要保守。 “忘了写”是最常见的人类错误，所以安全默认值必须兜住这种错误。

方法三：注册时就做分层过滤。 编译期砍掉不需要的代码，运行时再按用户配置和环境状态过滤。不要把所有判断堆到执行时。

方法四：结果必须限流。 不要相信“模型全都能读懂”。输出过大时，要么做预览，要么做外部持久化，要么按工具特性专门治理。

方法五：长任务必须可见。 用户愿不愿意继续信任 Agent，很大程度上取决于过程是否透明。

方法六：工具列表顺序要稳定。 这是很多团队容易忽略的小地方。顺序一变，缓存命中率、调试定位、行为复现都会受影响。

10. 如果把这套设计翻译成一句人话，它到底在做什么？

可以把它理解成一句很朴素的话：

不是让模型“碰巧能用工具”，而是让模型“长期、稳定、安全、低成本地使用很多工具”。

这里面的关键词，一个都不能少。

没有“长期”，系统只能做 demo，不能做产品。

没有“稳定”，模型一遇到边界就乱调。

没有“安全”，工具越多，风险越大。

没有“低成本”，工具规模一大，token 和缓存马上失控。

所以这套设计真正厉害的地方，不在某个单点技巧，而在它把工具系统当成一个完整工程体来看待：接口、默认值、注册、过滤、预算、渲染、扩展，全部是一环扣一环的。

11. 总结：一套成熟的 AI Agent 工具系统，核心不是多，而是稳、准、可控

读完整章后，你会发现，工具系统的真正门槛，从来不是“接了多少个工具”，而是下面这五件事有没有同时做到：

第一，工具契约足够清楚。 模型知道它能做什么、该怎么传参数、结果会是什么样。

第二，默认值足够保守。 开发者一旦漏声明，系统也不会轻易放出危险能力。

第三，注册与过滤足够严格。 工具不是谁都能看见，谁都能调。

第四，结果预算足够理性。 模型看的是关键上下文，不是无底洞日志。

第五，执行过程足够可见。 用户不是盲等，而是一直知道 Agent 在做什么。

这也是普通团队最该建立的认知：Agent 工程化的分水岭，不在模型会不会调工具，而在工具系统有没有把“安全、成本、可见性、扩展性”同时管起来。

把这一章的思路吃透，你不只是看懂了一个 AI 编码助手的工具系统，更是拿到了一套可迁移的 Agent 工程方法论。