Spring AI 工具调用：从 Function Calling 到受控执行

模型可以根据对话判断何时需要外部信息，并生成一个工具调用请求，例如查询订单状态或搜索知识库。但模型本身并没有直接访问数据库或执行 Java 方法的权限；工具由应用注册和执行，应用决定允许模型做什么。

1. 一次工具调用的流程

1
2
3
4
5
6
用户提出问题
  → 应用把问题和可用工具描述发送给模型
  → 模型返回普通文本，或请求调用某个工具并给出参数
  → 应用校验工具名和参数，再执行 Java 方法
  → 应用把工具结果返回模型
  → 模型组织最终答复

有些材料把这个模式称作 Function Calling；Spring AI 文档中常用 Tool Calling。名称会变化，关键机制是模型提出结构化调用请求，应用负责真正执行。

2. 用窄范围工具表达能力

概念示例：

1
2
3
4
5
6
7
class OrderTools {
    @Tool(description = "按订单编号查询当前用户有权查看的订单摘要")
    OrderSummary findOrder(String orderId, ToolContext context) {
        String currentUserId = (String) context.getContext().get("userId");
        return orderService.findVisibleOrder(currentUserId, orderId);
    }
}

工具应表达清楚、范围有限，并由服务端从可信上下文取得用户身份。不要把“执行任意 SQL”“运行任意 Shell 命令”暴露给模型。上面的类只展示接口设计，具体注解包名和 ChatClient 调用方式要与项目锁定的 Spring AI 版本一致。

3. 参数仍然是不可信输入

模型生成的参数可能缺失、格式错误或与用户意图不符。应用需要做类型校验、范围校验、权限校验和业务状态校验。模型说“用户已经确认”并不构成授权证明；删除、付款、发信等有副作用的操作，应由明确的用户确认流程控制。

查询工具也要限制返回字段。工具结果可能包含个人信息、内部标识或提示注入文本，只返回完成任务所需的数据，并对日志和模型上下文做数据最小化。

4. 超时、重试与幂等

外部服务调用可能超时。对只读工具可以按策略重试；写入工具要使用幂等键，避免模型重复请求时创建多条记录或重复执行副作用。为每次调用设置超时、并发限制和审计记录，并明确错误是交给模型解释，还是由应用返回固定错误。

5. 工具结果不要盲目信任

工具可能返回过时、不完整或恶意构造的文本。应用可返回结构化结果和来源信息，模型只负责整理表达。涉及关键状态的最终决策应由业务服务校验，不能让生成文本本身成为交易或权限事实。

6. 小结

工具调用不是把模型变成拥有系统权限的程序，而是让模型在应用提供的有限能力中提出请求。权限、参数校验、身份上下文、幂等和审计都应由应用负责。

参考：Spring AI Tool Calling 文档。Spring AI API 仍在演进，示例应按项目采用的 BOM 版本校对。