Spring AI 2.0 工具调用实战：动态注册、上下文传递与参数解析-北京尧图网络

你有没有遇到过这种情况同一个助手上午还好好的下午把多租户接进去之后模型开始把 A 用户的订单数据回给 B 用户或者工具明明已经定义好了模型却死活不调用一问就是“参数没给全”我在把 SpringAI 2.0 的 Tool Calling 接入真实业务时前两周基本就在跟这类问题搏斗工具集太死、请求上下文传不进去、参数模型绑不上。后来把动态模式、ToolContext 和隐式解析这三件事彻底吃透工具调用才算真正从“能跑”变成“能上线”。这篇文章我不想做 API 罗列而是想把这轮实战里踩过的设计决策、代码写法和排查过程完整梳理一遍。如果你已经在 Spring AI 里跑通过最简单的Tool方法但一碰到多租户、权限隔离、复杂参数、异步调用就头大那这篇应该能帮你省不少时间。1. 先理清楚Spring AI 2.0 的工具调用瓶颈不在“能不能调”而在“用得对不对”1.1 一个让 Tool 瞬间暴露的场景订单查询里的“用户隔离”先说我最开始写的版本。它看起来非常标准Service public class OrderToolService { Tool(description 根据订单号查询订单详情) public Order queryOrder(String orderId) { return orderMapper.findByOrderId(orderId); } }单测能过模型也能正确返回“你的订单 XX 正在配送中”。但只要把相同接口暴露给真实用户问题就来了方法里根本没有当前用户的概念模型只要编出一个订单号服务端就会把任何人的订单查出来。有朋友会反驳那我给queryOrder加一个userId参数让模型从对话里提取不就行了你试一次就知道有多难受。模型不一定能从“帮我看看上周买的那个耳机到哪了”里推出 userId就算能推到也是基于用户自己说的话服务端根本没有办法验证这个 userId 是不是当前登录用户。一个没有任何可信来源的鉴权参数还不如不要。1.2 所谓“进阶”其实是在解决三个问题把需求拆开看真实业务中的 Tool Calling 其实有三个层次用哪些工具应该在请求级别动态决定。管理员能调删除接口普通用户不能A 租户不能看到 B 租户的统计工具。这不是工具方法内部做if/else能解决的因为模型已经看到了工具 schema它就会去尝试调用。调用时的身份、租户、链路信息不能依赖模型生成而是由服务端直接注入到执行链路里。也就是工具方法需要的上下文要从请求里带进去而不是从模型返回的 JSON 里带进去。工具参数的解析不能把所有类型都退化成 String 手动处理。模型生成的参数是 JSON怎么可靠地绑到 Java 对象上这就是隐式解析要做的事。Spring AI 2.0 的 Tool Calling 真正值钱的地方就在于这三件事都有对应的机制动态模式、ToolContext、隐式解析。我下面逐个说。2. 动态模式在请求级别决定“模型能看到哪些工具”2.1 不能等到方法执行时才做权限校验一开始我的思路是把工具都注册进去在工具方法里判断当前用户有没有权限没有就返回“无权限”。这个思路不能说完全错但隐患很大。第一个问题是工具数量膨胀。用户相关的工具有二十个管理后台工具也有二十个全部塞给模型模型选择准确率会肉眼可见地下降。这种下降不是模型变笨了而是工具之间的 description 太接近模型很容易选出相似但不正确的那个。第二个问题是安全。就算方法内部有校验模型已经拿到了工具定义恶意用户通过 prompt 注入或者其他方式诱导模型调用一个不该调的工具服务端虽然最终会拦住但拦截前已经发生了多余的解析和调用尝试。真正靠谱的做法是让模型从头到尾就看不到没有权限的工具。2.2 基于当前用户动态组装 ToolCallback 列表Spring AI 里有一个很实用的工厂方法ToolCallbacks.from(...)它可以把任意 Spring Bean 里带Tool注解的方法在运行时转换成ToolCallback列表。这就让“动态组装工具”变得非常自然。下面是我这边一个简化后的实现思路Service public class AiChatController { private final ChatClient chatClient; private final OrderToolService orderToolService; private final AdminOrderToolService adminOrderToolService; PostMapping(/chat) public String chat(RequestBody UserChatRequest request, RequestHeader(X-User-Id) String userId, RequestHeader(X-Tenant-Id) String tenantId) { LoginUser user userService.getLoginUser(userId, tenantId); ListToolCallback tools new ArrayList(); // 所有登录用户都能查自己的订单 tools.addAll(ToolCallbacks.from(orderToolService)); // 只有管理员能强制改订单状态 if (user.hasRole(ADMIN)) { tools.addAll(ToolCallbacks.from(adminOrderToolService)); } // 免费版不放开导出工具 if (!free.equals(user.plan())) { tools.addAll(ToolCallbacks.from(exportToolService)); } return chatClient.prompt() .system(你是订单助手只能使用可用工具不要编造订单状态。) .user(request.message()) .tools(tools) .call() .content(); } }注意几个细节ToolCallbacks.from(orderToolService)会把OrderToolService类中所有Tool方法注册成ToolCallback。如果这个类里有一些内部方法不希望暴露给模型就一定不要加Tool。工具是按用户请求动态组装的不是启动时定死的。这看起来只是代码位置换了但模型收到的 tools JSON Schema 完全不同。ChatClient.prompt().tools(...)未必是你那个版本唯一的入口有些版本习惯在ChatClient.builder().defaultTools(...)里配但动态思路是一样的把工具列表当作请求级参数而不是全局配置。动态模式下服务端依然要做二次校验。工具列表只是减少暴露面不能替代工具方法内部的租户/用户校验。ToolContext 可以让校验数据可靠地进到方法里这点下一节展开。2.3 动态模式的两种常见形态我后来把动态模式总结成两种形态**形态一按权限动态装配工具实例。**就是上面代码写的方式一个业务模块对应一个带Tool方法的 Service在入口处根据登录用户、套餐版本、租户配置决定要不要把整个 Service 注册进去。优点是代码直观适合颗粒度比较粗的权限控制。**形态二用一个“路由工具”做内部二次分发。**当工具数量非常大比如超过四十个可以让模型先调用一个routeTool工具方法内部拿到请求上下文后再决定交给哪个业务模块。这种方案能缓解模型在大量工具间做选择的压力代价是调试链路变长而且路由工具本身的设计必须非常稳。我个人的建议工具数量在二十个以内优先用形态一简单、可观测、好排查超过三十个再考虑路由工具不要一上来就搞复杂的路由层。2.4 动态模式的成本每个工具都要知道自己的“适用边界”动态模式有个隐藏成本就是每个模块的方法必须写清楚“什么场景用”否则模型还是会乱选。比如Tool(description 查询当前用户订单列表适合用户询问我的订单/快递到哪/买了什么等场景参数 status 不传表示查全部。) public ListOrder queryMyOrders(String status, ToolContext toolContext) { // ... }description 写得好不好直接决定模型在相似工具之间的选择质量。我见过很多项目花大量时间调 prompt却不愿意在工具的 description 上多写两句这是典型的本末倒置。3. ToolContext把“模型不该知道但工具必须知道”的东西传进去3.1 ToolContext 在工具链路里的位置Spring AI 的ToolContext从设计上看就是一个MapString, Object的封装但它承担了一个很关键的任务让工具方法在执行时能拿到调用方上下文里的数据同时这些数据又不会出现在发送给模型的工具参数 JSON Schema 里。换句话说模型看到的工具定义是queryMyOrders(String status)但真正执行时方法还可以额外拿到ToolContext里面装着 userId、tenantId、requestId 这些由服务端塞进去的信息。这就像你去柜台办业务窗口上写的办理要求只是“出示取件码”但柜员电脑系统里其实已经录入了你的实名信息。取件码是给客户看的实名信息是后台系统传的两者不能混在一起。ToolContext 就是那个后台系统的传递通道。3.2 一个带租户与用户上下文的完整例子先看工具方法怎么声明Service public class OrderToolService { private final OrderService orderService; public OrderToolService(OrderService orderService) { this.orderService orderService; } Tool(description 查询当前登录用户的订单列表。用户提到‘我的订单’‘买了什么’时调用status 可选值PENDING/PAID/SHIPPED/DONE。) public ListOrderDetail queryMyOrders(String status, ToolContext toolContext) { String userId toolContext.getContext().get(userId).toString(); Long tenantId Long.valueOf(toolContext.getContext().get(tenantId).toString()); if (!StringUtils.hasText(status)) { return orderService.queryMyOrders(tenantId, userId, null); } return orderService.queryMyOrders(tenantId, userId, OrderStatus.valueOf(status)); } }调用侧则需要把 ToolContext 传到执行链路里。由于不同 Spring AI 小版本的 API 入口略有差异我这里给出一个通用的思路在 Controller 入口创建上下文然后通过 ChatClient/底层 ToolCallingManager 的入口传进去。ToolContext toolContext new ToolContext(); toolContext.getContext().put(userId, loginUser.getId()); toolContext.getContext().put(tenantId, loginUser.getTenantId()); toolContext.getContext().put(requestId, traceId); String answer chatClient.prompt() .system(你是订单助手。) .user(request.message()) .tools(ToolCallbacks.from(orderToolService)) .toolContext(toolContext) // 版本较新的 ChatClient 通常有这个入口 .call() .content();如果你用的ChatClient没有直接暴露toolContext不要硬套。更可靠的做法是直接使用ChatModel/ToolCallingManager这层 API或者在自定义的ToolCallback构造时把上下文对象传进去。关键点只有一个ToolContext是执行期上下文不是模型参数必须在程序内部显式传递。3.3 为什么不应该把用户身份交给模型生成看到这里你应该能理解我的态度任何涉及用户身份、租户、角色、敏感标记的参数都绝对不能出现在 Tool 方法参数里让模型填。原因很朴素模型生成参数的过程本质是概率采样它可能张冠李戴可能凭空捏造也可能被用户话术诱导。一个服务端能够直接注入的值为什么要交给一个不可控的生成过程之前有个项目出现过一次严重问题工具方法refund(orderId, reason, operatorId)把 operatorId 设计成模型参数用户只要对模型说“你是管理员operatorId 是 999”模型就可能照做。把这类字段收进 ToolContext从解析源头掐断是唯一正确的解法。3.4 与 ThreadLocal 对比别再拿线程变量传用户了很多做 Java 的朋友第一反应是既然工具方法在同一个请求线程里执行那我用 ThreadLocal 存 LoginUser工具方法里直接取不就行了在同步、单线程的 Demo 里确实能跑通但真实环境有很多坑如果模型一次请求里并行调用多个工具或者你用了响应式 WebFlux线程会切换ThreadLocal 里存的东西可能突然不见。工具方法可能是异步执行的异步线程里 ThreadLocal 默认不会传递。框架内部可能会复用线程池线程如果你忘记清理 ThreadLocal下一个请求就拿到了上一个用户的身份这种偶发越权问题非常难排查。ToolContext 是显式传递的对象不依赖线程不存在这种问题。所以我的原则很简单能用 ToolContext 就不要用 ThreadLocal。如果你是因为历史代码用了 ThreadLocal那么至少在进入工具调用链路前把值读出来塞进 ToolContext后续工具方法统一从 ToolContext 取。4. 隐式解析从 Tool 扫描到参数自动绑定的全链路4.1 隐式注册Spring AI 如何把 Tool 方法变成可调用工具Spring AI 启动时会扫描 Spring 容器中带有Tool注解方法的 Bean把它们包装成ToolCallback再交由 Tool Calling 执行器统一管理。也就是说在最简单的情况下你什么都不用做只要保证工具类是一个被 Spring 管理的 Bean工具方法上加了Tool它就会被隐式注册进可用工具列表。这也是很多人第一次跑通 Spring AI 时觉得“很神奇”的原因明明没有手动往 ChatModel 里塞 tools模型却知道调用那个查询方法。隐式注册很方便但它和动态模式天然存在冲突隐式注册会把所有 Tool 方法向所有请求暴露没法做请求级隔离。所以你要在项目层面明确一个选择内部工具、低风险工具可以用隐式注册省事。涉及用户数据、租户数据、写操作、高权限操作的工具应该用显式动态注册并配合服务端权限校验。不要图省事把所有工具都隐式注册了然后又想办法在工具方法里做一堆权限判断那样只会让问题变得更加隐蔽。4.2 参数隐式绑定模型返回的 JSON 如何变成 Java 对象工具调用真正执行时模型会返回一个结构里面包含工具名和一段 JSON 格式的参数。Spring AI 拿到这个 JSON 后会根据目标方法的参数列表逐个绑定Tool(description 查询当前用户订单支持按状态和分页过滤。) public PageResultOrderDetail queryMyOrders(OrderPageQuery query, ToolContext toolContext) { // query 由框架自动解析 }这里记录了一个稍微复杂一点的入参类型public record OrderPageQuery( ToolParam(description 订单状态支持多个PENDING/PAID/SHIPPED/DONE) ListString status, DateRange createdTime, Integer pageNum, Integer pageSize ) { } public record DateRange(String start, String end) { }模型生成的参数 JSON 大概是这样的{ status: [PAID, SHIPPED], createdTime: { start: 2025-01-01, end: 2025-02-01 }, pageNum: 1, pageSize: 20 }Spring AI 会根据方法签名里的泛型和嵌套结构把 JSON 自动反序列化成OrderPageQuery对象。工具方法里不用手动解析 JsonNode也不用往方法里塞 Map 再自己 get。4.3 枚举、嵌套对象和时间类型怎么处理参数绑定的过程并不是所有类型都能无脑映射我在实际项目里总结了几条经验枚举类型优先用字符串描述。如果方法参数是OrderStatus status模型生成的 JSON 里写SHIPPED默认可以映射到对应枚举常量。但如果模型返回了shipped或已发货就会映射失败。所以我会在ToolParam的 description 里写清楚“只接受这些值PENDING/PAID/SHIPPED/DONE”让模型生成时不要自由发挥。时间类型一定要说清格式。模型生成2025-02-01 12:00:00还是2025-02-01T12:00:00Z取决于你给它的 schema 和描述。如果工具方法里用的是LocalDateTime最好在工具描述里明确写 “ISO-8601 格式例如 2025-02-01T12:00:00” 这种范例否则很容易出现解析异常。实在不行就在工具方法入口接 String自己再转一次保证稳定。复杂对象优先用 Java record。record 的构造器就是参数映射的依据写起来干净也不容易出现反射需要无参构造器之类的问题。如果你用的是普通 class务必要有无参构造器和 setter否则某些反序列化实现会报错。不要为了给模型少传参数而写一个巨大的 DTO。DTO 字段越多模型越容易漏生成或者乱填。理想情况是一个工具方法的“必填业务参数”控制在四五个以内其余信息尽量通过 ToolContext 注入。把工具参数定义得越“像一份给外包开发看的接口文档”模型调用工具的准确率就越高。这一点没有任何技巧可以绕过。5. 进阶实战中最容易踩的坑含排查思路5.1 工具调用的失败排查链路如果你的 Spring AI 工具调用“偶尔成功、偶尔不调用”或者干脆报参数解析错误我建议不要急着改 prompt先按下面这条链路排查。第一步确认模型到底收到了哪些工具定义。打开调用链路的 debug 日志看发给模型的 messages 里 tools 字段是不是完整。之前遇到过一个案例工具方法加了Tool但所在 Service 没有被 Spring 扫描到隐式注册失效模型当然一直说“我没有这个功能”。这类问题看日志最快。第二步确认模型返回的 tool call 参数是不是合法 JSON。模型偶尔会返回类似{status: PAID, status: SHIPPED}这种重复键或者少了结尾括号的 JSON。如果你的版本对 JSON 容错不够就会解析失败。可以在工具调用入口加一段日志把原始 tool call 的输入打出来。第三步确认 Java 端反序列化是否正常。报错信息里如果出现Cannot construct instance基本就是类型不匹配。检查枚举值是否严格一致、时间格式是否统一、自定义 DTO 是否有可用的构造/反序列化方式。我强烈建议把参数对象设计成简单的 record线上真的能少一大半问题。第四步确认方法是不是被正确调用。如果日志显示模型已经请求调用某个工具但业务方法没有执行可能是 ToolCallback 注册的 name 和方法实际 name 不一致。Spring AI 默认会拿方法名作为工具名但你手动注册或者给 Tool 指定了 name 时要保证两边一致。5.2 动态模式下最容易漏掉的一环错误也要“结构化”工具方法执行失败时如果直接抛异常异常信息可能会被模型当成上下文最后生成一段看起来很合理但完全不可信的回复。我现在的做法是在工具方法内部捕获业务异常返回一个结构化的错误字符串让模型明确知道“操作没成功”。比如Tool(description 取消订单) public String cancelOrder(String orderId, ToolContext toolContext) { try { orderService.cancel(orderId, currentUserId(toolContext)); return {\success\:true,\message\:\订单已取消\}; } catch (OrderNotCancelableException e) { return {\success\:false,\error\:\订单当前状态不允许取消\,\reason\:\ e.getMessage() \}; } }这样模型会把错误信息如实组织语言告诉用户而不会脑补出一个“取消成功”。如果你用显式注册的 방식甚至可以在自定义 ToolCallback 里统一包一层 catch记录耗时并把异常转成结构化文本。这对线上可观测性也有很大帮助。5.3 工具命名与描述模型不调用很多时候不是模型问题工具会不会被调用60% 取决于 description 写得好不好。同一个能力你写查询订单接口和写当用户想了解自己购买的商品的物流、状态、发货情况时调用参数 orderId 是订单号可以从用户消息中提取模型的调用率完全不在一个量级。另外要注意工具名冲突。隐式注册如果发现两个 Bean 里有同名 Tool 方法注册阶段往往不会直接报错但真正调用时会匹配不到正确的那个。我给工具命名通常带业务前缀比如order_query、order_cancel、refund_apply而不是简单写query、cancel。工具名在模型面前是“可读文本”起得没有区分度模型选错是必然的。5.4 事务、线程与上下文传播的最后提醒工具方法如果涉及数据库事务请把Transactional加在工具方法本身或工具方法内部的 Service 方法上而不是加在“整个 ChatModel 调用”的外层方法上。模型交互可能持续好几秒你不可能让一个数据库事务跨越模型输出、工具解析、方法执行、结果返回再二次生成的全过程。另外一个建议是所有工具方法在执行前都从 ToolContext 里重新取一次 userId、tenantId不要依赖构造时捕获的变量。同一套工具代码可能在动态模式下被多个请求复用如果工具类持有上一次请求的用户状态就成了一个定时炸弹。ToolContext 是请求级的工具方法本身尽量无状态这条约定能避免很多偶发问题。把动态模式、ToolContext、隐式解析放在一起看它们其实是同一条设计原则的三面让工具列表、调用上下文、参数解析都变成程序可控制的东西而不是把所有不可控信息都丢给模型去猜。我个人建议在项目里先别急着把几十个工具全部隐式注册而是从“显式 ToolCallback 动态注册 ToolContext 传租户和用户简单 record 参数”这套组合开始跑等模型调用稳定了再逐步把低风险工具切到隐式解析。工具调用这条路跑通 Demo 只是起点把边界划清楚才是真正能上线的分水岭。

Spring AI 2.0 工具调用实战：动态注册、上下文传递与参数解析

相关推荐

Spring AI vs Spring AI Alibaba：技术选型与平滑迁移策略

C语言入门到实践：环境配置、核心语法与项目应用全攻略

Opencode：基于npm的本地化AI编程代理工具

更多资讯

Boring Notch 安装指南：3 步搞定未识别开发者弹窗

CMAC算法的各种密码分析方法全面盘点

CRC-MAC算法的各种密码分析方法全面盘点

Linux --进程信号

5 分钟跑通 Locale-Emulator：让任意程序以你想的语言启动

Folia 歌词动画播放器安装教程：Windows、macOS、Linux 全覆盖，3 分钟一次跑通

今日更新

多智能体协作系统架构设计与实践优化

大模型系统性入门实战指南：从原理到部署微调的全链路路线

鸿蒙文件系统沙箱机制解析与开发实践

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？