Skip to content

工具调用:把 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 两代都还在。

xml
<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 工具类:描述、校验、身份、超时 ​

java
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 日志,节选):

text
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 注册:只读常驻,写操作逐次挂载 ​

java
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() 的输出,字段顺序有调整):

json
{
  "name": "queryOrder",
  "description": "按订单号查询订单状态与最新物流节点。只读操作。\n订单号形如 SO + 12 位数字。用户没有给出订单号时,先追问,不要调用本工具。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "orderNo": { "type": "string", "description": "平台订单号,形如 SO202611160001" }
    },
    "required": ["orderNo"]
  }
}

properties 里只有 orderNo。方法签名里的 ToolContext 被框架剔掉了,永远不进 schema——所以身份信息模型既看不到也改不了,2.4 节那句"身份只能走 ToolContext"在协议层就是这么落地的。

java
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 非空,写工具已挂载):

text
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 都要覆写,这点后面会讲为什么。

java
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());
    }
}

运行结果:

text
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 也可以包成一个工具,只是大多数时候不必绕这一圈。