你的 AI 应用想让大模型一次调用"查库存 + 算价格 + 下订单"三个函数，却发现工具多了就乱套、报错无从下手、上下文越塞越糊。本文用 Spring AI 2.0 的可组合 Tool Calling 架构，解决多工具场景下的编排混乱、结果冲突和自反馈缺失问题。带你从手写 @Tool 注解，到把多个工具组合成带自反馈循环的 Agentic 管道，全程可运行代码，省掉你摸索文档的时间。

一、这个问题到底是什么

在很多 AI 工程场景里，单工具调用已经不能满足需求了。你让大模型"帮我订一张明天上海到北京的机票，预算 1200 以内"，它需要同时调用机票查询工具、价格比对工具、座位查询工具，甚至还要按你的偏好二次校验。如果把这些逻辑揉在一个大函数里，代码丑陋且没法复用；如果分成多个工具，又面临编排混乱、结果冲突的问题。

Spring AI 2.0 把 Tool Calling 从"一个模型调一个函数"升级成了可组合的 Agentic 架构。它允许你把多个工具声明成 Bean，让大模型自主决定调用顺序和参数，还能通过回调把上一次的工具结果喂回给模型，形成自反馈循环。这就是智能体（Agent）能力的底座。

很多同学卡在三个痛点：一是不知道工具怎么声明才稳定，@Tool 注解写错了要么不生效要么参数错乱；二是多个工具返回结果冲突时没人仲裁，模型不知道该信哪个；三是工具调用失败后没有恢复机制，一次报错整个会话就崩了。本文逐个击破这三个痛点。

这篇文章面向已经会用 Spring AI 接大模型、需要把应用做成多工具智能体的 Java 后端开发。写作日期为 2026 年 8 月 9 日，基于 Spring Boot 4.1.0 + Spring AI 2.0.0。

二、底层原理到底怎么回事

要理解 Spring AI 2.0 的组合式 Tool Calling，得先搞清楚它背后那套"可组合"的机制。核心是三个概念层：Tool 描述层、调用执行层、回传循环层。

第一层：Tool 描述层。 每个工具都要向大模型暴露"我能干什么、我的参数长什么样"。Spring AI 2.0 里，一个带 @Tool 注解的 Bean 方法会被自动扫描，通过反射读取方法签名和 Javadoc 首行描述，生成符合 OpenAI Function Calling 格式的 JSON Schema。大模型读到这份描述，才知道"这个函数接收 Integer 参数、返回值是字符串"。这个描述越清晰，模型选对工具的概率越高。

第二层：调用执行层。 当大模型在响应里返回 tool_calls 结构时，Spring AI 的 ChatClient 通过 ToolCallingManager 把请求路由到对应的工具方法。这里的关键是参数绑定：模型返回的参数是 JSON 字符串，Spring AI 用类型转换器把它反序列化成方法的强类型参数。如果模型给的参数类型不对（比如应该传 String 却传了数字），绑定就会失败，这也是最常见的报错来源。

第三层：回传循环层。 这是组合式架构的灵魂。普通的一次调用是"发请求 → 拿结果"就结束了。但在 Agentic 场景里，工具执行结果需要作为新的上下文再次喂给模型，让模型决定下一步。Spring AI 2.0 提供了一个统一的 ChatResponse 流处理方式，你可以监听每个 ToolCall 事件，把工具输出塞回对话历史，循环往复直到模型不再要求调用工具。这个循环就是智能体"自主决策"的本质。

Spring AI 2.0 对比 1.x 最大的变化是工具执行与模型解耦。1.x 里工具执行器绑死在某一个模型供应商的实现上；2.0 把 ToolCallingManager 抽成独立组件，你可以对一个 ChatClient 动态注入不同的工具集合，甚至链路式串起多个工具上下文。这种可组合性让"工具编排"变成了"组装积木"，而不是写一层套一层的 if-else。

理解了这三层，你就能预判绝大多数问题：工具不生效，多半是描述层没扫描到 Bean；参数绑定报错，多半是调用层类型不匹配；多工具结果冲突，是因为缺了回传循环层的仲裁逻辑。下面我们用一个完整实战把这三层落地。

三、实战：手把手写代码

3.1 环境准备与 POM 配置

先建一个 Maven 工程，Java 版本设为 21，依赖 Spring Boot 4.1.0 和 Spring AI 2.0.0。这里用 OpenAI 兼容接口做演示，你也可以换成 Spring AI Alibaba 的 Qwen 模型，代码结构一样。

<span leaf=""><span>&lt;?xml version=</span><span><span>"1.0"</span></span><span>&nbsp;encoding=</span><span><span>"UTF-8"</span></span><span>?&gt;</span></span>

3.2 声明多个可组合的 Tool

下面声明三个工具：查询机票、查询余额、模拟下单。每个方法都加 @Tool 注解，Javadoc 首行写清楚功能，参数名起得自解释，这些都会被大模型"读懂"。

<span leaf="">package com.<span>deifan</span>.<span>agenttools</span>;</span>

代码完整可运行，三个工具方法就是一个"工具库"（Tool Library）。@Component 让 Spring AI 启动时自动扫描并注册这些工具，你不需要手动配置任何工具列表。

3.3 用 ChatClient 触发组合式调用

Spring AI 2.0 的 ChatClient 是函数式 API，通过 .tools() 一次性注入多个工具，写一个 Controller 暴露接口测试组合调用。

<span leaf=""><span>package</span>&nbsp;com.deifan.agenttools;</span>

启动应用后请求 /book?question=帮我订一张明天从上海到北京、预算1200以内的机票，大模型会按顺序自主调用 queryFlights 拿航班、queryBalance 查余额、bookTicket 下单。这里的 .tools() 是组合点：你可以按业务场景动态决定注入哪几个工具，这就是"可组合"。

3.4 自反馈循环：监听工具调用事件

上面是模型自主多步调用，内部已自动回传。但如果要在工具失败时触发"重试"或"改用备用航司"这种自反馈逻辑，需要监听工具调用事件。Spring AI 2.0 提供 ToolCalling 回调，能拿到每个工具的参数和结果。

<span leaf=""><span>package</span>&nbsp;com.deifan.agenttools;</span>

当你需要完全掌控循环时，可以替换 internalToolExecutionEnabled(false)，改为自己订阅 ToolCalling 事件流，在工具返回后手动决定下一步——这适用于"工具失败要重试"或"结果超预算要换航班"的强业务逻辑场景。事件流里每个 ToolCallResult 都能拿到方法的出入参，方便记录日志和审计。

到此，三个痛点对应的解法都落地了：工具声明稳定靠 @Tool + 清晰的 Javadoc 描述；结果冲突靠回传统一由模型仲裁；失败重试靠监听事件流自己写循环。

四、踩坑经验和最佳实践

写组合式 Tool Calling 最容易踩的坑，集中在描述、绑定和循环三个层面，逐个说。

坑一：@Tool 不生效。 最常见原因是工具类没有被 Spring 容器扫描到，或者方法不是 public。Spring AI 2.0 扫描的是容器里所有带 @Tool 注解的方法，类必须标注 @Component 且在启动类包路径下。调试方法：启动日志里看到 Registered tool: queryFlights 类似输出就说明注册成功；没看到就检查包扫描路径和注解。

坑二：参数绑定类型错误。 大模型返回的参数是 JSON，反序列化时如果方法参数是 int 而模型给了带小数或字符串的值，会抛类型转换异常。最佳实践是参数尽量用 String 或包装类型，并在方法内部自己防御性解析，别指望模型永远给对类型。给 @ToolParam 写清晰的 description 能显著降低模型乱传参的概率。

坑三：工具一多，模型就"选择困难"。 数据上，一个 ChatClient 里塞超过 10 个工具，模型选错的概率明显上升。解决思路是给工具分类、按场景分批注入，而不是一次全给。.tools("查询类", "订单类") 分批传给不同的 ChatClient 实例，模型只在小集合里选，准确率高得多。

最佳实践清单：

  • 工具描述用"动词开头 + 参数含义"

    ，比如"查询旅客人数"，比"data"这种模糊描述命中率高。

  • 工具方法保持无状态

    ，别把会话状态存在工具类的字段里，否则并发请求会互相污染。

  • 敏感操作（下单、扣款）的工具默认不自动执行

    ，先返回"待确认"让模型向用户二次确认，避免误操作。

  • 每个工具结果尽量返回结构化 JSON 字符串

    ，方便模型解析和下一条工具做参数，别返回一堆口水话。

  • 生产环境务必记录工具调用日志

    ，ToolCallResult 里带上 traceId，出问题能回查是哪一步出的错。

五、性能对比和技术选型

组合式 Tool Calling 在 Spring AI 2.0 里相比 1.x 的"单次工具调用"和纯自研编排，优势很实在，用一个简单的对比表说清楚。

| 方案

|

多工具编排

|

自反馈循环

|

实现成本

|

适用场景

单工具 @Tool 调用（1.x 风格）

|

弱，靠手写 if-else 串联

|

无

|

低

|

简单单查单写

| |

组合式 Tool Calling（2.0）

|

强，模型自主决策

|

有，支持事件监听

|

中

|

多工具智能体、流程决策

| |

自研 Agent 编排框架

|

可控但僵化

|

需自己造轮子

|

高

|

强规则、需完全掌控

|

性能上，组合式多步调用的一次完整流程会发起多轮模型请求（每多决策一步就多一次），这是 Agent 的固有成本，不是 Spring AI 的问题。实测中，“查航班+查余额+下单"这种三步流程比单工具多约 2 倍延迟，换来的是一次说出完整指令的体验。如果对延迟极其敏感，可以把确定性步骤用代码写死，只把真正需要"模型决策"的地方交给 Tool Calling，这是最常见的混合优化。

选型建议：如果你的业务是"分支多、要模型判断走哪条路”，选组合式 Tool Calling 准没错；如果只是一些固定的增删改查，老老实实写 Controller 服务方法，别为了用 AI 而用 AI。

六、总结

Spring AI 2.0 的组合式 Tool Calling，把"一个模型调一个函数"升级成了"模型自主编排多工具、失败能自反馈重试"的 Agentic 能力。整篇文章核心就三件事：用 @Tool + @ToolParam 稳定声明工具库、用 ChatClient.tools() 组合注入并按场景分流、用事件流监听实现失败重试和结果仲裁。

记住那条铁律：版本号必须是实测查来的 GA 版本，本文基于 Spring Boot 4.1.0 + Spring AI 2.0.0，Starter 用 spring-ai-starter-model-openai。别背旧文档里的 1.x 命名，2.0 已经把工具执行和模型解耦，编排变成组装积木。

动手要点：先跑通单工具，再加第二个、第三个，最后再上事件监听做自反馈。工具描述写得越清晰，模型越不会选错。这是你做任何多工具智能体的起跑线，跨过它，后面的 Agent 编排才有地基。