Spring AI on On My Way https://tuanzi-wow.cn/tags/spring-ai/ Recent content in Spring AI on On My Way Hugo zh-CN Sat, 12 Sep 2026 00:25:38 +0800 Spring AI Tools https://tuanzi-wow.cn/agent/spring-ai-tools/ Sun, 06 Sep 2026 00:00:00 +0800 https://tuanzi-wow.cn/agent/spring-ai-tools/ Tool是agents调用来执行操作的组件,通过定义良好的输入和输出来让模型和外部世界交互…… Tools

定义:

Tool是agents调用来执行操作的组件,通过定义良好的输入和输出来让模型和外部世界交互

Tools封装了一个可调用的函数及其输入模式,允许模型决定什么时候调用Tools以及传入的参数

Tool主要用语言:

  • 信息检索:与外部数据源进行交互检索信息,如数据库和Web搜索引擎.主要目标是增强model的知识,使其能够回答原本无法回答的问题
  • 执行操作:目标是自动化原本需要人工干预或者显式编程的任务

ps:Toolc calling称为model能力但是实际上由客户端提供ToolCalling逻辑

Quick Start

两个示例:一个信息检索,一个执行操作

信息检索

在DataTimeTool类中实现一个Tool来获取日期和时间(此处不关心具体实现方式)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

import java.time.LocalDateTime;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.context.i18n.LocaleContextHolder;

class DateTimeTools {

  @Tool(description = "Get the current date and time in the user's timezone")
  String getCurrentDateTime() {
      return LocalDateTime.now().atZone(LocaleContextHolder.getTimeZone().toZoneId()).toString();
  }

}

如何让LLM了解到这个Tool的存在:通过调用Chatclient的tool()方法通知LLM 注意 tool(datetimetool)中的datetimetool需要实例化(也就你JAVA这么多事)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

ChatModel chatModel = ...;

String response = ChatClient.create(chatModel)
      .prompt("What day is tomorrow?")
      .tools(new DateTimeTools())
      .call()
      .content();

System.out.println(response);
// 输出：Tomorrow is 2015-10-21.

执行操作

和上面差不多自己看了

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.context.i18n.LocaleContextHolder;

class DateTimeTools {

  @Tool(description = "Get the current date and time in the user's timezone")
  String getCurrentDateTime() {
      return LocalDateTime.now().atZone(LocaleContextHolder.getTimeZone().toZoneId()).toString();
  }

  @Tool(description = "Set a user alarm for the given time, provided in ISO-8601 format")
  void setAlarm(String time) {
      LocalDateTime alarmTime = LocalDateTime.parse(time, DateTimeFormatter.ISO_DATE_TIME);
      System.out.println("Alarm set for " + alarmTime);
  }

}

那么有的同学就要问了: 这里只调用了datetimetool类而不是具体的工具,他是怎么知道选择哪个方法的 这就是你SpringAI叔叔的强大之处了,@Tool:会将该方法自动注册为一个tool 所以你们臭学JAVA的还不好好学Spring,Spring Boot,Spring MVC?

概述

Tool Calling 主要操作序列

1.Tool定义:名称,描述和传入参数 2.调用:Model发送带有Tool名称和参数的相应 3.通过名称选择tool并传入参数执行 4.toolcall结果由程序处理 5.结果传回Model 6.Model根据结果作为附加上下文生成最终响应

Tools 是 tool calling 的构建块，它们由 ToolCallback 接口建模。Spring AI 提供了从方法和函数指定 ToolCallback(s) 的内置支持，但您始终可以定义自己的 ToolCallback 实现以支持更多用例。

ChatModel 实现透明地将 tool call 请求分派到相应的 ToolCallback 实现，并将 tool call 结果发送回 model，最终生成最终响应。它们使用 ToolCallingManager 接口来执行此操作，该接口负责管理 tool 执行生命周期。

ChatClient 和 ChatModel 都接受 ToolCallback 对象列表，以使 tools 可用于 model 和最终执行它们的 ToolCallingManager。

除了直接传递 ToolCallback 对象外，您还可以传递 tool 名称列表，这些名称将使用 ToolCallbackResolver 接口动态解析。

创建工具

Spring AI提供了两种从方法指定Tools(即ToolCallback(s))的内置支持

  • 声明式:使用@Tool注解
  • 编程式:使用低级MethodToolCallback实现

方法作为Tool

声明式规范 @Tool

1
2
3
4
5
6
7
8

class DateTimeTools {

  @Tool(description = "Get the current date and time in the user's timezone")
  String getCurrentDateTime() {
      return LocalDateTime.now().atZone(LocaleContextHolder.getTimeZone().toZoneId()).toString();
  }

}

@Tool注解允许你提供的信息:

  • name:如果未提供,将使用方法名称
  • description:tool描述;若未提供,使用方法名称代替.但是强烈建议详细描述,对于model理解tool的用途以及when to use and how to use很重要
  • returnDirect:结果是否直接传回model;为布尔值
  • resultConverter:将toolcall的结果转化为String Object以 ToolCallResultConverter 实现

NOTE: Spring AI 为 @Tool 注解方法的 AOT 编译提供内置支持，只要包含方法的类是 Spring bean（例如 @Component）。否则，您需要向 GraalVM 编译器提供必要的配置。例如，通过用 @RegisterReflection(memberCategories = MemberCategory.INVOKE_DECLARED_METHODS) 注解类。

如果方法返回值，返回类型必须是可序列化类型，因为结果将被序列化并发送回 model。

@ToolParam 注解可用于提供有关输入参数的附加信息，例如描述或参数是必需还是可选的。默认情况下，所有输入参数都被视为必需

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;

class DateTimeTools {

  @Tool(description = "Set a user alarm for the given time")
  void setAlarm(@ToolParam(description = "Time in ISO-8601 format") String time) {
      LocalDateTime alarmTime = LocalDateTime.parse(time, DateTimeFormatter.ISO_DATE_TIME);
      System.out.println("Alarm set for " + alarmTime);
  }

}

@ToolParam允许你提供的有关tool参数的关键信息:

  • description：参数的描述，model 可以使用它来更好地理解如何使用它。例如，参数应该是什么格式，允许什么值等。
  • required：参数是必需还是可选的。默认情况下，所有参数都被视为必需。
]]> Spring AI Tool Calling 使用指南 https://tuanzi-wow.cn/agent/spring-ai-tool-calling/ Sun, 06 Sep 2026 00:00:00 +0800 https://tuanzi-wow.cn/agent/spring-ai-tool-calling/ ToolCalling(FunctionCalling)允许模型与一组API或者工具进行交互,增强模型的能力…… Spring AI Tool Calling使用指南之我不用JAVA好多年

概述:

Tool Calling(Function Calling)允许模型与一组API或者工具进行交互,增强模型的能力

主要功能:

  • 信息检索:从外部数据源获取信息,比如:数据库,Web服务,例如:Web_Search
  • 执行操作:在软件系统执行特定操作:例如:预定航班,生成代码

Spring AI Alibaba拓展服务:

  • 搜索引擎
  • 翻译服务
  • 地图服务
  • 数据服务
  • 开发工具
  • 其他工具

详细使用说明

Python Tool示例(你个臭执行Python代码的)

PythonTool 使用 GraalVM polyglot 在沙箱环境中执行 Python 代码。这个工具允许 AI 代理执行 Python 代码片段并获取结果。

依赖配置:

使用Maven添加依赖:

1
2
3
4
5

<dependency>
	<groupId>com.alibaba.cloud.ai</groupId>
	<artifactId>spring-ai-alibaba-starter-tool-calling-python</artifactId>
	<version>${version}</version>
</dependency>

注意：Python Tool 需要 GraalVM polyglot 依赖，这些依赖已作为可选依赖包含。如果需要使用，请确保 GraalVM polyglot 在 classpath 中。

自动配置

Python Tool默认启用,会自动注册为ToolCallback并可供AI代理使用,如果需要禁用,可以在配置文件中设置

1
2
3
4
5
6

spring:
	ai:
		alibaba:
			python:
				tool:
					enabled: false

基本使用

示例1:在ChatClient中使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

import com.alibaba.cloud.ai.agent.python.tool.PythonTool;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class PythonToolService {

    @Autowired
    private ChatModel chatModel;

    @Autowired
    private PythonTool pythonTool;

    public String executeCalculation(String question) {
        // 创建 ChatClient 并添加 Python Tool
        ChatClient chatClient = ChatClient.builder(chatModel)
            .tools(pythonTool.createPythonToolCallback(PythonTool.DESCRIPTION))
            .build();

        // 使用工具进行对话
        String response = chatClient.prompt(question)
            .call()
            .content();

        return response;
    }
}

示例2:直接使用PythonTool

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

import com.alibaba.cloud.ai.agent.python.tool.PythonTool;
import org.springframework.ai.chat.model.ToolContext;

public class DirectPythonToolUsage {

    public void executePythonCode() {
        PythonTool pythonTool = new PythonTool();
        
        // 创建请求
        PythonTool.PythonRequest request = new PythonTool.PythonRequest("2 + 2");
        
        // 执行 Python 代码
        String result = pythonTool.apply(request, new ToolContext());
        
        System.out.println("Result: " + result); // 输出: Result: 4
    }
}

示例3:执行复杂计算

还是通过在client中调用PythonTool

示例4:字符串操作

类似于示例2:创建request,调用apply(request,toolcontext)

1
2
3
4

  PythonTool.PythonRequest request1 = new PythonTool.PythonRequest(
            "'Hello, ' + 'World'"
        );
        String result1 = pythonTool.apply(request1, toolContext);

示例5:在Spring Boot应用中使用

类似于示例1 创建client并将PythonTool写入,只是这里的1应用场景是Spring Boot

示例6:自定义ToolCallback

(来你告诉我这不是在Spring Boot里面运行吗?)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

import com.alibaba.cloud.ai.agent.python.tool.PythonTool;
import org.springframework.ai.tool.ToolCallback;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class PythonToolConfiguration {

    @Bean
    public PythonTool pythonTool() {
        return new PythonTool();
    }

    @Bean
    public ToolCallback pythonToolCallback(PythonTool pythonTool) {
        return PythonTool.createPythonToolCallback(
            "执行 Python 代码并返回结果。支持数学计算、字符串处理、列表操作等。"
        );
    }
}

示例7:多工具组合使用

PythonTool和其他Tool一起调用,看看就好,也是创建client并添加tools,这次是多个

安全特性:

PythonTool在沙箱环境中运行,具有以下的安全限制

  • 文件I/O已禁用:无法读写文件
  • 本地访问已禁用:无法访问本地系统资源
  • 进程创建已禁用:无法创建新的进程
  • 默认限制所有访问:所有访问受限

保证了Python代码执行的安全性

支持的数据类型

  • 字符串:直接返回
  • 数字:转化为字符串返回
  • 布尔值:转化为字符串返回
  • 数组/列表:转化为字符串表现形式
  • 其他类型:使用toString()方法转换

注意事项

  1. GraalVM 依赖：确保 GraalVM polyglot 依赖在 classpath 中
  2. 性能考虑：每次执行都会创建新的 Context，对于频繁调用可能需要优化
  3. 错误处理：代码执行错误会被捕获并返回错误消息
  4. 代码限制：由于安全限制，某些 Python 功能可能不可用
  5. 资源管理：Context 会自动关闭，无需手动管理

一个完整的示例:AI代理使用Python Tool:

eee,这算哪门子示例,好吧也算

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

import com.alibaba.cloud.ai.agent.python.tool.PythonTool;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.stereotype.Service;

@Service
public class PythonToolAgentService {

    private final ChatClient chatClient;

    public PythonToolAgentService(ChatModel chatModel, PythonTool pythonTool) {
        this.chatClient = ChatClient.builder(chatModel)
            .tools(pythonTool.createPythonToolCallback(PythonTool.DESCRIPTION))
            .build();
    }

    public String solveMathProblem(String problem) {
        String prompt = String.format("""
            请使用 Python 工具解决以下数学问题：
            %s
            
            请展示计算过程。
            """, problem);

        return chatClient.prompt(prompt)
            .call()
            .content();
    }

    public String analyzeData(String dataDescription) {
        String prompt = String.format("""
            请使用 Python 工具分析以下数据：
            %s
            
            请计算基本统计信息（平均值、中位数、标准差等）。
            """, dataDescription);

        return chatClient.prompt(prompt)
            .call()
            .content();
    }
}

支持的拓展实现:

https://java2ai.com/integration/toolcalls/tool-calls#%E7%9B%AE%E5%BD%95 自己去这里看

使用说明

所有的Tool Calling实现都遵循相同的使用模式

  1. 添加依赖:在pom.xml或者build.gradle中添加相应的依赖
  2. 自动配置:Spring Boot的生态真实太好用了,你们知道吗?会自动注册为ToolCallback
  3. 在Chatclient中使用:通过ChatClient.builder().tools()添加工具
  4. AI模型调用:AI模型会根据会话内容自动决定是否调用工具

通用接口

你这么好用你不早说?

所有 Tool 都实现了 BiFunction<Request, ToolContext, String> 接口，并通过 FunctionToolCallback 包装为 ToolCallback：

1
2
3
4
5

public interface ToolCallback {
    String getName();
    String getDescription();
    ToolResponse call(ToolRequest request);
}

配置说明

大多数工具都支持通过Spring Boot配置属性进行配置(又是你宝宝)

1
2
3
4
5
6

spring:
  ai:
    alibaba:
      tool-name:
        enabled: true  # 启用/禁用工具
        # 其他工具特定配置

认证和API key

参考各个工具的文档

最佳实践

  1. 工具选择：根据实际需求选择合适的工具，避免添加不必要的工具
  2. 错误处理：工具调用可能失败，确保有适当的错误处理机制
  3. 性能优化：对于频繁调用的工具，考虑缓存结果
  4. 安全性：确保 API Key 等敏感信息的安全存储
  5. 成本控制：某些工具（如搜索、翻译）可能产生费用，注意使用量
]]>