1. 从 Demo 到生产满屏 Tool 是怎么把项目拖垮的如果你写过 LangChain4j 的工具调用大概率经历过这个阶段为了让大模型“什么都能干”把订单查询、库存扣减、退款申请、优惠券发放、物流跟踪、发票下载……十几个 Service 方法统统打上Tool注解然后一股脑塞进AiServices。本地跑起来那一刻确实爽模型像个全能助理问什么答什么。但上线两周后问题就来了。我试过在一个客服 Agent 里挂了 28 个工具结果单次请求的 Token 从 800 涨到 4200响应时间从 1.2 秒变成 4.5 秒更离谱的是模型开始“乱点鸳鸯谱”——用户问“我的订单到哪了”它去调了退款接口。排查半天才发现工具描述里“订单”两个字出现了 6 次模型根本分不清哪个是查询哪个是写操作。这就是静态Tool的工程化天花板工具一旦挂载每次请求模型都能看见它你无法根据用户角色、租户、对话阶段做任何收敛。工具列表本质上是权限边界的一部分把它写死在注解里等于把权限控制交给了提示词——而提示词是拦不住越权的。LangChain4j 给出的解法是ToolProvider接口。它不是换种语法写Tool而是把“这次对话该给模型看哪些工具”变成一个运行时决策。你可以根据memoryId查用户角色、根据消息内容判断意图、根据租户 ID 加载专属 API甚至把上百个低频工具丢进向量库做语义检索。下面我把这套方案拆成可复制的骨架从依赖到验证一步步走。2. 前置准备TaoToken 接入与 LangChain4j 依赖对齐在动手写ToolProvider之前得先把模型通道打通。LangChain4j 本身只是编排框架真正跑推理需要接一个兼容 OpenAI 协议的模型服务。我这边用 TaoToken 做统一入口它的 API 地址是https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions格式LangChain4j 的OpenAiChatModel可以直接指过去。先确认你的pom.xml里 LangChain4j 版本。ToolProvider、ToolProviderResult、ReturnBehavior这些类在 0.35 之后的版本才稳定建议用 0.36.x 或更高dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.36.2/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version0.36.2/version /dependency模型配置这块把baseUrl指向 TaoToken 的 API 地址Key 从控制台生成。注意baseUrl结尾不要带/v1LangChain4j 会自己拼路径ChatLanguageModel chatModel OpenAiChatModel.builder() .baseUrl(https://taotoken.net/api) .apiKey(System.getenv(TAOTOKEN_API_KEY)) .modelName(gpt-4o-mini) .temperature(0.2) .build();Key 的获取路径在 TaoToken 控制台的 API Keys 页面生成后建议用环境变量注入别硬编码进代码。如果你还没配好可以先到模型对话页面验证一下通道是否通确认能正常返回再往下走。3. 可复制配置ToolProvider 骨架与动态注册ToolProvider是一个函数式接口签名大致是ToolProviderResult provideTools(ToolProviderRequest request)。request里能拿到memoryId会话标识和userMessage用户消息这两个就是你做动态决策的全部依据。下面这个骨架我抽成了独立 Bean方便在多个 AiService 之间复用。核心思路是先查上下文再按权限和意图往 Builder 里塞工具最后 build 返回。import dev.langchain4j.agent.tool.ToolSpecification; import dev.langchain4j.agent.tool.ReturnBehavior; import dev.langchain4j.service.tool.ToolProvider; import dev.langchain4j.service.tool.ToolProviderResult; Configuration public class DynamicToolConfig { Bean public ToolProvider customerToolProvider(OrderService orderService, RefundService refundService, UserContextHolder contextHolder) { return request - { // 1. 从 memoryId 还原当前用户上下文 UserContext user contextHolder.get(request.memoryId()); ToolProviderResult.Builder builder ToolProviderResult.builder(); // 2. 基础工具所有登录用户都能查订单 ToolSpecification queryOrder ToolSpecification.builder() .name(query_order) .description(根据订单号查询订单状态和物流信息) .build(); builder.add(queryOrder, (toolReq, memId) - orderService.query(toolReq.arguments())); // 3. 权限工具只有 VIP 才暴露极速退款 if (user ! null user.isVip()) { ToolSpecification vipRefund ToolSpecification.builder() .name(vip_fast_refund) .description(为 VIP 用户提交极速退款申请仅限已支付订单) .build(); builder.add(vipRefund, (toolReq, memId) - refundService.applyVipRefund(toolReq.arguments())); } // 4. 阻断工具凭证下载执行后直接返回不让模型二次润色 if (request.userMessage().singleText().contains(下载凭证)) { ToolSpecification receipt ToolSpecification.builder() .name(download_receipt) .description(生成订单凭证下载链接) .build(); builder.add(receipt, (toolReq, memId) - orderService.generateDownloadLink(), ReturnBehavior.IMMEDIATE); } return builder.build(); }; } }几个关键点值得展开。ToolProviderResult.Builder.add()有三个重载只传规格、传规格加执行器、传规格加执行器再加ReturnBehavior。ReturnBehavior.IMMEDIATE是省钱利器——工具执行完直接把结果返回给前端跳过大模型的二次处理。像下载链接、结构化 JSON、敏感数据这类场景让模型“润色”纯属浪费 Token 还容易泄露。UserContextHolder是我自己写的一个基于ConcurrentHashMap的会话上下文容器在用户登录时把UserContext按memoryId存进去。你也可以换成 Redis 或 ThreadLocal看你的会话管理方案。4. 组装 AiService静态工具、动态 Provider 与工具检索的混合光有ToolProvider还不够真实项目里往往是“常驻工具 动态工具 海量低频工具”三者共存。LangChain4j 允许你在AiServices上同时挂.tools()、.toolProvider()和.toolSearchStrategy()它们会合并成最终的可见工具集。Configuration public class AssistantConfig { Bean public CustomerAssistant customerAssistant(ChatLanguageModel chatModel, ToolProvider customerToolProvider, StaticCoreTools staticCoreTools, EmbeddingModel embeddingModel, EmbeddingStoreTextSegment toolStore) { // 向量检索策略把上百个低频工具丢进向量库模型按需语义搜索 ToolSearchStrategy searchStrategy VectorToolSearchStrategy.builder() .embeddingModel(embeddingModel) .embeddingStore(toolStore) .build(); return AiServices.builder(CustomerAssistant.class) .chatModel(chatModel) // 常驻静态工具查时间、汇率换算这类无副作用纯函数 .tools(staticCoreTools) // 动态工具按用户权限和意图实时组装 .toolProvider(customerToolProvider) // 工具检索解决工具基数过大的问题 .toolSearchStrategy(searchStrategy) .build(); } }StaticCoreTools里放的是那种“永远该可见”的工具比如获取当前时间、基础单位换算。这类工具用Tool注解写最省事没必要动态化。而VectorToolSearchStrategy解决的是另一个维度的问题当你的企业有几百个微服务接口时全量暴露不现实框架会只给模型一个“寻找工具”的元工具模型根据用户意图触发向量检索从工具库里捞出最相关的几个再调用。AI Service 接口本身保持干净不需要任何工具相关注解AiService public interface CustomerAssistant { SystemMessage(你是专业客服助理。凭证下载类请求直接调用工具返回不要改写结果。) String chat(MemoryId String userId, UserMessage String message); }5. 验证请求从日志确认工具是否按预期收敛配置写完不能直接信得验证工具列表真的随上下文变化了。最直接的办法是打开 LangChain4j 的请求日志在application.yml里把日志级别调到 DEBUGlogging: level: dev.langchain4j: DEBUG然后写一个测试用例分别用普通用户和 VIP 用户的memoryId发起请求观察日志里tools字段的差异SpringBootTest class ToolProviderTest { Autowired private CustomerAssistant assistant; Test void normalUserShouldNotSeeVipRefund() { String reply assistant.chat(user_normal_001, 帮我查下订单 20241120001); System.out.println(reply); } Test void vipUserShouldSeeVipRefund() { String reply assistant.chat(user_vip_888, 我要退款订单 20241120002); System.out.println(reply); } }实测下来普通用户的请求日志里工具列表只有query_orderVIP 用户会多出vip_fast_refund。如果日志里两个用户看到的工具一样说明UserContextHolder没取到值检查memoryId是否在登录时正确写入。再验证ReturnBehavior.IMMEDIATE的效果。发一条包含“下载凭证”的消息观察响应时间——正常工具调用会经历“模型决策→执行→结果回传模型→模型生成回复”两轮推理而 IMMEDIATE 工具只有一轮。日志里如果看到工具执行后直接返回、没有第二次chat请求就说明阻断生效了。6. 本篇常见错排查报错一NoClassDefFoundError: dev/langchain4j/service/tool/ToolProvider这是版本没对齐。ToolProvider在 0.35 之前叫别的名字升级到 0.36.2 以上即可。如果你用的是 Spring Boot Starter 方式引入注意langchain4j-spring-boot-starter的版本要和核心包一致别一个 0.35 一个 0.36。报错二工具被调用但参数是空的ToolSpecification只写了name和description没定义参数 Schema。模型不知道要传什么参数就会传空对象。正确做法是用.parameters(JsonSchema...)声明参数结构或者干脆用ToolSpecifications.toolSpecificationFrom(Method)从方法反射生成。手写 Schema 容易漏字段建议优先用反射方式。报错三VIP 用户也看不到vip_fast_refund先确认UserContextHolder.get(memoryId)返回的不是 null。常见原因是登录时写入用的memoryId和chat()传入的不一致——比如登录用userId聊天用sessionId。统一用一个标识或者在UserContextHolder里做一层映射。报错四VectorToolSearchStrategy检索不到工具检查EmbeddingStore里是否真的存了工具描述。工具检索依赖预先向量化你得在应用启动时把工具的名称和描述 embed 进去。如果 store 是空的模型搜什么都是空结果。另外 embedding 模型和检索时用的模型必须是同一个否则向量空间对不上。报错五IMMEDIATE 工具执行后模型还是回复了确认ReturnBehavior.IMMEDIATE是加在builder.add()的第三个参数上而不是加在ToolSpecification上。这个行为是执行器级别的不是规格级别的。加错位置不会报错但也不生效。7. 下一步把工具治理当成架构问题走到这里你的 Agent 应该已经能做到“问订单只给订单工具、VIP 才见退款、凭证下载不绕模型”了。但工具治理不止于此。当工具数量继续膨胀你需要考虑的是工具描述怎么版本化不同租户的工具库怎么隔离工具调用失败后的降级策略是什么我的建议是把ToolProvider当成一个“工具网关”来设计它不只是返回工具列表还可以做调用埋点、限流、审计。每次provideTools被调用时记一条日志你就能知道哪个用户在哪次对话里看到了哪些工具、调用了哪个、耗时多少。这些数据反过来能帮你优化工具描述和权限策略。如果你还在用满屏Tool硬扛不妨从下一个新功能开始把它写成ToolProvider里的一个分支。迁移不用一步到位新旧共存完全没问题。等你看到日志里工具列表随用户角色动态变化的那一刻就会明白为什么说“工具列表就是权限边界”。