结论先行
这段代码通过“模型提出工具调用、本地 Java 查询天气、模型解释工具结果”的往返过程,生成两个城市的穿衣建议。工具名、参数结构与描述发给模型;方法对象、HTTP 客户端和真正执行工具的能力留在应用内。
在本文核对的 Spring AI 2.1.0-M1 中,ChatClient 会自动注册 ToolCallingAdvisor,所以注释掉手动添加它的代码仍可执行工具。call().content() 是一轮业务请求,内部可能包含多次模型请求。
本例查询当前气温,坐标由模型填写;没有查询全天预报、降雨和风力。源码事实来自匹配版本的依赖源码,协议概览可参阅 Spring AI 官方工具调用说明。
问题背景
链式 API 把复杂过程压缩成几行,容易让人误以为模型直接调用了 Java 方法,或以为 @Service 会自动把方法开放给模型。另一个常见误解是把一次 call 当成一次模型 HTTP 请求。
本文从应用启动沿着实际调用顺序展开,先解释对象由谁创建,再解释工具如何被描述、调用和返回,最后把日志、错误处理及业务限制放回完整流程。Advisor 在文中指模型调用前后的处理步骤;ToolCallback 指留在本地、可以真正执行工具的回调。
详细内容
从一段穿衣建议代码开始
用户问:“今天在阿姆斯特丹和巴塞罗那应该穿什么?”程序没有写死温度,也没有预先调用天气接口,而是把一个 Java 工具交给模型。模型返回需要执行的工具和参数,程序查到气温后,再请模型给出建议。
package com.example.demo;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.ToolCallingAdvisor;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
@SpringBootApplication
public class ToolDemoApplication {
public static void main(String[] args) {
SpringApplication.run(ToolDemoApplication.class, args);
}
@Bean
public CommandLineRunner cli(ChatClient.Builder chatClientBuilder) {
return args -> { // @formatter:off
ChatClient chatClient = chatClientBuilder
.defaultAdvisors(MyLoggingAdvisor.builder().showAvailableTools(true).build())
.build();
var output = chatClient.prompt()
.user("What should I wear today in Amsterdam and in Barcelona?")
.tools(new WeatherTools())
.advisors(ToolCallingAdvisor.builder().build())
.call()
.content();
System.out.println("\n" + output);
}; // @formatter:on
}
}这段代码来自演示项目的 08-tools 模块。本文以项目实际使用的 Spring AI 2.1.0-M1、Spring Boot 4.0.7 为分析范围;Java 编译目标为 17。后文的框架实现依据对应版本源码包,不把其他版本教程中的内部实现直接搬过来。
天气数字、工具调用 ID 和日志均为说明用的示例,不是实测结果。标有“简化逻辑”的代码用于解释控制流程,不是可以直接替换框架源码的完整实现。
先分清五个角色:入口、处理链、模型、工具与天气服务
| 角色 | 对应组件 | 负责的具体事情 |
|---|---|---|
| 应用入口 | Spring Boot、CommandLineRunner | 创建容器,执行启动后的演示任务 |
| 对话入口 | ChatClient | 收集用户消息、工具和选项,构造处理链 |
| 工具循环 | ToolCallingAdvisor | 请求模型,检查工具调用,执行工具,再请求模型 |
| 模型适配 | AnthropicChatModel | 转换 Anthropic 请求与响应,通过 SDK 访问模型 |
| 本地执行 | ToolCallingManager、MethodToolCallback | 找到工具,把 JSON 转成参数,调用 Java 方法 |
| 天气查询 | WeatherTools、RestClient | 请求 Open-Meteo,读取当前气温 |
| 过程日志 | MyLoggingAdvisor | 打印每轮问题、工具调用、结果和模型文字 |
用户问题 + 工具定义
→ ToolCallingAdvisor
→ MyLoggingAdvisor
→ AnthropicChatModel
→ 模型返回工具名与 JSON 参数
→ ToolCallingManager
→ MethodToolCallback
→ WeatherTools.getTemperature(...)
→ Open-Meteo
→ 工具结果加入对话
→ 再次请求模型
→ 最终穿衣建议模型只负责提出调用请求,实际执行权在本地应用。它不会拿到 Java 对象引用,不会进入 JVM,也不会直接使用你的 RestClient。发送给模型的是工具说明和参数格式,留在本地的是方法、目标对象及执行逻辑。
应用启动后为什么会自动运行这段逻辑
@SpringBootApplication 将配置、自动配置和组件扫描组合起来。SpringApplication.run(...) 创建应用上下文,加载配置与 Bean;随后 Spring Boot 执行容器中的 CommandLineRunner。
@Bean
public CommandLineRunner cli(ChatClient.Builder chatClientBuilder) {
return args -> {
// 容器初始化完成后,执行这里的演示逻辑。
};
}创建 Bean 和执行任务是两个时间点。Spring 调用 cli(...) 时,得到一个实现 CommandLineRunner 的 Lambda;这时并没有因为创建 Lambda 就请求模型。启动任务运行时,才执行其中的 Client 构建与对话调用。
args 是应用启动参数,这段示例没有使用它。用户问题直接写在 .user(...) 中。模块配置了 spring.main.web-application-type=none,因此当前是启动后执行任务的程序,而非提供问答接口的 Web 服务。
组件扫描从 com.example.demo 开始,但只扫描运行时类路径中的类。仓库里其他模块即使有同名包,也不会仅因包名相同就全部加载。
ChatClient.Builder 从哪里来,模型供应商如何确定
业务方法没有声明 Builder Bean,却可以直接注入,是因为模块依赖了 spring-ai-starter-model-anthropic。模型自动配置创建 AnthropicChatModel,Client 自动配置再基于这个 ChatModel 创建 ChatClient.Builder。
Anthropic Starter
→ AnthropicChatAutoConfiguration
→ AnthropicChatModel
→ ChatClientAutoConfiguration
→ ChatClient.Builder
→ 注入 cli(...)ChatClient 提供通用的对话 API;AnthropicChatModel 处理具体供应商协议。业务代码只依赖前者,实际供应商由依赖、配置和自动配置共同决定。
自动配置的 Builder 使用 prototype 作用域,不同注入点得到独立的构建实例,避免共享可变构建配置。Lambda 内部 .build() 创建的 Client 只是局部对象,并不会自动注册成 Spring Bean。
defaultAdvisors 与链式调用:什么时候真正请求模型
ChatClient chatClient = chatClientBuilder
.defaultAdvisors(MyLoggingAdvisor.builder()
.showAvailableTools(true)
.build())
.build();Advisor 可以理解成模型调用前后的处理步骤。defaultAdvisors(...) 将日志步骤设为这个 Client 后续请求的默认配置,并不影响应用里的所有 Client。showAvailableTools(true) 只控制日志显示工具名称,不负责启用工具能力。
| 调用 | 发生的事情 | 是否已经执行模型请求 |
|---|---|---|
| prompt() | 创建本次请求的构建对象,带入 Client 默认配置 | 否 |
| user(...) | 设置用户消息 | 否 |
| tools(...) | 把工具对象转换成可描述、可执行的回调 | 否 |
| call() | 建立处理链和同步响应对象 | 否,当前版本仍在准备 |
| content() | 执行处理链,等待完成,提取最终文字 | 是 |
源码中 call() 构造 DefaultCallResponseSpec;content() 再调用 doGetObservableChatClientResponse(...),最终进入 advisorChain.nextCall(...)。因此,“同步调用模式”不等于“调用 call 方法的一瞬间就已经发送请求”。
content() 返回的是最终响应第一项结果中的文字,不包含完整工具调用、用量和元数据。需要这些信息应读取 chatResponse() 或 chatClientResponse()。当前调用会等待完整结果;逐步接收模型输出需要使用流式 API。
源码定位:DefaultChatClient:call、content 与处理链构造。
从 chatClientBuilder 到本次请求的 Advisor 链
上面的 chatClientBuilder 是注入的 ChatClient.Builder 变量;其默认实现 DefaultChatClientBuilder 的 build() 如下。这里创建 Client,保存默认请求配置,还没有构建本次请求的 Advisor 链。
public ChatClient build() {
return new DefaultChatClient(this.defaultRequest);
}接着,prompt() 复制默认请求配置,user(...)、tools(...) 与 advisors(...) 补充本次请求。调用 call() 时才执行下面的代码。以下方法均摘自 DefaultChatClient.DefaultChatClientRequestSpec,保留 2.1.0-M1 的实际实现。
@Override
public CallResponseSpec call() {
BaseAdvisorChain advisorChain = buildAdvisorChain();
return new DefaultCallResponseSpec(DefaultChatClientUtils.toChatClientRequest(this), advisorChain,
this.observationRegistry, this.chatClientObservationConvention);
}private BaseAdvisorChain buildAdvisorChain() {
autoRegisterToolCallingAdvisor();
validateSingleToolAdvisor();
// At the stack bottom add the model call advisors.
// They play the role of the last advisors in the advisor chain.
List<Advisor> chain = new ArrayList<>(this.advisors);
chain.add(ChatModelCallAdvisor.builder().chatModel(this.chatModel).build());
chain.add(ChatModelStreamAdvisor.builder().chatModel(this.chatModel).build());
return DefaultAroundAdvisorChain.builder(this.observationRegistry)
.observationConvention(this.advisorObservationConvention)
.pushAll(chain)
.build();
}autoRegisterToolCallingAdvisor():按条件补上默认工具 Advisor,详细判断见后文“注释掉 ToolCallingAdvisor 为什么仍然能工作”。validateSingleToolAdvisor():检查工具 Advisor 是否超过一个;超过就抛异常,尚未请求模型。- 复制当前 Advisor 列表,再添加同步与流式模型调用 Advisor,作为对应调用方式的末端处理步骤;这不表示一次同步请求会同时调用两次模型。
pushAll(chain).build()创建处理链,交给DefaultCallResponseSpec保存;随后调用content()等取值方法才执行请求。
所以两处 build() 的作用不同:chatClientBuilder.build() 创建可复用的 Client;请求内部的 buildAdvisorChain() 为本次调用准备处理步骤。stream() 也会调用同一个 buildAdvisorChain(),然后创建流式响应对象。
WeatherTools 的完整实现:工具真正做了什么
package com.example.demo;
import java.time.LocalDateTime;
import org.slf4j.Logger;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestClient;
@Service
public class WeatherTools {
private static final Logger logger = org.slf4j.LoggerFactory.getLogger(WeatherTools.class);
private final RestClient restClient;
public WeatherTools() {
this.restClient = RestClient.create();
}
public record WeatherResponse(Current current) {
public record Current(LocalDateTime time, int interval, double temperature_2m) {
}
}
@Tool(description = "Get the temperature (in celsius) for a specific location")
public WeatherResponse getTemperature(@ToolParam(description = "The location latitude") double latitude,
@ToolParam(description = "The location longitude") double longitude,
@ToolParam(description = "The city name") String city) {
WeatherResponse response = restClient
.get()
.uri("https://api.open-meteo.com/v1/forecast?latitude={latitude}&longitude={longitude}¤t=temperature_2m",
latitude, longitude)
.retrieve()
.body(WeatherResponse.class);
logger.debug("Check temparature for {}. Lat: {}, Lon: {}. Temp: {}", city, latitude, longitude,
response.current);
return response;
}
}工具只提供一个能力:根据经纬度查询当前摄氏气温。WeatherResponse 和内部的 Current 都是 Java record,用来接收结构化返回值。record 自动生成访问器、构造方法和常用对象方法。
current 包含数据时间、时间间隔和 temperature_2m。外层类访问内部 record 的字段 response.current 在这里合法;业务读取温度也可以使用 response.current().temperature_2m()。
方法接收 city,但它只用于日志。真正发给天气服务的只有经纬度。城市名和坐标不一致时,当前实现仍然查询坐标位置,不会自动核验城市。
@Tool 怎样变成模型可以理解的工具定义
.tools(new WeatherTools()) 接收到普通 Java 对象后,通过 ToolCallbacks.from(...) 交给 MethodToolCallbackProvider。它查找 @Tool 方法,为每个方法创建 MethodToolCallback。
DefaultChatClientRequestSpec.tools(...)
→ ToolCallbacks.from(...)
→ MethodToolCallbackProvider.getToolCallbacks()
→ ToolDefinitions.from(method)
→ ToolMetadata.from(method)
→ MethodToolCallback| 部分 | 内容 | 是否发送给模型 |
|---|---|---|
| 工具定义 | 名称、描述、输入参数 JSON Schema | 是,转换为供应商的工具格式 |
| 执行绑定 | Java Method、目标对象、结果转换器 | 否,留在应用内执行 |
| 执行元数据 | 例如 returnDirect | 用于框架控制执行和返回流程 |
没有显式设置名称时,工具名取方法名 getTemperature;描述来自 @Tool;参数类型、名称与说明共同用于生成输入 Schema。@ToolParam 默认必填,因此本例的三个参数都进入 required 列表。
{
"name": "getTemperature",
"description": "Get the temperature (in celsius) for a specific location",
"inputSchema": {
"type": "object",
"properties": {
"latitude": {"type": "number", "description": "The location latitude"},
"longitude": {"type": "number", "description": "The location longitude"},
"city": {"type": "string", "description": "The city name"}
},
"required": ["latitude", "longitude", "city"]
}
}上面省略了完整 Schema 的其他元信息。框架按反射得到的参数名取值,构建时应保留方法参数名;当前项目编译日志中的 parameters 表示启用了相关编译选项。
Schema 是对输入结构的说明,不等于业务校验。当前代码没有检查纬度范围、经度范围,也没有验证坐标与城市是否匹配;单写一个参数描述不会自动补上这些检查。
第一轮模型请求与工具选择:模型决定调用什么
处理链末端的 ChatModelCallAdvisor 调用 chatModel.call(prompt)。AnthropicChatModel 将通用消息和工具定义转换为 Anthropic SDK 请求;工具参数说明进入结构化的 tools[].input_schema,不是简单拼成一段用户文本。
模型可能根据用户的问题,返回两次 getTemperature 调用。下面是其中一次调用的示意:
{
"type": "tool_use",
"id": "call_amsterdam",
"name": "getTemperature",
"input": {
"latitude": 52.3676,
"longitude": 4.9041,
"city": "Amsterdam"
}
}经纬度是模型填写的。本例没有地理编码工具,不能把这一步描述为程序已经从地图服务验证了坐标。城市、坐标和工具调用 ID 都是用于解释的示例。
模型也可能先查一个城市,下轮再查另一个;可能输出说明文字后请求工具,也可能直接回答。.tools(...) 提供能力,不代表强制调用;当前业务代码没有设置必须使用工具的选项。
JSON 参数如何变成一次 Java 方法调用
供应商响应先被转换为 Spring AI 的 AssistantMessage.ToolCall,包含调用 ID、类型、工具名称与 JSON 参数。ToolCallingAdvisor 判断到存在工具调用后,将其交给 ToolCallingManager.executeToolCalls(...)。
默认管理器按工具名在当前请求的回调列表中查找,随后执行 toolCallback.call(arguments, toolContext)。对于方法工具,进入 MethodToolCallback:
// 简化后的执行顺序。
Map<String, Object> arguments = extractToolArguments(toolInput);
Object[] methodArguments = buildMethodArguments(arguments, toolContext);
Object result = callMethod(methodArguments);
return toolCallResultConverter.convert(result, returnType);构造参数时,按 parameter.getName() 从 JSON Map 中取值,转换成 Java 目标类型,再按方法声明的顺序排列。真正执行方法使用 Java 反射:
this.toolMethod.invoke(this.toolObject, methodArguments);因此,模型输出的 JSON 最终对应于本地的一次 weatherTools.getTemperature(52.3676, 4.9041, "Amsterdam")。这里没有生成 Java 程序再动态编译,模型也没有获得任意执行应用方法的入口。
天气 HTTP 请求与返回值:当前气温不是全天预报
RestClient 发起同步 GET 请求,将纬度和经度填入 URL;retrieve() 使用响应提取与默认错误状态处理,body(WeatherResponse.class) 读取响应并转换为 Java 对象。
https://api.open-meteo.com/v1/forecast
?latitude=52.3676
&longitude=4.9041
¤t=temperature_2m关键是 current=temperature_2m:本例读取当前的两米高度气温。接口路径虽然是 forecast,但代码没有请求当天的逐小时气温、最高最低温、降雨或风速。当前天气数据基于天气模型,也不等于保证返回某个现场传感器的即时实测值。
请求没有指定 timezone,接口默认采用 GMT/UTC;Java 的 LocalDateTime 又不保存时区,不能把它直接当作城市当地时间。这些接口含义见 Open-Meteo 官方文档。
工具能够支撑“当前气温下适合穿什么”的判断;如果回答进一步断言下午下雨或晚上会降到某个温度,当前工具没有提供这类数据。
工具结果怎样返回模型:调用 ID 与消息历史的作用
WeatherResponse 是 JVM 对象,需要经过 DefaultToolCallResultConverter 序列化为 JSON 字符串。管理器再将调用 ID、工具名和结果放入 ToolResponseMessage.ToolResponse。
new ToolResponseMessage.ToolResponse(
toolCall.id(),
toolName,
toolCallResult
);两个城市使用相同工具名,区分每次调用的是 ID:call_amsterdam 对应阿姆斯特丹,另一个 ID 对应巴塞罗那。模型不必依靠返回值中是否包含城市名来猜测对应关系。
USER:两个城市今天应该穿什么?
ASSISTANT:调用 getTemperature,ID=A,查询 Amsterdam
调用 getTemperature,ID=B,查询 Barcelona
TOOL:ID=A 的查询结果
ID=B 的查询结果
ASSISTANT:根据返回的气温组织穿衣建议管理器把模型的工具请求消息和工具结果追加到本次历史,下一次请求一起发送。只发送两个温度数字会丢失原问题、调用参数和结果对应关系。
Spring AI 内部使用统一的 TOOL 消息类型;Anthropic 适配层会把它转换为带 tool_result 内容块的 user 消息,把模型工具请求映射为 tool_use。统一 API 不意味着供应商 HTTP 消息格式完全一致。
天气事实来自接口,穿衣建议来自模型对这些事实的解释。工具方法本身没有编写“多少度穿什么”的规则。
ToolCallingAdvisor:一次业务请求为何会请求模型多次
// 解释控制流程的简化逻辑。
do {
response = downstreamChain.call(request);
if (response.hasToolCalls()) {
result = toolCallingManager.executeToolCalls(prompt, response);
request = requestWithUpdatedHistory(result);
}
} while (response.hasToolCalls());
return response;当前源码通过 callAdvisorChain.copy(this).nextCall(...) 执行后续处理链。每轮复制的是工具 Advisor 后面的步骤,不会把整个链上的所有步骤一律从头执行。模型不再要求调用工具时,正常循环结束。
| 模型行为 | 模型请求次数示例 |
|---|---|
| 首轮同时请求两个城市,下一轮回答 | 2 次 |
| 第一轮查一个城市,第二轮查另一个,第三轮回答 | 3 次 |
| 不使用工具直接作答 | 1 次 |
| 参数有误后重试或继续补查 | 可能更多 |
@Tool 默认 returnDirect=false,所以本例查询完成后还会把结果交回模型。如果显式启用直接返回,框架会采用不同的返回路径,不能再假设一定经过模型组织成自然语言。
当前版本默认管理器每轮用户请求限制单个工具最多 40 次、全部工具合计最多 150 次,配置或自定义管理器可改变这些限制。次数限制防止工具被无限调用,但不替代网络超时,也不保证每轮都会成功。
默认工具管理器使用普通 for 循环逐个执行同一批工具调用。模型一轮提出两个查询,不代表本地并行执行。spring.threads.virtual.enabled=true 也不会自动把这段循环变成并行。
注释掉 ToolCallingAdvisor 为什么仍然能工作
// .advisors(ToolCallingAdvisor.builder().build())在当前版本中,DefaultChatClient 构建链时自动注册工具 Advisor:没有关闭自动注册,且链上还不存在实现 ToolAdvisor 的对象,就添加默认 ToolCallingAdvisor。因此注释这行不会关闭工具调用。
取消注释后,框架检测到已经存在工具 Advisor,就不再自动补一个;通常不会出现两个循环重复查询。若显式注册多个工具 Advisor,框架会进行数量校验并报错。
自动注册与数量校验的实际源码
下面两个方法由前面的 buildAdvisorChain() 依次调用,均为 2.1.0-M1 源码摘录:
private void autoRegisterToolCallingAdvisor() {
boolean autoRegisterDisabled = Boolean.FALSE
.equals(this.advisorParams.get(ChatClientAttributes.TOOL_CALLING_ADVISOR_AUTO_REGISTER.getKey()));
if (autoRegisterDisabled) {
return;
}
boolean hasToolCallingAdvisor = this.advisors.stream().anyMatch(a -> a instanceof ToolAdvisor);
if (hasToolCallingAdvisor) {
return;
}
int configuredOrder = this.toolCallingAdvisorBuilder.getAdvisorOrder();
boolean hasDownstreamMemoryAdvisor = this.advisors.stream()
.anyMatch(a -> a instanceof MemoryAdvisor && a.getOrder() > configuredOrder);
this.advisors.add(this.toolCallingAdvisorBuilder.copy()
.conversationHistoryEnabled(!hasDownstreamMemoryAdvisor)
.build());
}private void validateSingleToolAdvisor() {
List<Advisor> toolAdvisors = this.advisors.stream().filter(a -> a instanceof ToolAdvisor).toList();
if (toolAdvisors.size() > 1) {
String names = String.join(", ",
toolAdvisors.stream().map(a -> a.getName() + " (order=" + a.getOrder() + ")").toList());
throw new IllegalStateException("At most one ToolAdvisor is allowed in the advisor chain, but found "
+ toolAdvisors.size() + ": [" + names + "]");
}
}自动注册先看本次 Advisor 参数是否明确设为 Boolean.FALSE,再检查是否已有实现 ToolAdvisor 的对象;任一条件满足就直接返回。检查范围是 ToolAdvisor 接口,并非只检查 ToolCallingAdvisor 这个具体类。
两个条件都不满足时,才复制已配置的工具 Advisor Builder 并添加实例。这一步没有以“当前是否已有静态工具”为前提,因此其他 Advisor 在运行中动态提供工具时,也有工具处理步骤可用。
hasDownstreamMemoryAdvisor 检查是否存在 order 更大的 MemoryAdvisor。有的话,自动注册的工具 Advisor 关闭自身内部对话历史,由后面的 MemoryAdvisor 处理每轮历史;没有的话,工具 Advisor 保留内部历史。本例没有配置 ChatMemory,走后者。
最后的数量校验允许零个或一个 ToolAdvisor,超过一个便抛出 IllegalStateException,错误消息列出各 Advisor 的名称与 order。它负责报错,不会替你挑选一个或自动删除重复项。
不过手动 ToolCallingAdvisor.builder().build() 使用自己的默认管理器,不一定沿用 Spring 容器中配置的观察注册器、异常处理和调用次数限制。只需默认功能时,保留自动配置即可。真要取消注释,还需导入 org.springframework.ai.chat.client.advisor.ToolCallingAdvisor。
spring.ai.chat.client.tool-calling.enabled=false上面配置关闭的是自动注册,不会删除你手动添加的 Advisor。关闭自动注册且没有其他工具处理逻辑时,模型仍可能返回工具调用,但此处不会替你执行;单看 content() 不能认为天气查询已经完成。
本文讨论 2.1.0-M1 的 Client 工具循环,不能套用旧版本由各个 ChatModel 内部执行循环的说明。官方文档可用于了解整体架构,精确方法与默认值以匹配依赖版本的源码为准。
MyLoggingAdvisor:日志为什么能看到中间轮次
MyLoggingAdvisor 实现 BaseAdvisor,由默认模板依次执行 before、后续处理链和 after。当前实现仅输出日志,然后原样返回对象。
// BaseAdvisor 的同步处理顺序。
processedRequest = before(request, chain);
response = chain.nextCall(processedRequest);
return after(response, chain);日志 Advisor 默认 order 为 0;工具 Advisor 默认 order 为 Ordered.HIGHEST_PRECEDENCE + 300,是一个更小的负数。处理链按数值从小到大进入,所以日志步骤在工具循环内部:
ToolCallingAdvisor(外层控制循环)
├─ 第 1 轮:MyLoggingAdvisor.before → 模型 → after
├─ 执行天气工具
└─ 第 2 轮:MyLoggingAdvisor.before → 模型 → after放在工具 Advisor 之前的步骤通常包住整轮业务请求,放在之后的步骤会参与每轮模型请求。这比单看 Builder 中添加 Advisor 的书写先后更重要。
| 字段 | 说明 |
|---|---|
| TOOLS | 当前可用工具名,不表示已经调用 |
| TOOL-CALL | 模型请求调用的工具及 JSON 参数 |
| TOOL-RESPONSE | 工具执行后的返回内容 |
| TEXT | 用户文字或模型文字,依当前消息阶段而定 |
before 的 USER 标签是代码写死的,即使最后消息是工具返回,也会先打印 USER,再输出 TOOL-RESPONSE。不要据此误判消息类型。
日志中系统文字最多显示 50 字符,用户和工具返回最多显示 300 字符,模型文字最多显示 200 字符。截断只作用于日志,不修改发给模型的消息。最后 System.out.println(output) 再打印完整最终文字,所以可能看到一段截断日志和一份完整答案。
默认 showConversationHistory=false 只是不打印全部历史,不会关闭本轮工具循环需要的历史消息。
@Service 与 new 同时存在:实际使用的是哪个对象
WeatherTools 带 @Service,正常扫描会创建一个由 Spring 管理的实例;new WeatherTools() 又创建了另一个实例。注册给本次工具调用的是后者。
当前对象自行创建 RestClient,所以可以工作。但后续若依赖字段注入、事务代理或缓存代理,手动 new 的对象不会因为类上有 Service 注解就自动获得这些能力。
@Bean
public CommandLineRunner cli(ChatClient.Builder builder, WeatherTools weatherTools) {
return args -> {
ChatClient client = builder
.defaultAdvisors(MyLoggingAdvisor.builder()
.showAvailableTools(true).build())
.build();
String output = client.prompt()
.user("What should I wear today in Amsterdam and in Barcelona?")
.tools(weatherTools)
.call()
.content();
System.out.println(output);
};
}这段改法通过方法参数注入工具,明确使用容器管理的实例。@Service 负责创建 Bean,.tools(...) 负责让当前请求知道有哪些工具;单独添加 Service 注解,不会把所有方法自动开放给所有模型。
消息积累、错误处理与实际运行配置
工具循环会保留当前问题、工具请求和工具结果,但这不是跨请求记忆。当前示例没有配置 ChatMemory;再次调用 prompt() 时,不应假定自动记得上一次的城市和用户偏好。
工具方法抛出的异常可被 MethodToolCallback 包装成 ToolExecutionException。默认异常处理器的 alwaysThrow 为 false,对能够处理的运行时异常可将错误消息返回模型,允许后续继续处理;非运行时异常、指定要重新抛出的异常,以及部分框架或参数异常仍可能中断请求。
| 位置 | 例子 | 不能作出的假设 |
|---|---|---|
| 模型请求 | 认证失败、网络失败、供应商报错 | 底层可能重试,但不保证最终成功 |
| 天气方法 | 接口错误、响应读取失败 | 可能把错误作为工具结果交给模型,不保证自动重试 |
| 参数和回调查找 | 参数类型不匹配、工具名不存在 | 不是所有错误都会转成自然语言答案 |
工具没有显式设置网络超时、业务重试或空响应检查。若 response 为 null,读取 response.current 会抛空指针异常;即使 DEBUG 日志关闭,日志方法的参数表达式仍先求值。
项目公共模块还提供 DotenvEnvironmentPostProcessor,从工作目录向上寻找 .env,作为低优先级配置来源补充模型凭据;环境变量和系统属性等已有高优先级值仍优先。这是项目扩展,不是 ChatClient 自带的 .env 加载行为。
公共模块间接引入 Inspector Starter。启用后会探测 Inspector 服务,发现服务才激活观察 Advisor 与模型代理路由。因此实际链上可能还有观察整轮请求和每轮模型请求的步骤。观察扩展不负责实现天气工具,也不改变模型提出请求、本地执行工具这一分工。
从演示走向实际使用:数据能力决定建议范围
| 需求 | 当前能力 | 更可靠的补充 |
|---|---|---|
| 城市是否定位准确 | 模型填写经纬度 | 地理编码查询及城市与坐标校验 |
| 今天全天怎么穿 | 当前气温 | 当地当天的逐小时或最高最低温 |
| 需不需要防雨 | 未查询降雨 | 降雨概率、降水量及对应时段 |
| 风大是否体感冷 | 未查询风力与体感 | 风速、阵风与体感温度 |
| 今天按哪一天计算 | 未明确城市时区 | 明确地点时区、查询日期和有效时间 |
| 服务失败怎么办 | 依赖默认异常处理 | 明确超时、有限重试和可解释的失败结果 |
这些补充不是完成工具调用演示的前提,但决定了它能否成为可靠的穿衣建议功能。工具描述越清楚,模型越容易正确选择;输入校验和异常处理越明确,应用越容易控制实际执行结果。
如果工具以后涉及付款、删除或写入数据,还需要在应用侧控制可用工具和执行条件。模型提出调用不等于业务操作天然获得授权。
按调用顺序读源码:一份可以直接跟进的断点清单
| 顺序 | 源码位置 | 重点观察 |
|---|---|---|
| 1 | DefaultChatClientRequestSpec.tools | 工具对象如何变成回调 |
| 2 | MethodToolCallbackProvider.getToolCallbacks | 方法、对象、定义如何绑定 |
| 3 | autoRegisterToolCallingAdvisor | 没有手动添加时的自动注册 |
| 4 | DefaultCallResponseSpec.content | 终端取值如何启动执行链 |
| 5 | ToolCallingAdvisor.adviseCall | 每轮请求及消息累积 |
| 6 | MyLoggingAdvisor.before / after | 本轮原始文字和工具请求 |
| 7 | AnthropicChatModel.internalCall | 供应商请求与响应转换 |
| 8 | DefaultToolCallingManager.executeToolCalls | 工具名称查找与执行顺序 |
| 9 | MethodToolCallback.call | JSON 参数到 Java 参数的转换 |
| 10 | WeatherTools.getTemperature | 天气请求和实际返回值 |
调试时先确认 IDE 附加的 sources.jar 与运行的依赖版本相符。先看工具定义,再看第一次工具调用响应,再看本地执行和第二轮消息,就能把这段链式 API 与真实执行过程对应起来。
总结归纳
阅读这段示例时,先把工具定义与本地执行分开,再把一轮业务请求与多轮模型调用分开。前者解释模型如何知道能做什么,后者解释为什么查询完天气还要再问一次模型。
沿着 tools → MethodToolCallbackProvider → ToolCallingAdvisor → AnthropicChatModel → ToolCallingManager → MethodToolCallback → WeatherTools 的顺序看源码,便能对齐整个过程。真正用于穿衣建议时,下一步应补齐地点、时区和天气指标,再明确超时、失败处理与输入校验。
参考资料
- Spring AI · Tool Calling
用于理解工具定义、应用负责执行和 Advisor 循环的整体关系。参考页会随版本更新,具体实现与默认值以本文核对的 2.1.0-M1 源码为准。
- DefaultChatClient · v2.1.0-M1
call 与 content 的执行时机、工具注册、自动注册工具 Advisor。
- ToolCallingAdvisor · v2.1.0-M1
多轮循环、后续处理链复制、直接返回与次数超限处理。
- MethodToolCallbackProvider · v2.1.0-M1
查找 @Tool 方法并绑定定义、执行对象与转换器。
- JsonSchemaGenerator · v2.1.0-M1
工具参数 Schema 的类型、描述与 required 生成。
- DefaultToolCallingManager · v2.1.0-M1
按名称执行工具、调用次数限制、消息历史拼装。
- MethodToolCallback · v2.1.0-M1
JSON 解析、Java 参数转换、反射调用和结果转换。
- AnthropicChatModel · v2.1.0-M1
模型供应商 SDK 请求、tool_use 与 tool_result 的映射。
- ChatClientAutoConfiguration · v2.1.0-M1
prototype Builder 和容器内工具管理器配置。
- DefaultToolExecutionExceptionProcessor · v2.1.0-M1
工具异常返回模型或重新抛出的具体条件。
- Open-Meteo · Weather Forecast API
当前气温、天气变量和默认时区的接口定义。
- VoxxedDays 2026 Spring AI Demo
示例项目来源;本文以本次核对的本地 08-tools、common 与 Inspector 源码为准,上游内容可能继续变化。
- DefaultChatClientBuilder · v2.1.0-M1
创建 ChatClient,以及默认 Advisor 如何写入请求配置。