@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；
  • 选择准确率；
  • 延迟；
  • 发现失败率；
  • 额外轮次。

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

高风险工具包括：

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

推荐：

独立服务或MCP Server
＋专用网关
＋细粒度OAuth Scope
＋用户确认
＋幂等
＋审计

不要把高风险逻辑直接写成一个无保护的本地@Tool。

模型只能生成“执行建议”，最终决策由业务策略层完成。

十五、工具版本如何管理

工具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/

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