@Tool、ToolCallback、MCP工具和ToolSearchToolCallingAdvisor怎么选？Spring AI工具架构指南

原创 20天前 1652

@Tool、ToolCallback、MCP工具和ToolSearchToolCallingAdvisor怎么选？Spring AI工具架构指南

文章摘要

Spring AI 2.0提供多种工具接入方式：@Tool适合本地Java方法快速暴露；ToolCallback适合动态注册、明确Schema和基础设施封装；MCP工具适合跨语言、跨服务和独立团队共享；ToolSearchToolCallingAdvisor则解决几十到数百个工具全部注入Prompt造成的Token浪费和选择准确率下降。本文从部署边界、权限、版本、性能、工具数量和团队协作等方面，给出企业项目的分层选型方法。

一、四种能力解决的问题不同

@Tool
→ 如何快速把Java方法变成工具

ToolCallback
→ 如何以编程方式定义和管理工具

MCP工具
→ 如何跨进程、跨语言、跨团队共享工具

ToolSearchToolCallingAdvisor
→ 工具太多时如何按需发现

它们不是简单互相替代。

一个企业Agent可以同时使用：

本地@Tool
＋远程MCP工具
＋ToolSearch按需检索

二、@Tool适合什么场景

示例：

public class InventoryTools {

    @Tool(
        description = "根据商品编码查询当前可用库存"
    )
    public InventoryResult queryInventory(
            @ToolParam(
                description = "企业内部商品编码"
            )
            String sku
    ) {
        return inventoryService.query(sku);
    }
}

优点：

上手快；
Java类型自动生成Schema；
与Spring服务调用自然；
本地方法延迟低；
适合少量稳定工具；
易于单元测试。

适合：

同一个Spring Boot应用；
工具与业务服务紧密耦合；
工具数量较少；
不需要跨语言；
同一团队维护。

不适合：

多个应用都要复用；
工具需要独立扩缩容；
不同语言客户端；
需要独立发布版本；
高风险工具需要专门网关。

三、ToolCallback适合什么场景

编程式定义：

@Bean
ToolCallback queryInventoryTool(
        InventoryService inventoryService
) {
    return FunctionToolCallback
            .builder(
                    "query_inventory",
                    inventoryService::query
            )
            .description(
                    "根据SKU查询实时库存"
            )
            .inputType(
                    InventoryRequest.class
            )
            .build();
}

ToolCallback适合：

动态创建工具；
从配置中心加载；
封装第三方API；
统一增加重试与指标；
明确工具名称和Schema；
按租户选择工具；
将工具放进注册表。

例如：

public interface EnterpriseToolRegistry {

    List getTools(
            String tenantId,
            String userId,
            String scenario
    );
}

调用前根据权限返回工具集合。

四、为什么Spring AI 2.0更强调显式ToolCallback

旧版可以依赖：

Spring Bean名称
＋toolNames()

隐式找到函数。

这种方式存在：

名称重构后运行时才失败；
不清楚哪些Bean会暴露给模型；
权限边界模糊；
工具Schema难以统一治理；
多租户选择困难。

Spring AI 2.0改为显式传递：

.tools(queryInventoryTool)

让工具暴露成为清晰的安全决策。

五、MCP工具适合什么场景

MCP Server把工具作为独立服务暴露。

架构：

Spring AI应用
→ MCP Client
→ MCP Server
→ 企业系统

适合：

跨语言；
多个Agent复用；
独立团队维护；
工具独立扩缩容；
SaaS连接器；
数据平台；
浏览器、文件、数据库等通用能力；
企业统一工具市场。

例如：

Java客服Agent
Python研究Agent
Node.js办公Agent

都可以调用同一个订单MCP Server。

六、MCP的代价

网络延迟；
远程鉴权；
协议版本兼容；
服务发现；
超时和熔断；
网关配置；
工具列表缓存；
独立运维；
数据跨边界；
供应链风险。

如果工具只被一个Spring Boot应用使用，把它拆成MCP Server可能是过度设计。

七、MCP 2026-07-28正式版带来的影响

新规范无状态化后，MCP Server更容易：

普通负载均衡
＋水平扩展
＋无Sticky Session

Mcp-Method和Mcp-Name让网关可以按工具方法和名称路由。

工具平台可以形成：

MCP Gateway
→ 低风险查询集群
→ 高风险交易集群
→ 文件处理集群
→ 长任务集群

但业务状态仍需外置。

八、工具数量少时，不需要ToolSearch

如果只有：

5—15个工具

直接传给模型通常最简单。

标准ToolCallingAdvisor会把工具定义注入模型上下文，模型根据描述选择。

优点：

行为直接；
调试简单；
没有工具搜索误差；
调用步骤更少。

九、工具数量多时为什么会出问题

假设有100个工具，每个Schema平均500 Token：

100 × 500
= 50000 Token

每次请求都发送工具定义，会造成：

输入成本上升；
首次响应变慢；
模型选择准确率下降；
相似工具互相干扰；
上下文留给业务数据的空间减少。

这时适合：

ToolSearchToolCallingAdvisor

十、ToolSearchToolCallingAdvisor如何工作

传统方式：

全部工具Schema
→ 一次性发送给模型

ToolSearch方式：

先只暴露工具搜索能力
→ 模型描述需要什么工具
→ 从工具索引找相关工具
→ 只注入少量工具
→ 再执行调用

可以使用：

Regex；
Lucene；
Vector；

三种索引策略。

配置：

spring.ai.chat.client.tool-search-advisor.enabled=true
spring.ai.chat.client.tool-search-advisor.tool-index-type=vector

向量模式需要VectorStore。

十一、ToolSearch为什么需要Session ID

工具索引与发现结果按会话隔离。

请求应传：

.advisors(spec -> spec.param(
        ChatMemory.CONVERSATION_ID,
        conversationId
))

多租户项目不能复用同一个Session ID，否则可能出现：

工具集合串用；
发现结果污染；
权限泄露；
会话A使用会话B已发现的工具。

十二、四种方案对比

维度	@Tool	ToolCallback	MCP工具	ToolSearch
部署位置	本地	本地或适配层	远程服务	工具发现层
上手成本	低	中	高	中
跨语言	否	否	是	取决于底层工具
网络开销	无	通常无	有	增加一次发现
动态工具	一般	强	强	强
独立版本	弱	中	强	不负责版本
工具数量	少量	少到中量	中到大量	大量
权限治理	应用内	可集中封装	服务与网关	必须按会话隔离
团队复用	弱	中	强	强化大工具集

十三、如何按业务边界选择

同一进程的领域能力

@Tool

例如：

查询当前用户信息；
读取本地配置；
调用同进程Service。

需要统一封装的本地工具

ToolCallback

例如：

动态REST API工具；
配置化工具；
按租户注册；
加统一审计。

跨服务和跨语言共享

MCP

例如：

企业订单平台；
数据平台；
Git仓库；
文档服务；
浏览器自动化。

工具超过30个

评估ToolSearch

不要只按数字决定，还应测试：

Token；
选择准确率；
延迟；
发现失败率；
额外轮次。

十四、高风险工具应该放在哪里

高风险工具包括：

付款；
退款；
删除；
权限修改；
发布；
合同发送；
数据导出。

十五、工具版本如何管理

工具Schema变化可能导致旧客户端或Prompt失效。

建议记录：

tool_name
tool_version
input_schema_version
output_schema_version
owner
risk_level
deprecated_at

兼容升级：

create_order_v1
create_order_v2

或保持工具名不变，通过兼容Schema演进。

MCP正式版的功能生命周期规则也可以作为工具治理参考：

Active
→ Deprecated
→ Removed

十六、一个推荐的企业架构

Spring AI ChatClient
→ ToolCallingAdvisor
→ EnterpriseToolRegistry
├─ 本地@Tool
├─ ToolCallback适配器
└─ MCP ToolCallbackProvider
        ↓
  Tool Policy Engine
        ↓
  参数校验、权限、审批、幂等、审计

工具搜索层位于工具注册表与模型之间，只负责发现，不负责授权。

十七、不要让模型决定工具权限

错误做法：

把所有工具给模型
→ 在Prompt中告诉它不要乱用

正确做法：

认证用户
→ 计算允许工具集合
→ 只把允许工具交给模型

工具是否可见本身就是权限控制的一部分。

十八、选型决策树

是否只在一个Java应用内使用？
→ 是：@Tool或ToolCallback

是否需要动态注册和统一封装？
→ 是：ToolCallback

是否跨语言、跨服务、跨团队？
→ 是：MCP

可用工具是否很多？
→ 是：ToolSearchToolCallingAdvisor

是否高风险动作？
→ 独立策略、审批和审计，不论使用哪种工具形式

总结

四种能力的分工可以概括为：

@Tool
→ 最快暴露本地方法

ToolCallback
→ 最灵活定义和治理工具

MCP
→ 最适合跨边界共享工具

ToolSearch
→ 最适合大规模工具按需发现

企业项目通常不是四选一，而是根据部署边界和风险组合使用。

延伸阅读

如果你正在关注企业级 AI 应用、Spring AI、RAG、Agent 与 MCP 工程化落地，欢迎访问 智元界：

https://www.zyentor.com/

智元界将持续分享可运行的技术实战、架构设计、问题排查与企业应用案例。

深夜开源工作台 2026/07/19 12:52:05

合规粒度这块确实关键，全量记录推理轨迹成本太高，建议先聚焦用户数据相关的交互。

阿南Data手记 2026/07/18 14:02:24

同感，合规粒度这块确实最让人头疼。我也在负责agent的落地，刚看到“完整推理轨迹”这几个字的时候，第一反应是成本会不会直接爆炸。我们之前试过给每个决策节点加日志，结果单次交互的存储量翻了好几倍，如果是高频场景，光存这些元数据就得比业务数据还多。我觉得文件里“自主决策边界”这个提法挺高明，但落到实践上，边界到底画在哪儿？比如一个agent调用了外部API，那调用前后的状态变化算不算决策轨迹的一部分？如果算，那很多隐式逻辑（比如大模型内部对prompt的拆解）根本没法显式记录。我们现在在尝试折中方案：只记录与用户数据直接相关的决策分支，以及触发规则约束层跳转时的上下文，其他中间推理过程用hash摘要存下来，既满足审计要求，又不太占空间。不过这个方案还没经过正式审核，不知道合规上能不能被接受。另外，关于“可解释性”这块，我们团队发现一个现实问题：就算你能把推理链条完整输出，非技术背景的审核人员也未必看得懂，最终可能还是需要业务层再封装一层自然语言摘要，这又多了个工程模块。总之，新规是个好事，但执行细节上的讨论空间太大了，特别期待后续能出个实践指南或者范例。

云端河狸守护服务器 2026/07/17 23:08:24

读到这个帖子特别有共鸣，作为也在搞agent落地的同行，新规出来那几天我们团队内部就吵了好几轮。你提到“黑盒路径走不通”这点太真实了，我们之前有个项目就是让大模型直接输出动作，结果上线后用户投诉说agent莫名其妙拒绝了一个合理请求，查日志根本看不出决策链路，现在回头想真是后怕。关于合规粒度那个疑问我也一直在纠结，理论上全量记录推理轨迹最安全，但agent跑一次任务可能调用几十次模型，存下来存储开销直接翻倍，更别提检索和审计的成本。我个人的折中方案是只对涉及用户隐私数据或资金操作的交互做完整日志，其他场景用摘要式记录，起码先保证关键环节可追溯。另外想补充一点，新规要求“数据溯源机制”其实倒逼我们把数据血缘工具链搭起来，这对后续排查训练数据污染问题反而是好事。不过有个现实困扰：小团队哪有资源自研审计系统？不知道有没有开源方案能直接适配agent框架的。

@Tool、ToolCallback、MCP工具和ToolSearchToolCallingAdvisor怎么选？Spring AI工具架构指南

@Tool、ToolCallback、MCP工具和ToolSearchToolCallingAdvisor怎么选？Spring AI工具架构指南

文章摘要

一、四种能力解决的问题不同

二、@Tool适合什么场景

三、ToolCallback适合什么场景

四、为什么Spring AI 2.0更强调显式ToolCallback

五、MCP工具适合什么场景

六、MCP的代价

七、MCP 2026-07-28正式版带来的影响

八、工具数量少时，不需要ToolSearch

九、工具数量多时为什么会出问题

十、ToolSearchToolCallingAdvisor如何工作

十一、ToolSearch为什么需要Session ID

十二、四种方案对比

十三、如何按业务边界选择

同一进程的领域能力

需要统一封装的本地工具

跨服务和跨语言共享

工具超过30个

十四、高风险工具应该放在哪里

十五、工具版本如何管理

十六、一个推荐的企业架构

十七、不要让模型决定工具权限

十八、选型决策树

总结

延伸阅读

评论 3

📖 关联推荐

精选推荐