Agent 学习笔记 on On My Way

Function Calling（工具调用）

Sun, 06 Sep 2026 00:00:00 +0800

//我说句实在话,这个菜鸟教程写的好简单也挺烂的,不过很容易看懂吧,还真是菜鸟教程,而且代码又臭又长

Function Calling(工具调用)

是LLM能够调用外部工具的核心机制,允许模型决定什么时候调用工具,调用什么工具,以及传递什么参数

Function Calling的工作原理:

其基本流程如下:

核心概念: 工具定义:描述一个工具的功能,参数和返回值 工具选择:LLM根据用户问题选择合适的工具 参数提取:LLM从问题中提取工具所需要的参数 结果处理:将工具执行结果整合到最终回答中

实例说明:

LLM 识别出需要调用天气查询工具
从问题中提取参数：city="北京", date="今天"
调用天气 API 获取数据
将天气数据整合成友好的回答返回给用户

工具定义和描述编写

好的工具定义应该描述: what:工具的功能 when:什么时候调用它 how:需要的参数;参数的格式;返回值

工具定义的结构:

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


# 工具定义示例结构
weather_tool = {
    "name": "get_weather",  # 工具名称
    "description": "获取指定城市的天气信息",  # 工具描述
    "parameters": {  # 参数定义
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "城市名称，如'北京'、'上海'"
            },
            "date": {
                "type": "string",
                "description": "日期，格式'YYYY-MM-DD'，或'今天'、'明天'",
                "enum": ["今天", "明天", "后天"]
            }
        },
        "required": ["city"]  # 必填参数
    }
}

编写优质的工具描述:

1.描述要具体,例如:

不好的描述：查询天气
好的描述：获取指定城市在特定日期的天气信息，包括温度、湿度、风速和天气状况（晴、雨、多云等）

2.参数描述要具体:不好的参数描述：

1

"city": {"type": "string"}

好的参数描述：

1
2
3
4


"city": {
    "type": "string",
    "description": "完整的城市名称，如'北京市'、'上海市'。不要使用简称或拼音。"
}

3.使用枚举项限制选项对于有限的选择,是一种很好的约束手段:

1
2
3
4
5
6


"unit": {
    "type": "string",
    "description": "温度单位",
    "enum": ["celsius", "fahrenheit"],
    "default": "celsius"
}

4.提供示例值在描述中提供示例,帮助LLM理解:

1
2
3
4


"date": {
    "type": "string",
    "description": "日期，格式应为'YYYY-MM-DD'，例如'2024-06-15'"
}

示例:

文件读取工具的定义

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


file_tool = {
    "name": "read_file",
    "description": "读取指定文件的内容",
    "parameters": {
        "type": "object",
        "properties": {
            "file_path": {
                "type": "string",
                "description": "文件的完整路径，如'/home/user/document.txt'"
            },
            "encoding": {
                "type": "string",
                "description": "文件编码，默认为'utf-8'",
                "default": "utf-8"
            }
        },
        "required": ["file_path"]
    }
}

工具定义的验证

定义工具之后,应该进行验证测试:

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


def validate_tool_definition(tool_def):
    """验证工具定义是否完整"""
    required_fields = ["name", "description", "parameters"]

    for field in required_fields:
        if field not in tool_def:
            return False, f"缺少必要字段: {field}"

    # 检查参数结构
    if "properties" not in tool_def["parameters"]:
        return False, "参数定义缺少properties字段"

    return True, "工具定义完整"

# 测试验证
is_valid, message = validate_tool_definition(weather_tool)
print(f"验证结果: {is_valid}, 消息: {message}")

参数提取的验证

LLM从问题中提取出参数之后,会对这些参数进行验证和处理,保证工具能正确执行

参数提取过程:

分析输出并提取需要的参数:

参数提取的挑战:

信息缺失:没有提供所有的必须信息格式不符:提供的格式与定义不符歧义解析:同一信息可能由歧义上下文依赖:参数需要结合历史对话理解

参数验证方法:

1.类型验证:验证参数类型符合要求

def validate_parameters(params, tool_def):
    """验证参数类型"""
    errors = []
    for param_name, param_def in tool_def["parameters"]		["properties"].items():
    if param_name in params:
        param_value = params[param_name]
        expected_type = param_def.get("type")

        # 类型检查
        if expected_type == "string" and not isinstance(param_value, str):
            errors.append(f"参数'{param_name}'应为字符串类型")
        elif expected_type == "integer" and not isinstance(param_value, int):
            errors.append(f"参数'{param_name}'应为整数类型")
        elif expected_type == "number" and not isinstance(param_value, (int, float)):
            errors.append(f"参数'{param_name}'应为数字类型")
        elif expected_type == "boolean" and not isinstance(param_value, bool):
            errors.append(f"参数'{param_name}'应为布尔类型")

return errors

2.范围验证:检查参数值是否在允许范围内:

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


def validate_range(params, tool_def):
    """验证参数范围"""
    errors = []

    for param_name, param_def in tool_def["parameters"]["properties"].items():
        if param_name in params:
            param_value = params[param_name]

            # 检查最小值
            if "minimum" in param_def and param_value < param_def["minimum"]:
                errors.append(f"参数'{param_name}'不能小于{param_def['minimum']}")

            # 检查最大值
            if "maximum" in param_def and param_value > param_def["maximum"]:
                errors.append(f"参数'{param_name}'不能大于{param_def['maximum']}")

            # 检查枚举值
            if "enum" in param_def and param_value not in param_def["enum"]:
                errors.append(f"参数'{param_name}'必须是{param_def['enum']}中的一个")

    return errors

3.必填参数检验: 所有必填参数都已提供

完整的参数检验系统:类型,范围,必需值

  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
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104


class ParameterValidator:
    """参数验证器"""

    def __init__(self, tool_def):
        self.tool_def = tool_def

    def validate(self, params):
        """执行完整的参数验证"""
        all_errors = []

        # 检查必填参数
        required_errors = self.validate_required(params)
        all_errors.extend(required_errors)

        # 检查参数类型
        type_errors = self.validate_type(params)
        all_errors.extend(type_errors)

        # 检查参数范围
        range_errors = self.validate_range(params)
        all_errors.extend(range_errors)

        # 检查额外参数（未定义的参数）
        extra_errors = self.validate_extra(params)
        all_errors.extend(extra_errors)

        return len(all_errors) == 0, all_errors

    def validate_required(self, params):
        """验证必填参数"""
        errors = []
        required_params = self.tool_def["parameters"].get("required", [])

        for param_name in required_params:
            if param_name not in params or params[param_name] is None:
                errors.append(f"缺少必填参数: {param_name}")

        return errors

    def validate_type(self, params):
        """验证参数类型"""
        errors = []

        for param_name, param_value in params.items():
            if param_name in self.tool_def["parameters"]["properties"]:
                param_def = self.tool_def["parameters"]["properties"][param_name]
                expected_type = param_def.get("type")

                if expected_type == "string" and not isinstance(param_value, str):
                    errors.append(f"参数'{param_name}'应为字符串类型，实际为{type(param_value).__name__}")
                elif expected_type == "integer" and not isinstance(param_value, int):
                    errors.append(f"参数'{param_name}'应为整数类型，实际为{type(param_value).__name__}")
                elif expected_type == "number" and not isinstance(param_value, (int, float)):
                    errors.append(f"参数'{param_name}'应为数字类型，实际为{type(param_value).__name__}")
                elif expected_type == "boolean" and not isinstance(param_value, bool):
                    errors.append(f"参数'{param_name}'应为布尔类型，实际为{type(param_value).__name__}")

        return errors

    def validate_range(self, params):
        """验证参数范围"""
        errors = []

        for param_name, param_value in params.items():
            if param_name in self.tool_def["parameters"]["properties"]:
                param_def = self.tool_def["parameters"]["properties"][param_name]

                # 检查最小值
                if "minimum" in param_def and param_value < param_def["minimum"]:
                    errors.append(f"参数'{param_name}'不能小于{param_def['minimum']}")

                # 检查最大值
                if "maximum" in param_def and param_value > param_def["maximum"]:
                    errors.append(f"参数'{param_name}'不能大于{param_def['maximum']}")

                # 检查枚举值
                if "enum" in param_def and param_value not in param_def["enum"]:
                    errors.append(f"参数'{param_name}'必须是{param_def['enum']}中的一个")

        return errors

    def validate_extra(self, params):
        """检查未定义的额外参数"""
        errors = []
        defined_params = set(self.tool_def["parameters"]["properties"].keys())
        provided_params = set(params.keys())

        extra_params = provided_params - defined_params
        if extra_params:
            errors.append(f"提供了未定义的参数: {', '.join(extra_params)}")

        return errors

# 使用示例
validator = ParameterValidator(weather_tool)
params = {"city": "北京", "date": "明天", "extra": "不应该有的参数"}
is_valid, errors = validator.validate(params)

if is_valid:
    print("参数验证通过")
else:
    print("参数验证失败:")
    for error in errors:
        print(f"  - {error}")

参数提取和验证的完整流程

参数修正的策略

询问客户:直接向客户询问缺失和错误的参数使用默认值:可以预先设定默认值智能推断:根据上下文推断合理的参数值格式转换:将用户提供的格式转化成工具要求的格式

错误处理和重试机制

工具调用可能会失败,健全的错误处理和重试机制是构建可靠的AI Agent的挂件

常见的工具调用错误:

网络错误:API调用超时,连接错误参数错误:参数验证失败,格式不正确权限错误:API密钥无效,权限不足资源错误:服务不可达,达到调用限制逻辑错误:工具内部逻辑错误

错误处理策略

1.分级错误处理:

根据错误类型采取不同的处理策略

class ErrorHandler:
    """错误处理器"""

    def handle(self, error, context):
        """处理错误"""
        error_type = self.classify_error(error)

        if error_type == "network":
            return self.handle_network_error(error, context)
        elif error_type == "parameter":
            return self.handle_parameter_error(error, context)
        elif error_type == "authentication":
            return self.handle_auth_error(error, context)
        elif error_type == "resource":
            return self.handle_resource_error(error, context)
        else:
            return self.handle_unknown_error(error, context)

    def classify_error(self, error):
        """分类错误类型"""
        error_str = str(error).lower()

        if any(word in error_str for word in ["timeout", "connection", "network"]):
            return "network"
        elif any(word in error_str for word in ["parameter", "invalid", "missing"]):
            return "parameter"
        elif any(word in error_str for word in ["auth", "key", "permission"]):
            return "authentication"
        elif any(word in error_str for word in ["limit", "quota", "unavailable"]):
            return "resource"
        else:
            return "unknown"

    def handle_network_error(self, error, context):
        """处理网络错误"""
        return {
            "success": False,
            "error": "网络连接失败，请检查网络后重试",
            "retryable": True,
            "retry_after": 5  # 5秒后重试
        }

    def handle_parameter_error(self, error, context):
        """处理参数错误"""
        return {
            "success": False,
            "error": f"参数错误: {str(error)}",
            "retryable": False,
            "suggestion": "请检查输入参数是否正确"
        }

    # 其他错误处理方法类似...

2.用户友好的错误信息

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


def user_friendly_error(error):
    """生成用户友好的错误消息"""
    error_map = {
        "timeout": "请求超时，请稍后重试",
        "connection_error": "网络连接失败，请检查网络",
        "invalid_api_key": "API 密钥无效，请检查配置",
        "rate_limit_exceeded": "调用频率过高，请稍后再试",
        "invalid_parameters": "输入参数不正确，请检查后重试"
    }

    error_str = str(error).lower()
    for key, message in error_map.items():
        if key in error_str:
            return message

    return "系统繁忙，请稍后重试"

重试机制

1.指数退避重试:

指的是等待时间随着重试次数呈指数级增长等待时间:指数退避+随机抖动

 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
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68


import time
import random

class ExponentialBackoffRetry:
    """指数退避重试"""

    def __init__(self, max_retries=3, base_delay=1, max_delay=30):
        self.max_retries = max_retries
        self.base_delay = base_delay
        self.max_delay = max_delay

    def retry(self, func, *args, **kwargs):
        """执行带重试的函数调用"""
        last_error = None

        for attempt in range(self.max_retries):
            try:
                return func(*args, **kwargs)

            except Exception as e:
                last_error = e

                # 检查是否可重试
                if not self.is_retryable(e):
                    raise

                # 最后一次尝试，不再重试
                if attempt == self.max_retries - 1:
                    break

                # 计算等待时间（指数退避 + 随机抖动）
                delay = min(
                    self.base_delay * (2 ** attempt) + random.uniform(0, 1),
                    self.max_delay
                )

                print(f"第{attempt + 1}次尝试失败，{delay:.1f}秒后重试...")
                time.sleep(delay)

        # 所有重试都失败
        raise last_error

    def is_retryable(self, error):
        """判断错误是否可重试"""
        error_str = str(error).lower()
        retryable_errors = ["timeout", "connection", "busy", "temporarily"]

        for retryable_error in retryable_errors:
            if retryable_error in error_str:
                return True

        return False

# 使用示例
retry = ExponentialBackoffRetry(max_retries=3)

def call_weather_api(city, date):
    """调用天气API（模拟可能失败）"""
    # 模拟API调用
    if random.random() < 0.3:  # 30%概率失败
        raise ConnectionError("API连接超时")
    return {"temperature": 25, "condition": "晴"}

try:
    result = retry.retry(call_weather_api, "北京", "今天")
    print(f"成功获取天气: {result}")
except Exception as e:
    print(f"获取天气失败: {e}")

2.熔断器模式

 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
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65


class CircuitBreaker:
    """熔断器"""

    def __init__(self, failure_threshold=5, reset_timeout=60):
        self.failure_threshold = failure_threshold
        self.reset_timeout = reset_timeout
        self.failure_count = 0
        self.last_failure_time = None
        self.state = "closed"  # closed, open, half-open

    def execute(self, func, *args, **kwargs):
        """通过熔断器执行函数"""
        if self.state == "open":
            # 检查是否应该尝试恢复
            if self.should_try_reset():
                self.state = "half-open"
            else:
                raise Exception("熔断器开启，服务暂时不可用")

        try:
            result = func(*args, **kwargs)

            # 成功调用，重置状态
            if self.state == "half-open":
                self.state = "closed"
                self.failure_count = 0

            return result

        except Exception as e:
            self.record_failure()
            raise e

    def record_failure(self):
        """记录失败"""
        self.failure_count += 1
        self.last_failure_time = time.time()

        if self.failure_count >= self.failure_threshold:
            self.state = "open"

    def should_try_reset(self):
        """检查是否应该尝试重置"""
        if self.last_failure_time is None:
            return True

        elapsed = time.time() - self.last_failure_time
        return elapsed > self.reset_timeout

# 使用示例
breaker = CircuitBreaker(failure_threshold=3, reset_timeout=30)

def unreliable_service():
    """模拟不可靠的服务"""
    if random.random() < 0.5:
        raise Exception("服务异常")
    return "服务正常"

for i in range(10):
    try:
        result = breaker.execute(unreliable_service)
        print(f"调用{i+1}: {result}")
    except Exception as e:
        print(f"调用{i+1}: {e}")
        time.sleep(1)

完整的工具框架

  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
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112


class ToolExecutor:
    """工具执行器"""

    def __init__(self):
        self.tools = {}  # 注册的工具
        self.validator = ParameterValidator
        self.error_handler = ErrorHandler()
        self.retry = ExponentialBackoffRetry()
        self.breaker = CircuitBreaker()

    def register_tool(self, name, tool_def, func):
        """注册工具"""
        self.tools[name] = {
            "definition": tool_def,
            "function": func
        }

    def execute_tool(self, tool_name, params):
        """执行工具"""
        if tool_name not in self.tools:
            return {
                "success": False,
                "error": f"工具'{tool_name}'未注册"
            }

        tool_info = self.tools[tool_name]
        tool_def = tool_info["definition"]
        tool_func = tool_info["function"]

        # 验证参数
        validator = self.validator(tool_def)
        is_valid, errors = validator.validate(params)

        if not is_valid:
            return {
                "success": False,
                "error": "参数验证失败",
                "details": errors
            }

        # 通过熔断器执行（带重试）
        try:
            def execute_with_retry():
                return self.breaker.execute(
                    lambda: self.retry.retry(tool_func, **params)
                )

            result = execute_with_retry()

            return {
                "success": True,
                "result": result,
                "tool": tool_name
            }

        except Exception as e:
            # 错误处理
            error_response = self.error_handler.handle(e, {
                "tool": tool_name,
                "params": params
            })

            return {
                "success": False,
                "error": error_response["error"],
                "retryable": error_response.get("retryable", False),
                "suggestion": error_response.get("suggestion", "")
            }

    def handle_user_request(self, user_input):
        """处理用户请求（简化版）"""
        # 1. 让LLM选择工具和提取参数（这里简化处理）
        # 实际应用中，这里会调用LLM进行工具选择和参数提取

        # 模拟LLM的输出
        if "天气" in user_input:
            tool_name = "get_weather"
            # 简单提取城市（实际应用中LLM会做得更好）
            if "北京" in user_input:
                params = {"city": "北京", "date": "今天"}
            elif "上海" in user_input:
                params = {"city": "上海", "date": "今天"}
            else:
                params = {"city": "北京", "date": "今天"}  # 默认值
        else:
            return "抱歉，我无法处理这个请求"

        # 2. 执行工具
        result = self.execute_tool(tool_name, params)

        # 3. 生成最终回答
        if result["success"]:
            weather = result["result"]
            return f"{params['city']}今天天气：{weather['condition']}，温度{weather['temperature']}°C"
        else:
            return f"获取天气信息失败：{result['error']}"

# 使用示例
executor = ToolExecutor()

# 注册天气工具
def mock_weather_api(city, date):
    """模拟天气API"""
    # 模拟API调用延迟
    time.sleep(0.1)
    return {"temperature": 22, "condition": "多云"}

executor.register_tool("get_weather", weather_tool, mock_weather_api)

# 处理用户请求
response = executor.handle_user_request("北京今天天气怎么样？")
print(response)

Spring AI Tools

Sun, 06 Sep 2026 00:00:00 +0800

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?

概述

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 使用指南

Sun, 06 Sep 2026 00:00:00 +0800

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.aigroupId>
	<artifactId>spring-ai-alibaba-starter-tool-calling-pythonartifactId>
	<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()方法转换

注意事项

GraalVM 依赖：确保 GraalVM polyglot 依赖在 classpath 中
性能考虑：每次执行都会创建新的 Context，对于频繁调用可能需要优化
错误处理：代码执行错误会被捕获并返回错误消息
代码限制：由于安全限制，某些 Python 功能可能不可用
资源管理：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实现都遵循相同的使用模式

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

通用接口

你这么好用你不早说?

所有 Tool 都实现了 BiFunction 接口，并通过 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

参考各个工具的文档

最佳实践

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

Function Call 是什么

Sun, 06 Sep 2026 00:00:00 +0800

Function Call是什么?

实现了从只会说话到能做事情

生成文本->Function_Call->操作外部程序

Function Call的工作原理:

分为四步:定义函数->选择函数(模型选择)->执行函数->返回结果(生成回答)

定义函数:

用JSON格式描述:函数名称(name),功能说明(description),参数(params)

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


{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的实时天气",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string", 
              "description": "城市名称，比如：上海"
            }
          },
          "required": ["city"]
        }
      }
    }
  ]
}

模型判断:

LLM分析意图并调用函数

执行函数

LLM本身不执行函数,而是输出调用意图+函数参数,应用程序拿到指令后调用函数执行函数

生成回答

LLM拿到结果并执行回答

为什么Function Call这么重要

解决了两个问题:

when:什么时候调用:LLM根据用户自然语言判断意图
传入什么参数:LLM从自然语言结构化传入参数

最底层的技术基础