前阵子我往一个 Agent 项目里一口气挂上了 62 个工具从文档解析、代码执行、数据库查询到定时任务、邮件发送几乎能想到的能力都注册进去了。最初几天感觉特别稳什么问题丢给它都能接住。直到有一次让它处理一个稍微绕一点的跨模块任务日志里反复出现agent execution terminated due to error.我盯着报错看了半天第一反应是模型能力问题。但翻到会话回溯才发现模型根本没崩它是在六十个工具面前挑花了眼——每一步都在纠结用哪个工具最后在某条分歧路径上硬选了一个明显不该选的东西参数还不合法整轮执行直接终止。这篇文章不是讲某个框架的用法而是想复盘一个很现实的问题当工具数量冲到六十这个量级时真正决定 Agent 能不能稳定工作的已经不是模型有多聪明而是你如何处理工具的分层、路由和定义。如果你也在做 Agent 开发正经历“工具越挂越多效果反而越来越差”的阶段下面的内容应该能帮你省掉不少调试时间。1. 六十个工具同时摆上台面Agent 的大脑先过载了三成先说结论工具数量对 Agent 决策质量的影响不是线性增长而是指数恶化。你把 60 个 function schema 一次性塞进上下文之后模型在做任何一次工具选择时都要先扫描这 60 个候选再逐个比对语义。这个过程的 token 开销还不是最要命的最要命的是决策空间变得太大工具之间的细微差异被注意力机制摊薄了。我之前那个项目出问题不是偶然一次选错而是出现了三类典型症状第一类叫“决策游离”。模型在思考链里反复列举候选工具写了一大段“这个工具好像能做那个工具也能做”的分析然后还是选了一个匹配度很低的。我去看 token 统计发现光是工具选择前的思考 tokens 就占掉了整轮调用的四成延迟从两三秒涨到十几秒多轮之后上下文被这些废话塞满后续指令都开始飘。第二类叫“相似工具互相干扰”。当工具列表里同时存在“获取用户订单”“查询订单状态”“拉取订单列表”这类功能高度重叠的条目时模型很容易把当前任务映射到错误的那个。说白了这种场景就像你走进便利店想买一瓶酱油结果货架上五排全是同品牌的不同规格你站在那儿好久都不确定该拿哪瓶。第三类叫“静默失败”。最隐蔽的一类是选错工具还不报错而是出现参数结构不匹配比如某个工具要求date字段传 ISO 格式模型给传了一个自然语言日期然后框架在参数校验阶段直接抛异常终止。热搜里那句agent execution terminated due to error.有很多次并不是模型崩溃而是选错工具加参数非法导致的连锁反应日志里只有一句笼统的失败提示原因被吞掉了。这些问题本质上不是“大模型不够聪明”而是你把工具数量直接压给了本应先做路由判断的入口。模型面对 60 个选项时注意力资源是有限的工具定义里的微小歧义会被选择压力无限放大。换句话说你不给 Agent 做减法它就一定会给你上演选择困难。2. 先别急着换模型问题多半出在三个病根上遇到工具选错很多人的第一反应是换个更强的大模型。我实测下来这条路只在少数场景有效大多数情况下问题压根不在模型能力而在工程结构。我从那次事故里拆出了三个互相独立的病根。2.1 信号过载选项越多决策质量反而越差60 个工具的 JSON Schema 拼进请求后模型需要先在很长的一段上下文里“找到”合适的目标再去匹配描述。候选越多不同工具在语义空间里的距离越接近的概率就越高。比如“删除订单”和“作废订单”在自然语言里几乎是一对同义词但在业务系统里可能分别对应两条完全不同的审批流。模型如果没有足够强的业务背景提示很容易挑到那个语义上接近但流程上错误的工具。有人会想那把 temperature 调低一点让模型没那么“发散”不就行了实际情况是工具选择更像一个隐式的“第一候选采样”过程降低 temperature 只是让模型在已有候选里更坚定地选一个它并不会让模型正确区分两个语义相近但业务不同的工具。打个比方你在两个长相差不多的嫌疑犯里指认凶手把灯调暗一点并不会提高指认准确率。2.2 目标模糊没有先问“这一步到底要干什么”Agent 就只会平铺搜索很多 Agent 实现只有一层拿到用户请求直接丢给大模型让大模型自己从所有工具里挑。这种设计最大的问题是没有任务意图分级。用户说一句“帮我把今天的销售报表生成好再发给销售总监”这里其实有两个完全不同的动作从数据仓库拉取销售数据并渲染成报表然后向指定联系人发送邮件。一个合格的 Agent 应该先识别出这是多步任务把大目标拆成子目标再为每个子目标选择对应工具。但如果少了意图拆解层模型大概率会试图找一个“生成并发送报表”的一体化工具找不到就开始瞎凑。这个问题在工具多的项目里尤其严重。工具越多模型越难从“整个工具全集”中判断当前子目标到底应该匹配哪一个。有效的做法是在 Agent 与工具之间增加一个规划层先让模型回答“这一步想得到什么结果”再基于结果去匹配工具而不是让它拿着用户的原始请求直接平铺搜索所有工具。这一步能显著减少工具选择的随机性。2.3 归因错误工具自身的命名和描述把模型带偏了我后来复盘那次走向终止的执行链发现一个非常尴尬的事实模型选错的工具它的 description 本身就写得稀烂。工具名叫search_data描述写的是“根据关键词查数据库里的相关内容”。这句话对模型来说完全无法判断它和search_order、search_customer之间是什么关系更不知道应该传什么参数。模型只能硬猜猜错就成了必然。工具定义本身是人与模型之间的接口协议写得不清晰模型再有推理能力也白搭。这个问题不做工程层面的修正换什么模型来都解决不了。3. 我把六十个工具拆成了三层漏斗每个 Agent 眼前只摆二十个病根找到了接下来就是对症下药。我的方案不是让模型一次性面对全部工具而是把工具集拆成三层漏斗让 Agent 在每个决策节点只看它当前真正需要的那一小撮。3.1 先给工具做体检别上来就删动手拆层之前我先给工具全集做了一次“体检”。方法是拉最近 30 天的调用日志统计每个工具的使用率、错误率和功能重叠度。使用率极低且能力可以被其他工具覆盖的直接合并或者下线。这一步能砍掉大约两成冗余工具别心疼留着只会增加选择噪声。然后按照“任务语义”重新分组而不是按技术层分组。很多人习惯按工具类型分比如数据库工具、文件工具、API 工具这种分组对模型没有任何帮助因为模型不关心底层实现。它关心的是“哪些工具服务于同一类用户意图”。所以我把工具重新按业务域划分所有围绕订单操作的工具归进订单包所有围绕用户画像操作的归进用户包所有运维类操作归进运维包。这样的分组在路由时才有意义。3.2 三层漏斗的设计体检和分组做完之后我再把工具全集拆成三个层级分别叫 Core Set、Scene Set 和 Library Set。Core Set 是常驻工具集大约 8 到 12 个。这些是几乎所有类型任务都绕不开的基础能力比如文本搜索、内容读取、代码执行、上下文总结、结果存储。任何一轮会话开始Agent 的 tools 参数里只需要加载 Core Set。Scene Set 是场景工具包大约 20 个。这部分工具按任务场景预打包比如文档编辑场景加载文件读写、格式转换、内容对比数据分析场景加载表格读取、统计计算、图表生成。当意图路由判断出当前任务属于某个场景后再把对应的 Scene Set 注入到模型上下文。Library Set 是边缘工具库剩下那些低频但又不能删的工具全部放到这里。它们平时不参与常规决策只有当 Core Set 和 Scene Set 里都找不到合适候选时才通过描述向量检索召回最相关的几个以“新增工具”的形式临时加入当前轮次。这套结构跑下来的效果很明显模型每轮真正面对的候选工具数从 60 骤降到 20 以内多数情况下甚至不到 10 个。我之前那套“选择困难症”基本消失了。3.3 用路由加检索把“60 选 1”降成“20 选 1 再 4 选 1”实现三层漏斗的关键是在模型前面加一道意图路由和一道检索闸门。第一道闸门判断任务属于哪个场景决定加载哪个 Scene Set第二道闸门处理“当前提供的工具里没有完全匹配的候选”的情况进入描述检索召回。这样选择过程就从“60 选 1”变成了“20 选 1 再 4 选 1”每一步的决策难度都低了很多。检索闸门的打分逻辑不需要做得很重纯规则就能跑得很好。一个简化示例是对候选工具做名称精确匹配加分、描述关键词匹配加分、最近 N 轮使用频率加权综合得分取前三名作为候选返回。下面这个伪代码基本能说明我的思路def retrieve_candidate_tools(query, scene_tools, top_k4): scored [] for tool in scene_tools: score 0.0 if tool.name query: # 名称精确命中 score 0.4 score overlap(tool.description, query) * 0.3 # 描述相似度 score usage_weight(tool.name) # 近期使用频率越常被用权重越高 scored.append((tool, score)) return [t for t, s in sorted(scored, keylambda x: -x[1])[:top_k]]这里唯一的注意点是usage_weight千万不要把频率设得过高否则会让 Agent 产生路径依赖每次都选那几个高频但并不能解决当前问题的工具。我的经验是频率权重最多占 20%剩下 80% 还是要看语义匹配。提示检索召回不等同于最终选择。召回的候选只是让模型有得挑你仍然要把“检索结果”和“当前任务描述”一起交给模型做最终决策。否则检索逻辑就变成了取代大模型判断的单点出错的时候更难看。4. 工具定义才是头号元凶把 description 写成“人话给模型听”三层漏斗解决的是“候选太多”的问题但就算只剩 5 个工具如果工具定义写得含糊模型照样会选错。这一节我想重点聊聊工具本身应该怎么定义。4.1 名字怎么起动词加对象拒绝花哨缩写工具命名虽然不像变量名那样影响程序运行但它直接影响模型对工具的第一印象要起得直白。最佳格式是“动词 业务对象”比如search_user、create_invoice、delete_message。尽量避免process_data_ex_v2、handle_thing这类抽象命名模型看到这种名字只能靠猜。如果有历史包袱已经注册了一堆旧名字建议在新版本里直接改名模型 Agent 执行时锁定版本就行。4.2 description 的第一句话要直接说“这个工具能干什么”我发现很多人写工具描述喜欢绕弯子先写一堆背景和前置条件再写功能。模型读的时候需要先在这个描述里筛出有效信息。正确写法是第一句话就写清楚工具的职责边界和最终结果然后写输入输出要求再写边界和失败场景。举个例子同一个工具两种写法效果完全不同写法description模型理解效果模糊写法“这是一个数据查询接口可以传入多个参数根据条件返回相关记录返回结果是列表形式。”工具到底查什么数据参数结构是什么和别的查询工具有什么区别全都不明确。清晰写法“按用户 ID 精确查询用户基本信息返回邮箱、手机号、注册时间。仅支持传入单个 user_id不支持模糊搜索用户不存在时返回空列表不会抛异常。”模型能明确判断出该在什么时候用知道传什么参数也知道了失败时会出现什么结果。写描述时还有一个额外的好处清晰的失败说明能帮模型在返回结果异常时做后续判断而不是把空列表当成正常数据继续执行导致更隐蔽的连锁错误。4.3 参数约束写死别给模型自由发挥工具参数定义是选错工具之后的第二次风险点即使工具选对了参数也可能传错。我处理这类问题的方式是在 JSON Schema 里把可以写死的约束全部写死。能设枚举就设枚举能限定格式就限定格式能加正则就加正则。我踩过一个经典坑工具要求date参数但我没写format模型在一次任务中传了“2025 年 1 月 1 日”另一种场景传了“01/01/2025”第三种场景传了标准时间戳。三种格式在自然语言里都对但在 API 里只有一种能被解析。后来我把format: string和pattern写进 schema模型基本不会再自由发挥了。4.4 在 system prompt 里写 Agent 的工具选取策略工具定义本身是静态信息但你还可以通过 system prompt 给模型一套工具选取的规则。我目前一直在用的策略有三条优先使用当前会话已经提供的工具不要自行联想不存在的工具名。在同类工具中选择名称与当前任务动词匹配度最高的那个。不确定该用哪个工具时主动向用户澄清不要硬选。这三条规则并不过分占用上下文但对减少乱选、胡编工具名的效果非常明显。它们的本质是给模型安装一个“选择护栏”让它在决策边界上不至于彻底失控。5. 看见“execution terminated due to error”我是这样从头到尾反推的如果你已经上线了工具数量较多的 Agent排查选择类问题的链路其实很固定。我把之前那次事故的完整回溯过程写下来你可以直接照着走。5.1 第一步还原预选候选列表任何一次工具选择只要你没有禁日志框架都会记录当时模型看到的候选工具列表。先去日志里把出错那一轮的 tools 参数拉出来看看当时候选工具都有哪些。我那次排查时发现预筛机制直接把正确工具过滤掉了候选列表里只剩几个名字相似但业务不同的工具模型基本上是被“逼着”在错误候选里选择。如果你在日志里发现正确工具根本没出现在候选里那就不用再去怀疑模型问题一定出在路由或检索层。5.2 第二步对比模型最终选择与候选打分如果正确工具确实在候选中但模型选择了另一个这时候需要看模型是否在决策时产生过偏移。检查模型输出的思考过程里是否提到了两个工具之间的犹豫如果它犹豫过说明描述里的语义区分度不够需要回到工具定义去补充“什么时候不适合用”这段描述。如果它没有犹豫直接选了一个错误工具那可能是 system prompt 里的工具选取策略没有生效建议检查是否被后续指令覆盖。5.3 第三步检查参数校验阶段是否根本没生效工具选对但参数非法导致的终止是最冤的一种情况。排查方式是看报错堆栈里有没有明确指向 JSON Schema 校验如果校验逻辑压根没有被触发说明框架配置里把参数校验关了或者模型输出结果在进入工具函数前就被错误转换了。这种情况下即使你修复了工具选择问题同样的错误还会在下次出现。日志现象可能原因检查点execution terminated due to error上下文有大量决策分析候选工具过多模型注意力被摊薄确认当前轮 tools 参数里是否只有 Core Set/Scene Set正确工具不在候选列表中分组路由将任务导向了错误场景核对意图路由的场景判定结果正确工具在候选中但模型选了相似名称工具description 语义区分度不足补充边界条件和“不适合用”场景工具选择正确但参数格式错误参数 schema 约束过弱或校验未启用检查 JSON Schema 里的 enum/format/pattern工具返回结果为空但下游继续执行描述里没有写失败返回值语义完善描述中的失败行为说明排查这类问题最忌讳的是只看最后一行报错。Agent 的错误往往是多环节堆积出来的不是某个单点突然坏掉从候选列表一路查到参数校验基本能把根因挖出来。6. 选对工具只是开始上下文占用和多 Agent 协作才是真正的深水区工具选择问题处理完之后我以为 Agent 就能稳定跑了但紧接着又撞上两堵新的墙。这里也一并分享出来。6.1 工具调用轨迹会迅速撑爆上下文把“选择过程”压缩掉六十个工具频繁调用时每一轮函数返回都塞进上下文多轮之后那段历史记录会变得非常恐怖。系统提示词、工具定义、历史对话、函数返回四块内容互相挤占空间最后模型连当前任务都快看不到了。我的处理方式是给工具返回做截断和摘要大段返回内容只保留前 200 个字符外加一个“已截断”标记同时把已经执行成功的工具链压缩成一行摘要比如“已调用 search_user → create_invoice → send_email”不再保留中间完整参数和返回值。这样既保留执行轨迹又避免上下文被撑爆。6.2 多 Agent 协作时每个 Agent 只暴露自己的工具面工具多了以后另一个好用的实践是别让所有工具都堆在一个 Agent 里。把不同职责拆给多个子 Agent每个子 Agent 只拥有自己工具集中的一小部分并通过一个协调者决定任务该交给谁。这样做的好处是单个 Agent 的 tools 参数永远很小决策压力天然被分摊。那些支持多 Agent 协作的框架大部分也都在走这条路线核心思想是分工明确、各自治小而不是把所有能力都塞给一个单体 Agent。6.3 什么时候别上更重的编排框架最后给一个反直觉的建议如果你的工具总量只有二三十个任务模式也比较固定那完全不需要引入复杂的编排框架直接在模型 API 层做简单路由就足够了。为一个小体量项目套上重型编排框架只会多一层需要维护的抽象排查问题反而更费劲。我见过太多团队为了“跟上技术潮流”强行上重型框架结果 Agent 本身没变聪明光框架自身的配置和版本兼容问题就耗掉了大半精力。工具多到结构性问题浮现时再去考虑更复杂的编排方案那时它才真正有用。回头看我那个挂了 62 个工具的项目最后稳定下来靠的不是模型升级而是把工具藏起来了一大半。让 Agent 只看到眼前该用的那部分比让它看完全部再靠推理去选要可靠得多。我个人现在的原则是每次添加新工具之前先问自己它能不能被现有工具覆盖每次看到工具数量涨到四十以上我就知道又该做一次分层整理了。工具不是越多越好把工具交给“够用的视野”Agent 才能真正干出活来。