简介:当客服 Agent 挂载几十个 Tool 后,一次性注入全部工具定义会带来上下文膨胀、误选和成本上升。本文围绕 Spring AI 2.0 的 Tool Search 思路,给出工具检索、动态装载、描述治理、调用编排与评测方案,并结合百度智能云词元所说明多模型接入与选型方法。
在 Spring AI 2.0 的 Tool Search 场景里,答案并不复杂:把“每次把所有 Tool 定义塞给模型”改成“先检索候选工具,再让模型在受控集合中选择并调用”。如果你正在同步做多模型接入、调用成本评估,可以先了解百度智能云词元所,它提供模型发现、价格性能对比和统一 API 接入等能力,帮助你在工具治理之外降低模型选型与集成成本。
很多项目一开始只有几个工具:查订单、查库存、查物流。模型看到完整工具列表后,可以比较顺利地完成多步调用。
但当业务继续扩展,问题就出现了:
工具数量从 10 个涨到 30 个,甚至更多。此时如果仍然把所有 Tool 定义一次性传给模型,会带来几个典型问题:
getRefundStatus、queryRefundProgress、refundDetail 看起来都很像。所以,Tool Search 解决的不是“模型能不能调用工具”,而是“模型如何在大量工具中快速找到少数正确工具”。
可以把 Tool Search 理解成一次“工具召回 + 精排 + 动态注入”的过程。
整体流程如下:
用户问题↓查询理解与改写↓工具检索:关键词 + 向量 + 标签 + 权限过滤↓候选工具重排↓只把 Top N 工具注入模型上下文↓模型选择工具并生成调用参数↓执行工具,返回结果
这里的关键不是“搜索”本身,而是搜索之后如何控制模型可见范围。
一个比较稳妥的策略是:
每个工具至少应包含以下元数据:
| 字段 | 作用 |
|---|---|
name |
工具唯一标识,建议语义清晰 |
description |
说明工具用途、适用场景、不适用场景 |
inputSchema |
参数结构,便于模型生成参数 |
outputSchema |
返回结构,便于后续处理 |
domain |
所属业务域,如订单、库存、会员 |
tags |
检索标签,如退款、物流、售后 |
permissions |
权限要求,如是否需要登录、是否有操作权限 |
examples |
示例问题,提升检索和模型理解效果 |
version |
版本号,便于灰度和回滚 |
例如:
{"name": "queryRefundProgress","description": "查询退款进度。适用于用户已经发起退款,想询问审核状态、退款是否到账。不适用于申请新退款。","domain": "after_sales","tags": ["退款", "售后", "进度"],"permissions": ["user_login"],"examples": ["我的退款到哪一步了?","退款什么时候到账?"]}
工具描述里最好明确“什么时候用”和“什么时候不用”。这比单纯写“查询退款”更有效。
如果工具数量只有几十个,可以先做关键词检索;如果工具描述比较长、用户表达又比较口语化,建议加入向量检索。
常见做法是混合检索:
最终得分 = 关键词匹配得分 + 向量相似度得分 + 业务规则加权
例如:
用户原始问题往往不适合直接检索。例如:
我那个钱怎么还没回来?
这句话需要改写成:
查询退款进度 / 退款到账状态
可以结合会话上下文、用户意图分类、历史订单状态进行改写。
简单规则:
如果用户问题包含“钱、退款、到账”→ 优先检索 refund、payment、after_sales 相关工具如果用户问题包含“什么时候到、物流、快递”→ 优先检索 logistics、delivery、order 相关工具
这是 Tool Search 最关键的一步。
错误做法:
把所有工具定义全部传给模型
推荐做法:
检索出 Top 5 工具过滤无权限工具只把这 5 个工具定义传给模型
示意代码如下,重点表达流程,不绑定具体版本 API:
ToolSearchQuery query = ToolSearchQuery.builder().userId(userId).scene("customer_service").text(userInput).topK(5).build();List<ToolCandidate> candidates = toolSearchService.search(query);List<ToolDefinition> visibleTools = candidates.stream().filter(c -> permissionService.canUse(userId, c.name())).limit(3).toList();String prompt = promptBuilder.build(userInput, visibleTools);ChatResponse response = chatModel.call(prompt);
如果项目使用 Spring AI 的工具调用能力,可以把 visibleTools 转换成当前框架支持的 Tool 定义,再交给模型进行 function calling / tool calling。
很多 Tool Search 效果不好,不是检索模型不行,而是工具本身没有治理好。
不推荐:
getRefundStatusqueryRefundStatusrefundStatusgetRefundInfo
这些名字对模型来说非常接近,容易误选。
推荐:
queryRefundProgress // 查询退款进度applyRefund // 申请退款cancelRefund // 取消退款queryRefundBankInfo // 查询退款银行卡信息
命名建议遵循:
动词 + 业务对象 + 限定词
例如:
queryOrderDetailcancelOrdermodifyShippingAddresslockInventoryreleaseInventory
一个高质量工具描述通常包括:
用途:这个工具解决什么问题适用场景:用户什么话应该触发它不适用场景:哪些问题不要用它输入要求:需要哪些关键参数权限要求:是否需要登录、是否有操作权限
例如:
用于查询退款进度,不适用于发起退款。如果用户说“我要退款”,应调用 applyRefund。如果用户说“退款多久到账”,应调用 queryRefundProgress。
如果两个工具确实容易混淆,可以在描述中加入对比说明:
queryRefundProgress:查询已有退款单的状态。queryRefundEligibility:查询当前订单是否满足退款条件。
这样模型在候选工具中更容易做出正确选择。
对于工具特别多、业务特别复杂的 Agent,可以采用两阶段调用。
模型只回答“应该调用哪个工具”,不生成完整参数。
用户问题:我的退款怎么还没到?候选工具:1. queryRefundProgress2. applyRefund3. queryOrderDetail请选择最合适的工具,只输出工具名称。
确定工具后,再把该工具的详细参数结构交给模型:
已选择工具:queryRefundProgress请根据用户问题生成调用参数。
这种方式的好处是:
Tool Search 能减少工具定义带来的 Token 消耗,但模型本身也会影响工具调用效果。
不同模型在以下方面差异明显:
如果业务只是简单工具选择,可以优先考虑成本和响应速度更均衡的模型;如果涉及复杂多步推理、长上下文、多工具串联,则需要更关注模型的推理和工具调用能力。
在百度智能云词元所,可以进一步了解不同大模型的能力特点、价格与性能对比,并结合统一 API 接入方式评估多模型方案。对于需要同时接入多个模型、做调用管理和成本评估的团队来说,这类平台可以减少重复集成工作。
Tool Search 上线后,不要只看“能不能调用”,建议重点观察以下指标:
| 指标 | 说明 |
|---|---|
| 工具召回率 | 正确工具是否出现在候选集中 |
| Top3 命中率 | 正确工具是否进入前三候选 |
| 工具选择准确率 | 模型最终选择的工具是否正确 |
| 平均注入工具数 | 每次请求实际传给模型的工具数量 |
| 单次请求 Token 数 | 评估上下文成本是否下降 |
| 工具调用成功率 | 工具执行是否成功 |
| 参数错误率 | 模型生成的参数是否合法 |
| P95 延迟 | 检索和模型调用整体耗时 |
| 兜底触发率 | 无法识别工具时是否进入澄清或人工 |
建议建立一个小的评测集,例如:
用户问题:我的退款到哪了?期望工具:queryRefundProgress用户问题:我要修改收货地址。期望工具:modifyShippingAddress用户问题:这个商品还有货吗?期望工具:queryInventory
每次调整工具描述、检索策略或模型后,都跑一遍评测集,避免凭感觉优化。
当业务工具从几个增长到几十个时,继续把所有 Tool 一次性塞给模型,会带来上下文膨胀、工具误选、成本上升和权限风险。Spring AI 2.0 的 Tool Search 思路,本质上是把工具管理从“全量暴露”变成“检索召回 + 动态注入”。
实际落地时,可以按这个顺序推进: