麻雀窝 Sparrow Zoo

Spring AI 工具调用源码解析:一段天气问答背后的完整执行过程

从天气穿衣建议示例出发,沿 Spring AI 2.1.0-M1 源码解释 ChatClient 自动配置、@Tool 参数 Schema、ToolCallingAdvisor 多轮循环、反射执行、日志顺序与异常处理,并说明当前气温与全天建议的能力差别。

面向掌握 Java 与 Spring Boot 基础的开发者;基于 Spring AI 2.1.0-M1、Spring Boot 4.0.7,Java 编译目标 17。发布于 更新于
模型决策 · 本地执行Spring AI 2.1 工具调用源码模型读工具说明 → 返回名称与参数JSON结果Java 应用转换参数 → 调用方法 → 查天气ToolCallingAdvisor 控制多轮往返
阅读目录

结论先行

这段代码通过“模型提出工具调用、本地 Java 查询天气、模型解释工具结果”的往返过程,生成两个城市的穿衣建议。工具名、参数结构与描述发给模型;方法对象、HTTP 客户端和真正执行工具的能力留在应用内。

在本文核对的 Spring AI 2.1.0-M1 中,ChatClient 会自动注册 ToolCallingAdvisor,所以注释掉手动添加它的代码仍可执行工具。call().content() 是一轮业务请求,内部可能包含多次模型请求。

先确定版本与数据范围

本例查询当前气温,坐标由模型填写;没有查询全天预报、降雨和风力。源码事实来自匹配版本的依赖源码,协议概览可参阅 Spring AI 官方工具调用说明。

问题背景

链式 API 把复杂过程压缩成几行,容易让人误以为模型直接调用了 Java 方法,或以为 @Service 会自动把方法开放给模型。另一个常见误解是把一次 call 当成一次模型 HTTP 请求。

本文从应用启动沿着实际调用顺序展开,先解释对象由谁创建,再解释工具如何被描述、调用和返回,最后把日志、错误处理及业务限制放回完整流程。Advisor 在文中指模型调用前后的处理步骤;ToolCallback 指留在本地、可以真正执行工具的回调。

详细内容

从一段穿衣建议代码开始

用户问:“今天在阿姆斯特丹和巴塞罗那应该穿什么?”程序没有写死温度,也没有预先调用天气接口,而是把一个 Java 工具交给模型。模型返回需要执行的工具和参数,程序查到气温后,再请模型给出建议。

code
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打印每轮问题、工具调用、结果和模型文字
code
用户问题 + 工具定义
    → ToolCallingAdvisor
    → MyLoggingAdvisor
    → AnthropicChatModel
    → 模型返回工具名与 JSON 参数
    → ToolCallingManager
    → MethodToolCallback
    → WeatherTools.getTemperature(...)
    → Open-Meteo
    → 工具结果加入对话
    → 再次请求模型
    → 最终穿衣建议

模型只负责提出调用请求,实际执行权在本地应用。它不会拿到 Java 对象引用,不会进入 JVM,也不会直接使用你的 RestClient。发送给模型的是工具说明和参数格式,留在本地的是方法、目标对象及执行逻辑。

应用启动后为什么会自动运行这段逻辑

@SpringBootApplication 将配置、自动配置和组件扫描组合起来。SpringApplication.run(...) 创建应用上下文,加载配置与 Bean;随后 Spring Boot 执行容器中的 CommandLineRunner。

code
@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。

code
Anthropic Starter
    → AnthropicChatAutoConfiguration
    → AnthropicChatModel
    → ChatClientAutoConfiguration
    → ChatClient.Builder
    → 注入 cli(...)

ChatClient 提供通用的对话 API;AnthropicChatModel 处理具体供应商协议。业务代码只依赖前者,实际供应商由依赖、配置和自动配置共同决定。

自动配置的 Builder 使用 prototype 作用域,不同注入点得到独立的构建实例,避免共享可变构建配置。Lambda 内部 .build() 创建的 Client 只是局部对象,并不会自动注册成 Spring Bean。

源码定位:ChatClientAutoConfiguration:Builder 与工具 Advisor 的自动配置。

defaultAdvisors 与链式调用:什么时候真正请求模型

code
ChatClient chatClient = chatClientBuilder
    .defaultAdvisors(MyLoggingAdvisor.builder()
        .showAvailableTools(true)
        .build())
    .build();

Advisor 可以理解成模型调用前后的处理步骤。defaultAdvisors(...) 将日志步骤设为这个 Client 后续请求的默认配置,并不影响应用里的所有 Client。showAvailableTools(true) 只控制日志显示工具名称,不负责启用工具能力。

链式 API 的实际作用
调用发生的事情是否已经执行模型请求
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();
}
  1. autoRegisterToolCallingAdvisor():按条件补上默认工具 Advisor,详细判断见后文“注释掉 ToolCallingAdvisor 为什么仍然能工作”。
  2. validateSingleToolAdvisor():检查工具 Advisor 是否超过一个;超过就抛异常,尚未请求模型。
  3. 复制当前 Advisor 列表,再添加同步与流式模型调用 Advisor,作为对应调用方式的末端处理步骤;这不表示一次同步请求会同时调用两次模型。
  4. pushAll(chain).build() 创建处理链,交给 DefaultCallResponseSpec 保存;随后调用 content() 等取值方法才执行请求。

所以两处 build() 的作用不同:chatClientBuilder.build() 创建可复用的 Client;请求内部的 buildAdvisorChain() 为本次调用准备处理步骤。stream() 也会调用同一个 buildAdvisorChain(),然后创建流式响应对象。

源码定位:DefaultChatClientBuilder:build 与默认 Advisor 配置。

WeatherTools 的完整实现:工具真正做了什么

code
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}&current=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。

code
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 是对输入结构的说明,不等于业务校验。当前代码没有检查纬度范围、经度范围,也没有验证坐标与城市是否匹配;单写一个参数描述不会自动补上这些检查。

源码定位:MethodToolCallbackProvider:方法发现与回调构建。

源码定位:JsonSchemaGenerator:参数类型、描述与必填信息。

第一轮模型请求与工具选择:模型决定调用什么

处理链末端的 ChatModelCallAdvisor 调用 chatModel.call(prompt)。AnthropicChatModel 将通用消息和工具定义转换为 Anthropic SDK 请求;工具参数说明进入结构化的 tools[].input_schema,不是简单拼成一段用户文本。

模型可能根据用户的问题,返回两次 getTemperature 调用。下面是其中一次调用的示意:

code
{
  "type": "tool_use",
  "id": "call_amsterdam",
  "name": "getTemperature",
  "input": {
    "latitude": 52.3676,
    "longitude": 4.9041,
    "city": "Amsterdam"
  }
}

经纬度是模型填写的。本例没有地理编码工具,不能把这一步描述为程序已经从地图服务验证了坐标。城市、坐标和工具调用 ID 都是用于解释的示例。

模型也可能先查一个城市,下轮再查另一个;可能输出说明文字后请求工具,也可能直接回答。.tools(...) 提供能力,不代表强制调用;当前业务代码没有设置必须使用工具的选项。

源码定位:AnthropicChatModel:请求创建、工具格式转换与响应解析。

JSON 参数如何变成一次 Java 方法调用

供应商响应先被转换为 Spring AI 的 AssistantMessage.ToolCall,包含调用 ID、类型、工具名称与 JSON 参数。ToolCallingAdvisor 判断到存在工具调用后,将其交给 ToolCallingManager.executeToolCalls(...)。

默认管理器按工具名在当前请求的回调列表中查找,随后执行 toolCallback.call(arguments, toolContext)。对于方法工具,进入 MethodToolCallback:

code
// 简化后的执行顺序。
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 程序再动态编译,模型也没有获得任意执行应用方法的入口。

源码定位:MethodToolCallback:JSON 解析、参数转换与反射调用。

源码定位:DefaultToolCallingManager:按名称查找和执行工具。

天气 HTTP 请求与返回值:当前气温不是全天预报

RestClient 发起同步 GET 请求,将纬度和经度填入 URL;retrieve() 使用响应提取与默认错误状态处理,body(WeatherResponse.class) 读取响应并转换为 Java 对象。

code
https://api.open-meteo.com/v1/forecast
    ?latitude=52.3676
    &longitude=4.9041
    &current=temperature_2m

关键是 current=temperature_2m:本例读取当前的两米高度气温。接口路径虽然是 forecast,但代码没有请求当天的逐小时气温、最高最低温、降雨或风速。当前天气数据基于天气模型,也不等于保证返回某个现场传感器的即时实测值。

请求没有指定 timezone,接口默认采用 GMT/UTC;Java 的 LocalDateTime 又不保存时区,不能把它直接当作城市当地时间。这些接口含义见 Open-Meteo 官方文档。

数据支持到哪里,回答就应到哪里

工具能够支撑“当前气温下适合穿什么”的判断;如果回答进一步断言下午下雨或晚上会降到某个温度,当前工具没有提供这类数据。

工具结果怎样返回模型:调用 ID 与消息历史的作用

WeatherResponse 是 JVM 对象,需要经过 DefaultToolCallResultConverter 序列化为 JSON 字符串。管理器再将调用 ID、工具名和结果放入 ToolResponseMessage.ToolResponse。

code
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:一次业务请求为何会请求模型多次

code
// 解释控制流程的简化逻辑。
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:循环、后续处理链与直接返回分支。

注释掉 ToolCallingAdvisor 为什么仍然能工作

code
// .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 内部执行循环的说明。官方文档可用于了解整体架构,精确方法与默认值以匹配依赖版本的源码为准。

源码定位:DefaultChatClient:自动注册和工具 Advisor 数量校验。

MyLoggingAdvisor:日志为什么能看到中间轮次

MyLoggingAdvisor 实现 BaseAdvisor,由默认模板依次执行 before、后续处理链和 after。当前实现仅输出日志,然后原样返回对象。

code
// 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 注解就自动获得这些能力。

code
@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 与模型代理路由。因此实际链上可能还有观察整轮请求和每轮模型请求的步骤。观察扩展不负责实现天气工具,也不改变模型提出请求、本地执行工具这一分工。

源码定位:DefaultToolExecutionExceptionProcessor:默认错误处理。

从演示走向实际使用:数据能力决定建议范围

用户问题与当前工具的差别
需求当前能力更可靠的补充
城市是否定位准确模型填写经纬度地理编码查询及城市与坐标校验
今天全天怎么穿当前气温当地当天的逐小时或最高最低温
需不需要防雨未查询降雨降雨概率、降水量及对应时段
风大是否体感冷未查询风力与体感风速、阵风与体感温度
今天按哪一天计算未明确城市时区明确地点时区、查询日期和有效时间
服务失败怎么办依赖默认异常处理明确超时、有限重试和可解释的失败结果

这些补充不是完成工具调用演示的前提,但决定了它能否成为可靠的穿衣建议功能。工具描述越清楚,模型越容易正确选择;输入校验和异常处理越明确,应用越容易控制实际执行结果。

如果工具以后涉及付款、删除或写入数据,还需要在应用侧控制可用工具和执行条件。模型提出调用不等于业务操作天然获得授权。

按调用顺序读源码:一份可以直接跟进的断点清单

建议阅读与断点位置
顺序源码位置重点观察
1DefaultChatClientRequestSpec.tools工具对象如何变成回调
2MethodToolCallbackProvider.getToolCallbacks方法、对象、定义如何绑定
3autoRegisterToolCallingAdvisor没有手动添加时的自动注册
4DefaultCallResponseSpec.content终端取值如何启动执行链
5ToolCallingAdvisor.adviseCall每轮请求及消息累积
6MyLoggingAdvisor.before / after本轮原始文字和工具请求
7AnthropicChatModel.internalCall供应商请求与响应转换
8DefaultToolCallingManager.executeToolCalls工具名称查找与执行顺序
9MethodToolCallback.callJSON 参数到 Java 参数的转换
10WeatherTools.getTemperature天气请求和实际返回值

调试时先确认 IDE 附加的 sources.jar 与运行的依赖版本相符。先看工具定义,再看第一次工具调用响应,再看本地执行和第二轮消息,就能把这段链式 API 与真实执行过程对应起来。

总结归纳

阅读这段示例时,先把工具定义与本地执行分开,再把一轮业务请求与多轮模型调用分开。前者解释模型如何知道能做什么,后者解释为什么查询完天气还要再问一次模型。

沿着 tools → MethodToolCallbackProvider → ToolCallingAdvisor → AnthropicChatModel → ToolCallingManager → MethodToolCallback → WeatherTools 的顺序看源码,便能对齐整个过程。真正用于穿衣建议时,下一步应补齐地点、时区和天气指标,再明确超时、失败处理与输入校验。

参考资料

  1. Spring AI · Tool Calling

    用于理解工具定义、应用负责执行和 Advisor 循环的整体关系。参考页会随版本更新,具体实现与默认值以本文核对的 2.1.0-M1 源码为准。

  2. DefaultChatClient · v2.1.0-M1

    call 与 content 的执行时机、工具注册、自动注册工具 Advisor。

  3. ToolCallingAdvisor · v2.1.0-M1

    多轮循环、后续处理链复制、直接返回与次数超限处理。

  4. MethodToolCallbackProvider · v2.1.0-M1

    查找 @Tool 方法并绑定定义、执行对象与转换器。

  5. JsonSchemaGenerator · v2.1.0-M1

    工具参数 Schema 的类型、描述与 required 生成。

  6. DefaultToolCallingManager · v2.1.0-M1

    按名称执行工具、调用次数限制、消息历史拼装。

  7. MethodToolCallback · v2.1.0-M1

    JSON 解析、Java 参数转换、反射调用和结果转换。

  8. AnthropicChatModel · v2.1.0-M1

    模型供应商 SDK 请求、tool_use 与 tool_result 的映射。

  9. ChatClientAutoConfiguration · v2.1.0-M1

    prototype Builder 和容器内工具管理器配置。

  10. DefaultToolExecutionExceptionProcessor · v2.1.0-M1

    工具异常返回模型或重新抛出的具体条件。

  11. Open-Meteo · Weather Forecast API

    当前气温、天气变量和默认时区的接口定义。

  12. VoxxedDays 2026 Spring AI Demo

    示例项目来源;本文以本次核对的本地 08-tools、common 与 Inspector 源码为准,上游内容可能继续变化。

  13. DefaultChatClientBuilder · v2.1.0-M1

    创建 ChatClient,以及默认 Advisor 如何写入请求配置。