一个绕不开的问题你在用 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
一个绕不开的问题你在用 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
