1. Spring AI工具配置概述在构建AI驱动的应用程序时工具调用(Tool Calling)是一个关键功能它允许AI模型与外部系统和服务进行交互。Spring AI 1.x提供了灵活的工具配置机制支持全局默认配置和运行时动态配置两种模式。工具调用的核心价值在于扩展AI模型的能力边界使其能够执行预定义的操作实现与业务系统的无缝集成提供可控的执行环境确保AI行为符合预期Spring AI的工具配置系统设计考虑了以下关键因素声明式与编程式API的平衡配置的继承与覆盖规则执行上下文的管理结果处理的灵活性2. 全局默认工具配置2.1 默认工具的定义方式Spring AI支持三种定义默认工具的方式注解式声明使用Tool注解标记工具方法Component class DateTimeTools { Tool(description Get current date and time) public String getCurrentDateTime() { return LocalDateTime.now().toString(); } }函数式注册通过Function接口定义工具Bean Description(Get weather by location) public FunctionWeatherRequest, WeatherResponse weatherFunction() { return request - weatherService.getWeather(request); }编程式构建使用ToolCallback接口Bean public ToolCallback customTool() { return MethodToolCallback.builder() .name(userLookup) .description(Find user by ID) .toolMethod(ReflectionUtils.findMethod(UserService.class, findById, Long.class)) .toolObject(userService) .build(); }2.2 默认工具的注册机制全局默认工具可以通过以下方式注册ChatClient构建器ChatClient.builder(chatModel) .defaultTools(new DateTimeTools(), weatherFunction) .build();ChatModel配置OllamaChatModel.builder() .ollamaApi(ollamaApi) .defaultOptions(ToolCallingChatOptions.builder() .toolCallbacks(toolCallbacks) .build()) .build();2.3 默认工具的作用域全局默认工具具有以下特点生命周期与创建它们的ChatClient或ChatModel实例绑定对所有通过该实例执行的对话请求可见适合那些在多个对话中需要重复使用的工具注意过度使用全局工具可能导致工具污染问题特别是在多租户场景下。建议仔细评估工具的作用范围。3. 运行时动态工具配置3.1 动态工具绑定方式Spring AI提供了多种运行时绑定工具的方法直接工具实例ChatClient.create(chatModel) .prompt(Set alarm for 10 minutes from now) .tools(new AlarmTools()) .call();工具名称解析ChatClient.create(chatModel) .prompt(Whats the weather in Berlin?) .tools(weatherFunction) .call();动态选项配置ChatOptions options ToolCallingChatOptions.builder() .toolCallbacks(ToolCallbacks.from(new StockQuoteTool())) .build(); new Prompt(Get AAPL stock price, options);3.2 动态工具的优先级当同时存在默认工具和运行时工具时同名工具运行时工具完全覆盖默认工具不同名工具两者都会被保留执行顺序按工具定义的顺序调用覆盖行为示例// 默认工具 ChatClient client ChatClient.builder(chatModel) .defaultTools(new BasicCalculator()) .build(); // 运行时覆盖 client.prompt(Calculate 22) .tools(new ScientificCalculator()) // 覆盖BasicCalculator .call();3.3 动态工具的应用场景动态工具特别适合以下情况临时性工具需求用户特定工具上下文敏感型工具需要隔离的工具执行4. 工具配置高级特性4.1 工具上下文传递Spring AI支持通过ToolContext传递额外上下文信息ChatClient.create(chatModel) .prompt(Get customer details) .tools(new CustomerTools()) .toolContext(Map.of(tenantId, acme-corp)) .call();在工具实现中访问上下文Tool public Customer getCustomer(Long id, ToolContext context) { String tenant context.get(tenantId); return customerRepo.find(id, tenant); }4.2 结果处理控制可以通过以下方式控制工具执行结果的处理直接返回模式Tool(returnDirect true) public Report generateReport(Params params) { return reportService.generate(params); }自定义结果转换器Tool(resultConverter CustomConverter.class) public DataSet queryData(Query query) { return db.query(query); }元数据配置ToolMetadata.builder() .returnDirect(true) .resultConverter(new CustomResultConverter()) .build();4.3 工具输入模式Spring AI支持丰富的参数定义方式参数注解Tool public void placeOrder( ToolParam(description Product ID) String productId, ToolParam(description Quantity, required false) Integer qty ) { // 实现逻辑 }JSON Schema定义ToolDefinition.builder() .inputSchema( { type: object, properties: { location: {type: string}, unit: {type: string, enum: [C,F]} }, required: [location] } ) .build();记录类型public record WeatherRequest( JsonPropertyDescription(City name) String location, JsonProperty(required false) Unit unit ) {}5. 工具执行与生命周期5.1 执行流程控制Spring AI提供了对工具执行流程的细粒度控制执行资格判断Bean ToolExecutionEligibilityPredicate customPredicate() { return (options, response) - { // 自定义判断逻辑 return checkExecutionConditions(); }; }执行管理器Bean ToolCallingManager toolCallingManager() { return ToolCallingManager.builder() .executionEligibilityPredicate(customPredicate()) .build(); }5.2 生命周期钩子可以通过以下方式介入工具生命周期前置处理器Bean ToolExecutionListener preProcessor() { return new ToolExecutionListener() { Override public void beforeExecution(ToolExecutionRequest request) { // 执行前逻辑 } }; }后置处理器Bean ToolExecutionListener postProcessor() { return new ToolExecutionListener() { Override public void afterExecution(ToolExecutionResult result) { // 执行后逻辑 } }; }6. 最佳实践与常见问题6.1 配置策略建议工具组织原则按功能域分组工具区分核心工具与扩展工具使用清晰的命名规范性能优化轻量级工具方法异步执行耗时操作合理使用缓存安全考虑实施权限检查参数验证敏感操作审计6.2 常见问题排查工具未调用检查工具描述是否清晰验证输入模式是否匹配确认工具可见性参数解析失败检查JSON Schema定义验证参数类型确保必需参数已提供执行上下文丢失确认ToolContext正确传递检查线程边界验证序列化/反序列化6.3 调试技巧日志配置logging.level.org.springframework.ai.toolDEBUG诊断端点Spring Boot ActuatorBean Endpoint(id aitools) public ToolRegistryEndpoint toolEndpoint() { return new ToolRegistryEndpoint(); }测试工具Test void testToolExecution() { ToolTester.builder() .tool(myTool) .input({\param\:\value\}) .expectOutput(expectedResult) .verify(); }7. 实际应用案例7.1 电商助手实现Component class ECommerceTools { private final ProductRepo productRepo; private final OrderService orderService; Tool(description Search products by keywords) public ListProduct searchProducts( ToolParam(description Search keywords) String keywords, ToolParam(description Maximum results) int limit ) { return productRepo.search(keywords, limit); } Tool(description Place new order, returnDirect true) public OrderConfirmation placeOrder( ToolParam(description Product ID) String productId, ToolParam(description Quantity) int quantity, ToolContext context ) { String userId context.get(userId); return orderService.placeOrder(userId, productId, quantity); } }7.2 数据分析流程Bean FunctionAnalysisRequest, AnalysisResult dataAnalysisTool() { return request - { // 1. 数据准备 Dataset data dataService.load(request.datasetId()); // 2. 执行分析 AnalysisResult result analyzer.analyze(data, request.parameters()); // 3. 生成报告 return reportGenerator.generate(result); }; } // 配置为默认工具 ChatClient.builder(chatModel) .defaultTools(dataAnalysisTool) .build();7.3 动态工具切换public ToolCallback getContextualTool(User user) { if (user.hasRole(ADMIN)) { return adminTools; } else if (user.hasPermission(REPORT)) { return reportTools; } return basicTools; } // 在控制器中使用 GetMapping(/ask) public String askQuestion(RequestParam String query, AuthenticationPrincipal User user) { ToolCallback tool getContextualTool(user); return ChatClient.create(chatModel) .prompt(query) .tools(tool) .call() .content(); }8. 性能优化建议工具懒加载Bean Lazy public ExpensiveTool expensiveTool() { return new ExpensiveTool(); }工具缓存Tool Cacheable(weatherData) public WeatherData getWeather(String location) { return weatherApi.fetch(location); }批量处理Tool(description Batch process items) public BatchResult processItems( ToolParam(description Item IDs) ListString ids ) { return processor.processBatch(ids); }异步工具Bean Description(Async data fetch) public SupplierCompletableFutureData asyncDataFetcher() { return () - dataService.fetchAsync(); }9. 安全实践权限检查Tool public SensitiveData getData(ToolParam String id, ToolContext context) { SecurityUtils.checkAccess(context.get(user), id); return dataRepo.find(id); }输入验证Tool public void updateRecord( ToolParam Valid Size(max100) String input ) { // 处理逻辑 }审计日志Bean ToolExecutionListener auditLogger() { return new ToolExecutionListener() { Override public void afterExecution(ToolExecutionResult result) { auditLog.log(result); } }; }10. 未来演进方向工具版本管理Tool(version 2.0) public ImprovedResult improvedTool() { // 新版本实现 }工具依赖声明Tool(dependsOn {preProcessor, validator}) public Result compositeTool() { // 依赖其他工具 }动态模式生成ToolDefinition.dynamicBuilder() .fromOpenApiSpec(apiSpec) .build();工具市场集成Bean ToolRegistry toolMarketplace() { return new RemoteToolRegistry(https://market.example.com/api/tools); }