简介

    spring ai alibaba是java的ai agent框架，本系列将深入剖析 Spring AI Alibaba 的源码实现与核心原理，不仅指导agent的开发，更可以改造框架，增加新特性

系列内容：

系列(一) 架构  完成
系列(三) 调用 
     I 工具  完成 
     II MCP
       -1 MCP MCP能力，工具，资源，Prompts，sampling，。。。；springboot自动配置  完成
       -2 分布式 MCP  
       -3 MCP security
     III skills  完成
系列(四) RAG  完成
     I 知识库，文档读取，分块；嵌入，向量store 
     II 检索，增强生成，模块化；混合检索，融合重排
系列(二) 模型 model模型 完成
         chat模型，消息，提示词，结构化输出，记忆
         chat client，advisor组件
系列(五) graph  图结构，节点和边；StateGraph；CompiledGraph；图执行，状态和存储
             推理框架graph映射示例: ReAct，relection，CoT，Plan-And-Execut
系列(六) ReactAgent分析，钩子和拦截器，记忆，结构化输出，Human-in-the-loop
系列(七) MAS
        I 多agent graph，flow agent; handoffs模式，toolcalling模式；
        II 分布式agent，A2A；AP2AP，分布式多agent的graph，新功能
系列(八) I 观测：观测组件(micrometer-observation)，观测点：chatClient，chat模型，工具(tracing)
         II 模型评估
系列(九) agent管理平台(admin) agent发现(a2a)，agent列表，提示词管理，会话管理，skill管理，MCP管理；chat；评估；观测

本文分析外部调用 I 工具

based spring ai aliba ba v1.1.2.2，spring ai v1.1.2

关键词

工具

MCP

Skills

缩写

spring ai 缩写sa

spring ai alibaba  本文缩写saa

参考资料

https://java2ai.com/docs/overview  spring ai alibaba官网文档

https://docs.spring.io/spring-ai/reference/index.html spring ai官方文档

组件视图

上图是saa原理源码分析场景视图，每个包对应着saa/sa组件或特性，是本文分析的目录

model  大模型的封装，模型包括Chat，嵌入，audio，image等类型，其中chat模型包括，advisor组件，提示词，记忆等

agent/graph  agent和图紧密相关，可以认为agent是一种既定的”图”形，开发人员可以使用graph低层api直接构建graph，也可以使用agent获得既定的图形，简化和加快agent的开发

外部调用(calling)  工具，MCP，skills

RAG  检索增加生成

MAS  工具，MCP，skills，A2A

studio 简易的agent管理工具，嵌入到agent，带有agent面板，列表agent；提供chat界面，用于调试agent，是开发agent的便利工具

admin 管理台， agent的发布，列表，管理，执行；提示词工程，评估和数据集，观测

外部调用

如果说大模型是agent大脑，调用就是手脚，执行动作干实事。调用在不断发展演变中，目前已有工具，MCP，skills等多种方式

工具

工具调用是最早的外部调用方式，大模型调用工具是通过训练获得的能力，不是所有大模型都有调用工具的能力，有些大模型还可以直接调用工具，但出于安全考虑，工具的调用是agent执行，大模型返回调用什么工具，参数等，agent执行调用。

上图展示工具的分析用例

工具对应java类的方法，有两种，

1. 一般类方法  普通类可有多个方法，使用注解@Tool标识工具方法
2. Function  这种类型只有一个方法，且名称参数固定，不需要抓取，类的方法就是工具方法，解释工具针对这种类型，sa统一用BiFunction适配其他，也就是Function工具只有BiFunction类型方法

调用侧用例： 

设置工具  agent构建 ChatClient，设置工具

工具提示词 ChatClient写入工具描述到提示词，大模型学习工具

调用工具  大模型处理请求，有需要调用工具，返回toolcall消息给 agent，agent调用工具，结果返回给大模型，也可以根据设置直接回到agent，终止大模型处理

抓取和提供工具

工具提供者(ToolCallbackProvider)抓取工具信息，包括工具的名称，描述，输入参数等，返回ToolCallback

上图方法工具提供的类

toolObject，MethodToolCallbackProvider使用反射，抓取对象带@Tool的方法，获得工具方法

解释工具

本节分析解释工具，解释工具也是工具提供者，抓取工具信息方式与方法工具不同

上图Function工具提供者类图

解释工具使用常见的模式，

DelegatingToolCallbackResolver  代理类，按顺序交给聚合的解释，正确解释结束

目前有两个解释类：

StaticToolCallbackResolver  接收上下文的ToolCallback，ToolCallbackProvider，但排除MCP工具*，ToolCallbackProvider取出ToolCallback，合并起来，因此该类获取性能高，只要遍历ToolCallback集比较名称

SpringBeanToolCallbackResolver  引用spring的上下文，实时解释，只接受Function，Supplier，Consumer类型， 提供了缓存，因此第一次解释性能低，这样做是考虑到ai应用的工具可能很多

*MCP工具的ToolCallback信息需要远程，可能考虑到这点，延迟到用户设置ChatClient工具时

设置工具

上面两节分析了工具提供者/工具解释器，工具准备好，ChatClient可以设置工具*，工具定义写入提示词给大模型，大模型学会使用工具

ChatClient工具设置分为默认工具和请求级别，请求级别有效范围是当前请求，默认是ChatClient实例有效

 

上图chat client请求的工具设置，请求范围有效，与默认工具的设置方法一致

toolNames  使用工具名称，通常是工具解释器的，可以用名称获得ToolCallback

toolObject  对象，用MethodToolCallbackProvider抓取Tool注解的方法，构建ToolCallback

toolCallbacks/toolCallbackProvider 直接保存

总的说来，ChatClient的工具有3种形态，工具名称，ToolCallback，MethodToolCallbackProvider，

其中MethodToolCallbackProvider可以转换为ToolCallback

下面分析工具设置原理和源码

上图ChatClient设置工具的类图

ChatClient.Builder/DefaultChatClientBuilder  默认工具在该类设置，执行build方法后生成ChatClient，默认工具保存在defaultChatClientRequest属性，类型是DefaultChatClientRequestSpec

ChatClient/DefaultChatClient  ChatClient的prompt方法，返回新的ChatClientRequestSpec

上图ChatClient的prompt方法，以及DefaultChatClientRequestSpec工具属性的初始，这里看到一个技巧，新建返回给用户的DefaultChatClientRequestSpec的工具属性list是新建的， ChatClient的defaultChatClientRequest的工具addAll到新建的工具属性list，这样ChatClient的default工具不受影响，后续新的DefaultChatClientRequestSpec请求范围的增加工具累加起来，ChatClient再请求只有default的工具，这样实现了ChatClient实例范围和请求范围的工具

接着DefaultChatClient调用call，这个call不是真正调用Model，但做了两个关键事情

首先，偷偷的塞入了模型调用advisor，

第二，DefaultChatClientUtils.toChatClientRequest方法，构建ChatClientRequest，也是调用大模型前工具的处理方法，下面分析一下代码

DefaultChatClientUtils.toChatClientRequest

若有工具设置，新建DefaultToolCallingChatOptions代替原有的ChatOptions，DefaultToolCallingChatOptions增加了工具的属性

toolName写到新的Options

工具提供者取出ToolCallback，合并到新的Options

至此工具全部转移到新Options

最后，新建ChatClientRequest，工具Options放入Prompt

总结：

上图ChatClient构建和调用代码

*ChatModel也支持直接设置工具，ChatClient面向用户，提供更多友好机制，方便用户

*关于ChatClient，ChatModel将在系列(二)-模型详细分析，本文只关注与工具相关的部分

调用工具

上节分析工具设置，本节分析工具调用，前面介绍过，工具不是大模型直接调用，大模型返回ToolCall消息，ChatModel或拦截器调用工具，其中，拦截器可以是spring ai的Advisor，或者spring ai Alibaba的model 拦截器，ChatModel和拦截器工具调用的逻辑类似，本文分析ChatModel实现类的工具调用

上图工具调用的原理图

上节分析到ChatClient请求构建了ToolCallChatOptions，塞进Prompt，CallResponseSpec/ChatModelCallAdvisor调用大模型，两者不涉及到工具方面，直接分析ChatModel实现

下面以DeepSeekChatModel分析工具执行

工具提示词

首先分析工具提示词

DeepSeekChatModel.createRequest

DeepSeekChatOptions 是DeepSeekChatModel以传入Tool ChatOptions构建，DeepSeekChatOptions增加了放置DeepSeek的选项，ChatModel实现类都这样模式

toolCallingManager.resolveToolDefinitions

上图请求的工具解释出工具定义，解释tool name，首先看options的toolbacks有没有该名字的，这种情况属于用户重复输入，没有就用工具解释器解释

解释出工具定义，后续Chat模型的逻辑处理，这里就不深入分析

执行

工具执行是调用大模型后，返回toolcall信息，ChatModel类或者Advisor执行

DeepSeekChatModel.call

上图是ChatModel执行

toolExecutionEligibilityPredicate 断言的逻辑

如果是设置了ToolCallAdvisor，advisor会把isInternalToolExecutionEnabled设为false，留到advisor执行

returnDirect，当true，返回结果给ai应用；false，发起大模型调用，结果返回给大模型

下面分析工具调用管理器(ToolCallingManager)执行工具调用

上图是工具调用管理器类图

ToolCallingAutoConfiguration  工具调用管理器，工具解释器都是该自动配置类构建

上图是查找ToolCallback的代码，大模型给的是工具名称和参数，工具调用要做的就是根据名字找ToolCallback，

toolCallbacks是工具ChatOption的，有几个来源，

1. 用户使用MethodToolCallbackProvider抓取没在spring管理带@Tool的类，甚至底层api构建，这类不在工具解释器内
2. MPC工具，这类也不在工具解释器
3. spring管理的，这类工具解释器也有，可以传工具名称

工具解释器的来源，所有spring 管理的ToolCallBack，ToolCallBackProvider，所有带@Tool注解的function

最后，大模型使用的ToolCallback，一定是ChatClient传入，可以工具名称，也可以是ToolCallback，工具名称可能是ChatOption的ToolCallback(重复提交)，也可能是解释器的

其他

工具还有结果转换和异常处理两块，本文不深入分析