当 AI Agent 调用工具时，用户 ID 从哪来？——Spring AI ToolContext 传值实战-北京尧图网络

一个绕不开的问题你在用 Spring AI 开发 Agent 应用，一切都很美好——模型能理解自然语言，能自主决定调用哪个工具、传什么参数，直到你遇到了这样一个场景：@Tool(description="查询用户账户余额")StringgetBalance(StringaccountType){returnbankService.getBalance(userId,accountType);// ^^^^^^// 这个 userId 从哪来？}用户 ID 不能让 LLM 填。它属于运行时上下文，是请求进来时应用层已经确定的信息，不应该、也不能让模型来"猜"。类似的场景很多：用户 ID、租户 ID——多租户系统中的安全边界会话 ID——需要关联当前对话上下文权限 Token——工具需要携带鉴权信息访问外部 API请求来源、渠道标识——工具行为需要根据来源差异化这类参数有一个共同特征：它们属于"确定的上下文"，不是 LLM 应该生成的"推理参数"。如果把它们混入工具的输入参数让模型来填，轻则幻觉（模型编造一个 userId），重则越权（模型填了别人的 userId）。Spring AI 提供了ToolContext机制来优雅地解决这个问题。ToolContext 是什么一句话概括：ToolContext 是一个由应用层注入、对 LLM 不可见的键值对容器，在工具执行时自动传递给工具方法。它的核心设计思想：┌──────────────┐ toolContext(Map) ┌──────────────┐ │ Application │ ──────────────────────────▶│ Tool │ │ (应用层) │ userId, tenantId, ... │ (工具方法) │ └──────────────┘ └──────────────┘ ┌──────────────┐ toolInput(参数) ┌──────────────┐ │ LLM │ ─────────────────────▶│ Tool │ │ (大语言模型) │ accountType, ... │ (工具方法) │ └──────────────┘ └──────────────┘LLM 负责填充的：工具的业务参数（如accountType）——模型根据用户意图推理得出应用层负责注入的：上下文参数（如userId）——应用层在调用时确定，透传给工具两条路径，互不干扰。LLM 完全感知不到 ToolContext 的存在，既不会在工具的 JSON Schema 中看到它，也不会试图为它生成值。具体用法Spring AI 提供了两种等价的工具定义方式，都支持 ToolContext：方式一：@Tool注解式——在方法签名中声明 ToolContext将ToolContext作为方法的最后一个参数，Spring AI 会自动注入：classCustomerTools{@Tool(description="查询客户信息")CustomergetCustomerInfo(Longid,ToolContexttoolContext){// 从 ToolContext 中取出应用层注入的租户 IDStringtenantId=(String)toolContext.getContext().get("tenantId");returncustomerRepository.findById(id,tenantId);}@Tool(description="查询账户余额")StringgetBalance(StringaccountType,ToolContexttoolContext){StringuserId=(String)toolContext.getContext().get("userId");returnbankService.getBalance(userId,accountType);}}注意：ToolContext参数对模型是隐藏的。模型只看到id和accountType，不会看到ToolContext。方式二：BiFunctionT, ToolContext, R编程式——函数式定义等价地，用BiFunction定义工具逻辑，第二个参数就是ToolContext：publicclassAccountInfoToolimplementsBiFunctionString,ToolContext,String{@OverridepublicStringapply(Stringquery,ToolContexttoolContext){StringuserId=(String)toolContext.getContext().get("userId");StringtenantId=(String)toolContext.getContext().get("tenantId");if(userId==null){return"用户未登录，无法查询";}returnaccountService.query(userId,tenantId,query);}}// 构建 ToolCallbackToolCallbackaccountTool=FunctionToolCallback.builder("get_account_info",newAccountInfoTool()).description("查询当前用户的账户信息").inputType(String.class).build();两种方式完全等价，选择哪种取决于你的编码风格：注解式更简洁，适合工具逻辑简单的场景编程式更灵活，适合需要复杂构造或复用的场景在调用端注入 ToolContext定义好工具后，在调用时注入上下文数据。根据入口不同，方式略有差异。ChatClient 入口Stringresponse=ChatClient

当 AI Agent 调用工具时，用户 ID 从哪来？——Spring AI ToolContext 传值实战

相关推荐

specs/features/DragAndDrop.spec.md中的测试用例

软件测试|测试环境如何配置

2026年美业门店管理系统深度测评

更多资讯

测序数据可视化：从BAM到bigWig的UCSC工具链实战指南

Simulink与FlightGear联合仿真：飞行器控制算法三维可视化验证平台搭建

Matlab/Simulink与FlightGear飞行器可视化仿真平台搭建指南

BrewUI 详解：macOS 上 Homebrew 的图形化包管理利器

AI芯片设计入门的三道硬门槛：NPU、编译器与验证闭环

反激电源TL431补偿器设计与波特图调试实战

今日更新

OneUptime 自定义探针（Custom Probe）部署实战：私网监控、代理配置与断连排障全指南

大众TL52625前端框架材料要求详解：从性能测试到落地执行

TiXL 浮点运算算子库 Lib.numbers.float 完全指南：44 个算子的参数详解、源码原理与实战串联

本周精选

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

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