当 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年美业门店管理系统深度测评

更多资讯

ONNX Runtime端侧部署三要素：打包、量化与线程治理

Seastar 高性能服务器框架实战指南：从编译构建、构建模式到异步编程工程接入

RubricRL实战：用结构化评分表替代标量奖励的大模型强化学习方案

BlockNote 表格混合列宽的 Markdown 导出：从 columnWidths 到 GFM 快照的完整链路解析

EasyWeChat 6.x 微信开发疑难解答全攻略：从环境配置到平台接入的排坑指南

Higgsfield详解：AI视频生成项目原理、参数调优与实战避坑指南

今日更新

AI元人文：从工具使用到思维重构的深度探索

Python+CNN车牌识别实战：从数据预处理到模型训练与部署

Vim基础操作全攻略：保存退出、模式切换与高频命令实战

本周精选

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

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

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

本月热门

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

分布式服务的决策记录

创业产品的首版范围

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