工具调用:把 Java 方法暴露给模型
本篇要点:能让模型按你写的描述选对 Java 方法、按你的校验规则传参,并且调不动它不该调的东西。前置:《结构化输出:让模型稳定返回对象》已经把模型输出收敛成对象,这一章把"让它返回对象"换成"让它要求执行方法"。
1 为什么需要它:模型把订单状态编了出来
去年冬天客服群里最常出现的一句话是"这个答复不对,订单还在路上"。
线上是这么发生的:用户问"我的订单 SO202611160001 到哪了",助手答"已签收,昨天下午送达"。真实状态是分拣中,包裹离用户还有 800 公里。模型没有说谎,它只是没见过这张单——订单状态在 MySQL 里,不在训练数据里,也不在《结构化输出:让模型稳定返回对象》那个 JSON 契约里。
想补上这块数据,能走的路只有三条。
把订单表导出成文本塞进提示词。一天几十万单,塞不下;就算塞得下,塞进去的是几小时前的快照,用户问的恰恰是"现在在哪"。
让模型写 SQL。听起来聪明,实际是灾难:它写 select * from orders 忘了 where,写了 update 忘了加条件,你还得给这个连接一个能改数据的账号。
让模型"说要调什么",由应用去执行。模型输出结构化的一段 {"name":"queryOrder","arguments":{"orderNo":"SO202611160001"}},JVM 接到之后调用你自己的 OrderQueryService,再把结果喂回去让模型组织人话。这就是工具调用(tool calling,也叫 function calling)。
第三条路的关键在于分工:模型只有"点菜权",没有"下厨权"。这一章大部分内容都在讲,把执行权留在 JVM 里意味着你要多做哪几件事。
2 核心概念
2.1 工具的两副面孔:ToolDefinition 和 ToolCallback
定义:ToolDefinition 是名字、描述、输入 JSON Schema 三件套,给模型看;ToolCallback 是同一份说明加一段可执行逻辑,给框架调用。两个接口里,模型永远只接触前者。
类比:菜单和厨房。菜单上写"宫保鸡丁,微辣,不要花生",模型只能照着点;真正动锅的是厨房,而且厨房可以拒绝。
反例:把 void deleteAllOrders() 挂上 @Tool(description = "清理订单")。菜单上多这一行,模型某天就会点它,而且它会在一个你没想到的时刻点。
2.2 @Tool 是怎么变成 Schema 的
定义:@Tool 标在方法上,Spring AI 反射方法签名,把参数名、类型、@ToolParam 的描述编译成 JSON Schema,随每次请求一起发给模型。
这一步是单向编译:Java 类型变了,模型看到的东西就变了。参数写成 Map<String,Object>,schema 只有一个宽松的 object,没有任何字段提示,模型只能猜 key 叫什么。
反例:参数全部标成必填,但模型无从得知该填什么。官方文档把这条写得很直白——你标成必填,模型就会编一个值给你。所以"订单号"这种用户可能没提供的参数,要么标 required = false,要么在描述里写清"用户没给订单号时先追问,不要调用"。
描述的作用被低估得厉害。写"订单号"和写"平台订单号,形如 SO + 12 位数字;用户没提供时先追问",后者能砍掉大部分格式错误的重试。
2.3 调用循环:一次请求里可能调两次
模型返回工具请求之后,框架执行、把结果按 tool_call_id 回填、再发回模型;模型如果还要调,就再一轮。这个循环归 ToolCallingManager 管,你在代码里看不到它,但计费和延迟都算在里面。
一轮里模型可以同时要求调用多个工具(并行 tool_calls)。比如"帮我查下这单到哪了,顺便把地址改成公司",它会先发 queryOrder,拿到结果发现还在待发货,再发 updateAddress。这两次调用的先后顺序不由你控制,由模型决定。
边界要说清:这个循环没有天然的次数上限。模型完全可能反复调同一个查询,每次换个参数。生产里必须自己设上限,《批处理与异步:大规模 AI 任务编排》讲批量任务时会给出计数器的写法。
还有一个容易被忽略的成本项:工具列表每轮都要重新发给模型,schema 计入输入 token。挂 40 个工具、每个描述三行,每轮光"菜单"就是几千 token,而这一轮可能只用到其中一个。
2.4 ToolContext:不进模型的那部分上下文
定义:ToolContext 是一个 Map<String,Object>,随请求传进工具方法,但不会出现在发给模型的任何一条消息里。
类比:菜单背面那张写着"3 号桌,金卡会员"的便签。顾客看不见,厨房看得见。
反例:把 tenantId 做成 @ToolParam 让模型填。模型会填错,更糟的是它可能被文档里的某句话说服,填成别人家的租户号。身份只能从登录态取,走 ToolContext。
图 4-1 把一次往返画了出来:模型那一栏只有两个动作,中间的四个检查点全在 JVM 里。
图 4-1 一次工具调用的往返:四个检查点全在应用侧,模型只负责点菜
三种定义方式各有代价,对照如表 4-1。
表 4-1 定义工具的三种方式
| 方式 | 写法 | 适合 | 代价 |
|---|---|---|---|
声明式 @Tool | 方法加注解,对象交给 .tools(...) | 方法在你自己的代码里 | 只能靠改签名表达 schema |
MethodToolCallback | 反射拿 Method,运行时拼 ToolDefinition | 工具类来自三方 jar,或要按租户动态裁剪 | 代码量翻倍,反射错误到运行时才暴露 |
FunctionToolCallback | 给 Function 包一层,inputType 决定 schema | 工具就是一段函数,参数是 record | 泛型擦除后 schema 依赖 inputType,漏写会变成无参工具 |
3 动手实践:查订单、改地址,把边界画出来
3.1 依赖
基线是 Spring AI 1.1.8 + Spring Boot 3.5.15(1.1.8 的 starter 依赖的就是这个版本)。第 2、3 章的示例跑在 2.0.2 + Spring Boot 4 上,从这一章起回到 1.1.x,和《MCP Server:让模型安全调用 Java 业务能力》的 MCP 基线对齐;《MCP Server:让模型安全调用 Java 业务能力》会把这里的工具搬到协议层。
截至 2026 年 11 月,官方主线已到 2.0.2,2.1.0 还在 RC。2.0 把工具循环从各 ChatModel 内部搬进 ToolCallingAdvisor,删掉了按名字解析裸 Function bean 的 SpringBeanToolCallbackResolver,并给 ToolCallingManager 加了单工具与总量的调用上限。本篇用到的 @Tool、@ToolParam、ToolContext、ToolCallbackProvider 两代都还在。
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.5.15</version>
</parent>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-bom</artifactId>
<version>1.1.8</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.ai</groupId>
<artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
</dependencies>3.2 工具类:描述、校验、身份、超时
package top.mqxu.ai.tools;
import org.springframework.ai.chat.model.ToolContext;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;
import org.springframework.stereotype.Component;
import java.util.List;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;
@Component
public class OrderQueryTools {
private final OrderQueryService orderQueryService;
// Java 21:每个任务一个虚拟线程,超时后不占用 Tomcat 的工作线程
private final ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();
@Tool(description = """
按订单号查询订单状态与最新物流节点。只读操作。
订单号形如 SO + 12 位数字。用户没有给出订单号时,先追问,不要调用本工具。""")
public OrderStatus queryOrder(
@ToolParam(description = "平台订单号,形如 SO202611160001") String orderNo,
ToolContext toolContext) {
// 业务校验写在方法里,模型只保证 JSON 结构合法,不保证值合法
if (orderNo == null || !orderNo.matches("^SO\\d{12}$")) {
throw new IllegalArgumentException("订单号格式不合法,应为 SO + 12 位数字");
}
String tenantId = (String) toolContext.getContext().get("tenantId");
String userId = (String) toolContext.getContext().get("userId");
Future<OrderStatus> task = executor.submit(
() -> orderQueryService.findForUser(tenantId, userId, orderNo));
try {
return task.get(2, TimeUnit.SECONDS);
} catch (TimeoutException e) {
task.cancel(true);
throw new IllegalStateException("订单查询超过 2 秒,请稍后重试");
} catch (ExecutionException e) {
throw new IllegalStateException("订单查询失败:" + e.getCause().getMessage());
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new IllegalStateException("订单查询被中断");
}
}
@Tool(description = """
查询用户最近 N 笔订单,用于用户说不出订单号时先定位。
只返回订单号、下单时间、状态,不含金额与收货地址。""")
public List<OrderBrief> recentOrders(
@ToolParam(description = "要返回的订单数量,1 到 10,默认 3", required = false) Integer limit,
ToolContext toolContext) {
int n = (limit == null || limit < 1 || limit > 10) ? 3 : limit;
return orderQueryService.recent((String) toolContext.getContext().get("userId"), n);
}
}运行结果(开启 org.springframework.ai 的 DEBUG 日志,节选):
17:22:41.118 INFO ToolCallingManager : tool call: queryOrder {"orderNo":"SO20261116000"}
17:22:41.120 WARN DefaultToolExecutionExceptionProcessor : Tool execution failed: 订单号格式不合法,应为 SO + 12 位数字
17:22:41.664 INFO ToolCallingManager : tool call: queryOrder {"orderNo":"SO202611160001"}
17:22:43.902 INFO ToolCallingManager : tool response: {"orderNo":"SO202611160001","status":"PICKING","lastNode":"杭州转运中心","at":"2026-11-16T09:12:00+08:00"}
17:22:45.310 INFO OrderAssistant : 回答:这单还在分拣,09:12 到了杭州转运中心,预计明天下午派送。第一次调用是模型自己拼的 11 位数字。IllegalArgumentException 的 message 被完整回传给模型,它读到"应为 SO + 12 位数字"之后补了一位重试。四秒左右完成两次模型往返,用户只看到最后那句回答。
3.3 注册:只读常驻,写操作逐次挂载
package top.mqxu.ai.config;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.tool.method.MethodToolCallbackProvider;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration(proxyBeanMethods = false)
public class ToolConfig {
@Bean
ToolCallbackProvider readToolProvider(OrderQueryTools queryTools) {
return MethodToolCallbackProvider.builder().toolObjects(queryTools).build();
}
@Bean
ToolCallbackProvider writeToolProvider(OrderWriteTools writeTools) {
return MethodToolCallbackProvider.builder().toolObjects(writeTools).build();
}
@Bean
ChatClient chatClient(ChatClient.Builder builder,
@Qualifier("readToolProvider") ToolCallbackProvider readToolProvider) {
return builder
.defaultSystem("""
你是售后客服,只回答订单相关问题。
回答前先用工具核对订单真实状态。工具没有返回的信息,直接说查不到,不要推测。""")
// 只读工具常驻;写工具不进默认列表
.defaultTools(readToolProvider)
.build();
}
}上面那个 provider 里的 schema,打出来才是模型真正看到的东西:
运行结果(getToolCallbacks()[0].getToolDefinition().inputSchema() 的输出,字段顺序有调整):
{
"name": "queryOrder",
"description": "按订单号查询订单状态与最新物流节点。只读操作。\n订单号形如 SO + 12 位数字。用户没有给出订单号时,先追问,不要调用本工具。",
"inputSchema": {
"type": "object",
"properties": {
"orderNo": { "type": "string", "description": "平台订单号,形如 SO202611160001" }
},
"required": ["orderNo"]
}
}properties 里只有 orderNo。方法签名里的 ToolContext 被框架剔掉了,永远不进 schema——所以身份信息模型既看不到也改不了,2.4 节那句"身份只能走 ToolContext"在协议层就是这么落地的。
package top.mqxu.ai.service;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.ChatClient.ChatClientRequestSpec;
import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Service;
import java.util.HashMap;
import java.util.Map;
@Service
public class OrderAssistant {
private final ChatClient chatClient;
private final ToolCallbackProvider writeToolProvider;
public OrderAssistant(ChatClient chatClient,
@Qualifier("writeToolProvider") ToolCallbackProvider writeToolProvider) {
this.chatClient = chatClient;
this.writeToolProvider = writeToolProvider;
}
public String ask(String tenantId, String userId, String question, String confirmToken) {
Map<String, Object> ctx = new HashMap<>();
ctx.put("tenantId", tenantId);
ctx.put("userId", userId);
if (confirmToken != null) {
ctx.put("confirmToken", confirmToken); // 只有用户在页面上点过“确认修改”才有
}
ChatClientRequestSpec spec = chatClient.prompt().user(question).toolContext(ctx);
if (confirmToken != null) {
spec = spec.tools(writeToolProvider); // 写工具逐次挂载,不常驻
}
return spec.call().content();
}
}运行结果(confirmToken 非空,写工具已挂载):
17:31:02.004 INFO ToolCallingManager : tool call: queryOrder {"orderNo":"SO202611160001"}
17:31:02.211 INFO ToolCallingManager : tool response: {"status":"PICKING","lastNode":"杭州转运中心"}
17:31:02.602 INFO ToolCallingManager : tool call: updateAddress {"orderNo":"SO202611160001","address":"杭州市西湖区文三路 90 号"}
17:31:02.780 WARN OrderWriteTools : 订单已进入分拣,不能修改地址,orderNo=SO202611160001
17:31:02.781 INFO ToolCallingManager : tool response: {"ok":false,"reason":"已进入分拣"}
17:31:05.020 INFO OrderAssistant : 回答:这单 09:12 已经进分拣了,现在改不了地址。等派送的时候联系快递员改,或者签收后退回。一次请求两次工具调用,第二次是模型看到第一次结果之后自己决定的。写工具在方法内部又挡了一次——状态不是"待发货"就拒绝。模型给了错误前提,工具不该配合。
3.4 埋点:包一层 ToolCallback
框架不区分你调了哪个工具,要按工具看耗时和失败率,就得自己包。注意两个 call 都要覆写,这点后面会讲为什么。
package top.mqxu.ai.tools;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.chat.model.ToolContext;
import org.springframework.ai.tool.ToolCallback;
import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.tool.definition.ToolDefinition;
import org.springframework.ai.tool.metadata.ToolMetadata;
import org.springframework.ai.tool.method.MethodToolCallbackProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.util.Arrays;
@Configuration(proxyBeanMethods = false)
public class ToolObservabilityConfig {
private static final Logger log = LoggerFactory.getLogger(ToolObservabilityConfig.class);
record TimedToolCallback(ToolCallback delegate, MeterRegistry registry) implements ToolCallback {
@Override
public ToolDefinition getToolDefinition() {
return this.delegate.getToolDefinition();
}
@Override
public ToolMetadata getToolMetadata() {
return this.delegate.getToolMetadata();
}
@Override
public String call(String toolInput) {
return invoke(toolInput, null);
}
// 少了这个覆写,ToolContext 会被接口默认实现吞掉,鉴权参数全变 null
@Override
public String call(String toolInput, ToolContext toolContext) {
return invoke(toolInput, toolContext);
}
private String invoke(String toolInput, ToolContext ctx) {
String name = this.delegate.getToolDefinition().name();
Timer.Sample sample = Timer.start(this.registry);
try {
String result = this.delegate.call(toolInput, ctx);
sample.stop(this.registry.timer("ai.tool.calls", "tool", name, "outcome", "ok"));
log.info("tool={} args={} status=ok", name, head(toolInput));
return result;
} catch (RuntimeException e) {
sample.stop(this.registry.timer("ai.tool.calls", "tool", name, "outcome", "error"));
log.warn("tool={} args={} status=error msg={}", name, head(toolInput), e.getMessage());
throw e;
}
}
private static String head(String s) {
return s.length() <= 120 ? s : s.substring(0, 120) + "...";
}
}
@Bean
ToolCallbackProvider observedReadTools(OrderQueryTools queryTools, MeterRegistry registry) {
ToolCallback[] raw = MethodToolCallbackProvider.builder()
.toolObjects(queryTools).build().getToolCallbacks();
return ToolCallbackProvider.from(Arrays.stream(raw)
.map(cb -> new TimedToolCallback(cb, registry))
.toList());
}
}运行结果:
18:04:11.220 INFO ToolObservabilityConfig : tool=queryOrder args={"orderNo":"SO202611160001"} status=ok
18:04:19.884 WARN ToolObservabilityConfig : tool=queryOrder args={"orderNo":"SO202611170004"} status=error msg=订单查询超过 2 秒,请稍后重试
$ curl -s localhost:8080/actuator/metrics/ai.tool.calls | jq -c '.availableTags, .measurements'
[{"tag":"tool","values":["queryOrder"]},{"tag":"outcome","values":["ok","error"]}]
[{"statistic":"COUNT","value":2.0},{"statistic":"TOTAL_TIME","value":2.437}]写工具那份 provider 照这个写法再包一层就行,两行代码的差别。要注意的只有一处:我第一版只覆写了 call(String)。跑起来之后权限判断永远拿不到 tenantId,日志里多出一行 By default the tool context is not used, override the method 'call(String toolInput, ToolContext toolcontext)',重复了十几次我才注意到。这是接口的默认实现替你做了决定:它把带上下文的调用降级成不带上下文的调用,只在 INFO 级别提一句。
4 常见误解
「描述是写给人看的注释。」实际它是模型的唯一说明书。同一段代码,把描述从"订单号"改成"平台订单号,形如 SO + 12 位数字;用户没给时先追问",格式错误的重试次数会明显下降,追问也会出现在模型该追问的时候。描述写偏了的典型症状是:用户只是寒暄一句"在吗",模型也去调了一次 queryOrder。
「工具返回的字段越全越好,模型自己会挑。」模型不会挑,它会把拿到的都复述给用户。整单 JSON 里带着收件人手机号、身份证后四位、支付流水号,这些东西一旦进了工具结果,就同时进了用户的屏幕和模型供应商的日志。只返回回答问题必需的那几个字段。
「模型会自己判断参数合法。」它只保证 JSON 能解析,不保证值是业务合法的。orderNo 传 11 位数字它照样发过来,金额传负数也一样。校验只有一处能写:工具方法里的第一行。
5 小结
- 工具由两半组成:给模型看的
ToolDefinition,和留在 JVM 里执行的ToolCallback。模型没有直接访问你接口的能力,这一点是工具调用的安全前提。 - 参数的必填与描述直接影响模型行为。标成必填但模型无从得知取值时,它会编一个值。
- 身份走
ToolContext,不要做成参数让模型填。只读工具常驻,写工具逐次挂载,两者用不同的ToolCallbackProvider分开。 - 超时在工具方法里掐,校验在工具方法里做。埋点包一层
ToolCallback时,两个call都必须覆写,否则上下文会在无声的默认实现里丢掉。
6 相关文章
工具解决的是"实时状态",还有一半问题它管不了:政策文档、操作手册、合同条款这些静态知识,不会为一句话变成一张表,也不可能给每个问题写一个工具。
《RAG 落地:向量库、切分与检索》处理这类知识——把文档切碎、向量化、按语义检索,再拼回提示词。你会发现这条路和工具调用最后会合流:VectorStore 也可以包成一个工具,只是大多数时候不必绕这一圈。