简介

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

系列内容：

系列(一) 架构  完成
系列(二) 调用 skills；工具；MCP  
系列(三) 模型，chat模型; chat client，提示词，消息，结构化转换；advisor组件；chat记忆
系列(六) RAG 知识库，文档读取，分块，嵌入，向量store；检索，增强生成；混合检索，融合  重排
系列(四) graph：节点和边，StateGraph，CompiledGraph；执行
系列(五) agent，ReactAgent, AgentLlmNode, AgentToolNode；钩子和拦截器，上下文工程 
系列(七) MAS，FlowAgent，子agent，agent tool；handoffs模式，toolcalling模式；A2A，大规模集群
系列(八) 评估
系列(九) 观测
agent管理平台(admin) agent发布，列表，提示词管理，会话管理，skill管理；评估；观测

本文分析外部调用III skills

based spring ai alibaba v1.1.2.2，spring ai v1.1.2

关键词

skills

缩写

spring ai 缩写sa

spring ai alibaba  本文缩写saa

参考资料

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

组件视图

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

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

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

调用(calling)  调用包括工具，mcp， skills，CLI，

RAG 

MAS  多个agent协同工作，agent集群/蜂群

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

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

本文分析的skill属于外部调用场景

调用

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

Skills

        skills是目前最新的调用方式，可以认为skills是任务的操作手册，大模型学习skill手册完成完整的功能，skill利用现有工具，通过提示词，大模型便完成新功能，作为对比，使用工具，MCP，需要开发。skilll渐进式披露机制，减少提示词的规模。

         同时，我们也看到skill的问题，调试工作比较复杂，没有断点，目前只有依赖可观测，大模型理解是不是正确的，开展的工作是不是正确的。

saa支持skills，sa还没有支持

设计原理

本节分析saa的skill类设计，工作的原理

上图skills及其相关设计类图

SkillsAgentHook 负责初始化SkillsInterceptor，给SkillsInterceptor设置SkillRegistry，向agent框架提供该拦截器；负责初始化ReadSkillTool，向agent框架提供ReadSkillTool

SkillsInterceptor 负责生成skills摘要说明，给model请求增加skills用到的工具

        GroupedTools 以skill分组的工具，这是渐进披露的一部分，提示词只包含skills需要的工具

SkillRegistry  skills注册器，拥有SystemPromptTemplate，用于生成skills摘要说明，最后合并到系统提示词

ReadSkillTool  工具，BiFunction实现，返回String，也就是skills的详细说明

关于groupedTools

groupedTools是渐进披露的一部分，提示词只写入skill使用到的工具，但目前需要手动设置，Skill.md没有标准的属性存放skill使用的工具。据了解，目前社区有各自的解决方案，个人觉得Skill.md增加标准字段allowed-tools是比较好的方案。

skill注册

本节分析skill注册

上图skills注册类图

SkillMetadata  skill的元素据，包括名称，说明，详细内容等，其中source有两种，user,  project

skills注册有两个实现，ClasspathSkillRegistry和FileSystemSkillRegistry，两者都是从文件/文件夹载入skills，前者是jar包，后者本地文件夹

SkillRegistry实现提供SystemPromptTemplate，用于生成skills详细说明，

skill描述

大模型是通过skill描述学习skill，skill描述可分为摘要描述和完整描述，这也是渐进式披露的核心

skill摘要

用户输入查询，调用agent，agent提取skills的名字和描述，写入系统提示词，skills的名字和描述内容少，不会让提示词爆炸式增长，完整的描述通常内容多

SkillsInterceptor.interceptModel

buildSkillsPrompt方法拼接skills的名称，描述成字符串

buildSkillsPrompt

skills_list, skills_load_instructins为系统提示词模板的占位符

大模型怎么学会skills

agent偷偷的通过系统提示词模板塞了一份skills说明给大模型。

skills_list skill的名称列表，解释了read_skill使用，skills_load_instructins是skills文件位置信息，没有使用

skill详细说明

大模型从系统提示词获得skills摘要，若用户问题适用某个skill，大模型调用`read_skill`工具，即类设计介绍的ReadSkillTool，获取skill的详细说明，如下图

ReadSkillTool

大模型获得skill使用详细的使用指南，学习skill

示例分析

本节分析skill示例代码，saa的skills example，类似text2sql的示例，用户输入分析需求，返回sql

示例结构

本节分析示例结构

上图是示例的结构

上图配置类，声明skills注册类，SkillsAgentHook，ReactAgent

上图是示例执行类，应用启动后runner直接调起测试，查询：

"Write a SQL query to find all customers who made orders over $1000 in the last month"

客户销售查询，应用集成了studio，可以使用chat ui测试

上图sales_analytics Skill.md示例，可以预见，runner的请求，大模型使用sales_analytics skill

观测示例运行

本节使用ide的debug，观测示例skills的运行

构建skills摘要提示词

 skills注册了两个skills

skills的摘要合并到系统提示词，上图红框是上面提到的系统提示词模板的skills列表

大模型返回tool call

AgentToolNode

大模型返回toolCalls，read_skill，参数 {"skill_name": "sales_analytics"}

*ChatModel实现类(如，DashScopeChatModel)也负责处理工具调用，默认开关设为否，返回到AgentToolNode处理，系列(二)-agent/graph详细分析

调用read_skill

大模型调用read_skill工具，获取skill详细说明

生成sql

最后返回大模型的思路和生成sql

总结：示例比较简单，但也足够清晰描述skills的工作原理，渐进式披露原理。skills是用户描述好任务，剩下的大模型理解和执行，从中看到AGI的影子，只需要基本工具，任务描述好，大模型可以学会新的功能。另外，我们也提到，skills的正确性依赖开发人员的描述和大模型的理解，在两者中间，开发人员使用可观测调整和迭代skills。