Langchain4j - Skill 简单案例
Skill 简介
是什么?
Agent Skill 本质上是给 AI 打包好的 “专业能力模块”,一个包含指令、脚本和资源的文件夹,让 AI 从 “会聊天” 变成 “会干活”。它解决了传统 Prompt 每次重复输入、输出不稳定的痛点,把工作流程固化成可复用的技能包。在技术形态上,一个 Skill 通常是以标准化的 Markdown / YAML 文件形式存在(例如包含元数据的 SKILL.md),它集成了:
- 触发意图:定义什么场景下该激活此技能。
- 流程规范:告诉 LLM 具体的步骤逻辑(如:“重构代码时,必须先跑单元测试,再遵循 DRY 原则,最后检查类型定义”)。
- 上下文知识:特定项目或领域的专有信息。
- 可执行脚本/工具引用:附带的本地 Python/Shell 脚本或命令行调用范式。
解决什么问题?
在 Agent Skill 出现之前,让 AI 执行复杂任务主要依赖系统提示词(System Prompt)或动态检索(RAG)。这带来了三个痛点,也是 Skill 出现的关键原因:
- 解决上下文窗口爆炸与 Token 成本过高问题。如果把所有业务流程和所有工具的完整说明都一股脑写入全局 Prompt,每次对话都会消耗成千上万 Token,且容易导致模型 “迷失在细节中”。Skill 引入了渐进式暴露机制:初始时只加载 Skill 的 “名称与简短描述”(仅耗费百来 Token),只有当用户意图匹配时,Agent 才按需将具体的 SKILL.md 内容展开加载到上下文。
- 解决 AI “懂工具但不懂业务逻辑/规范” 的问题。即便 AI 拥有调用 API 的能力,它依然不知道你团队内部的约束(例如:“代码提交前必须包含哪些 CI 检查”或“如何按照公司的特定架构模式编写业务代码”)。Skill 将“知识”与“步骤”封装在一起,约束 Agent 行为。
- 解决可复用性与模块化问题。以前针对特定场景的复杂 Prompt 很难在团队间共享与版本控制。Skill 提供了轻量化、类似 “软件包” 的目录结构,让知识和工作流可以像 Git 仓库一样进行版本管控、团队协同与生态分发。
Java 领域的支持
目前,LangChain4j(>=1.12.x)和 Spring AI(2.0.0+)目前都已原生支持或通过标准扩展支持了 Agent Skill(以 SKILL.md 规范为核心)。针对 Java AI 生态的两大主流框架,实现细节与技术路线有所差异:
- LangChain4j 的支持情况:
- LangChain4j 将 Skill 抽象为一种渐进式动态加载上下文与工具链的机制。
- 延迟加载(Lazy Context Injection):启动时只扫描 SKILL.md 的 Frontmatter(即 YAML 头部定义的 name 和 description),并将其注册为路由元数据(非常节省 Prompt Token)。
- 动态激活:当 LLM 判定需要执行某个复合任务(如 process-order)时,会自动触发 Skill 加载工具。
- 指令注入:SKILL.md 正文中的 Markdown 操作规范(SOP)会被当作动态上下文注入当前对话,LLM 随后遵照 SOP 去依次调用关联的 Java @Tool 方法。
- Spring AI 的支持:
- Spring AI 将 Skill 接入到了其原有的 Function Call / Tool / Advisor 架构 体系中,不仅支持经典的 Spring Bean 声明式技能,还支持直接解析类路径或文件系统中的 SKILL.md 规范。Spring AI 的 AgentUtils 框架通过动态 Tool 机制,把 Skill 转化成系统内部可调用的“高阶元工具”。LLM 触发 Skill 后,SKILL.md 的内容会作为 Tool Result 返回给模型,驱动模型在下一步的推理链中按照 SOP 执行后续行动。
- 配置与使用方式:
- 定义静态 Skill:将封装好的 Skill 文件夹置于项目资源目录或外部存储服务中。
- Auto-Configuration(自动装配):Spring AI 自动扫描容器中的 SkillManager / AgentSkill 节点。
- 与 MCP / Functions 协同:在 Spring AI 中,Skill 通常用来编排那些通过 @Bean 注入的 FunctionCallback 或者从外部 MCP Server 导入过来的原生 Tools。
| 维度 | LangChain4j | Spring AI |
|---|---|---|
| 支持方式 | 原生抽象组件,基于 SKILL.md 文件路由与 Tool 编排 | 结合 Advisor/Tool 机制与 agentskills.io 规格整合 |
| 技能来源 | 本地 Classpath 文件系统、代码动态注册 | Spring Bean、本地文件、外部代理技能仓库 |
| 执行载体 | Java 本地 @Tool 方法、嵌入式 ToolProvider | Spring FunctionCallback、Spring Bean、MCP Tools |
| 主要优势 | 代码侵入性极低,轻量,适合构建纯 Java 智能体(Agent) | 企业级扩展性强,天然整合 Spring 生态的配置管理与安全体系 |
在当前的 Java AI 体系中,Skill 已经被两大框架作为编排复杂业务 SOP 的标准载体。在实际落地时,往往采用 “MCP 负责提供底层安全的接口连接 + Skill 文件负责定义上层业务逻辑 SOP” 的组合模式,直接在 Java 项目中即可快速落地。
Hello World 案例
为了帮助你快速验证,我们以下面 “客户订单处理场景” 构建一个最简 Langchain4j 示例。
- AI 本身并不知道订单处理的合规流转顺序;
- 我们通过一个包含 SKILL.md 的技能包,告知 AI 在处理订单时,必须按照 “验证订单 -> 预留库存 -> 扣款 -> 发确认邮件” 的 SOP 执行;
- 当用户发出指令时,LangChain4j 会自动激活 Skill,并将 Markdown SOP 的指示约束传递给 LLM 逐步调用对应的 Java 工具(@Tool)。
核心代码
依赖配置:
1 | <dependencies> |
Skill 标准元文件:src/main/resources/skills/process-order/SKILL.md
1 | --- |
简易 SKILL.md 解析器与实体类:AgentSkill。因为 SKILL.md 本质是一个带 Frontmatter (YAML) 的 Markdown 文件,我们可以写一个极其轻量的加载器读取它(这也是 LangChain4j 社区官方推荐的扩展范式):
1 | import java.io.IOException; |
定义供 Skill 在 SOP 流程中调用的工具:OrderTools.java
1 | import dev.langchain4j.agent.tool.Tool; |
动态工具提供者:OrderToolProvider,LangChain4j 提供了强大的 ToolProvider 机制。如果 Skill 匹配,才将工具暴露给 LLM,实现低 Token 开销与动态调配:
1 | import dev.langchain4j.agent.tool.ToolSpecification; |
定义 AI 接口:OrderAssistant
1 | import dev.langchain4j.service.SystemMessage; |
主程序入口:OrderProcessingApp
1 | import dev.langchain4j.model.chat.ChatModel; |
测试结果
1 | 加载技能成功: process-order |
测试中,我们看到:
- 场景 1和 2(暴露 Tool):Prompt Tokens 达到 684,带上了完整的 Function Definition 模式。
- 场景 3(不暴露 Tool):Prompt Tokens 仅有 196(节约了约 71% 的输入 Token)。对闲聊或无意图请求屏蔽工具,显著降低了 LLM API 的单次响应成本与耗时。在未识别到特定意图时不向模型透出真实 API 的 Schema,杜绝了非相关对话中被 Prompt 注入(Prompt Injection)误触发敏感接口(如扣款、发邮件)的风险。
- 在场景 1 的第二次请求日志中,prompt_tokens_details 出现了 cached_tokens: 512。LangChain4j 配合阿里云 DashScope 兼容接口,在多轮 ReAct 交互中触发了服务端的 Prompt Cache(KV 缓存)。虽然 Agent 经历多轮 HTTP 往返(RTT),但系统 Prompt 及前面的历史消息被命中缓存,大大降低了高频工具调用时的推理延迟与计费。
- 从场景 3 日志看,即使未暴露 Tool,System Prompt 依然携带了“订单处理规范指南”的文字。若希望进一步节省 Token,可以在识别为闲聊时,连同 System Prompt 中的 SOP 正文也一并置空/替换为普通通用 Prompt。另外,在场景 1 和场景 2 的最终回复中,LLM 输出了漂亮 Markdown 格式报告。如果下游系统(如前端 UI)需要解析结构化状态,可利用 LangChain4j 的 AiServices 返回值对象(DTO)或在 Prompt 中规范 JSON 输出,这样更利于系统展示。
多个 skill 案例
当从单个 Skill 扩展到多个 Skill(例如:在包含 “处理订单”的基础上,再新增一个 “退款申请 refund-request” 或 “开具发票 issue-invoice”)时,核心问题变成了:系统如何让 LLM 在几十上百个 Skill 中,只选择并加载当前需要的那个 Skill,从而避免 Token 爆表?这就用到了前文提到的关键机制——渐进式暴露与元数据路由。
Skill 文件组织结构
1 | src/main/resources/ |
新增的 skills/refund-request/SKILL.md 示例:
1 | --- |
关键的两阶段路由
为了不让所有 SKILL.md 的完整 SOP 内容同时塞进 System Prompt,工程上会分为两个阶段:
1 | [用户输入] |
多 Skill 实现代码
第一,扩展 AgentSkill 加载器(支持加载目录下的所有 Skill):
1 | import java.io.IOException; |
构建 SkillManager 技能注册表:用于集中管理系统中所有的 Skill,并生成给 LLM 看的 “轻量级技能目录”。
1 | import java.util.*; |
定义全量底层工具库(包含订单与退款等不同模块 Tool)
1 | import dev.langchain4j.agent.tool.Tool; |
改造 AI Service 接口(动态感知多 Skill 上下文)
1 | import dev.langchain4j.service.SystemMessage; |
组装主程序:根据意图选择匹配的 Skill
1 | import dev.langchain4j.model.chat.ChatModel; |
测试结果
1 | ========== 场景 A:触发订单处理 Skill ========== |
我们看到:
- 在处理退款(场景 B)时,系统只把 refund-request 的 3 步 SOP 传给了模型,完全没有传递 process-order 包含验证、扣款、发邮件等繁琐 SOP 的长文本。
- 当用户做退款操作时,模型受限于 refund-request 的 SOP 指引,绝对不会跳去调用 validateOrder 或 chargePayment,保证了业务流转的准确性。
- 今后无论新增多少个 Skill(如 issue-invoice、change-address),只需新建一个 SKILL.md 文件并向 SkillManager 注册即可,无需改动核心路由和业务代码!
实现自动判定意图
刚刚上面的测试中,我们是手动把某个 Skil 塞给 assistant.chat 接口的,但在多 Skill 架构中,手动把某个 Skill 塞给 AI 是不符合 Agent 自动化诉求的。真正的动态 Agent 机制是:Agent 先看到“技能目录”,根据用户的输入“自主判定意图”,然后自动去按需加载对应的 SKILL.md 正文并执行。
在 LangChain4j 中,实现这一机制有两种方案:
- 轻量路由器模式:先用一次极轻量的 LLM 调用(或关键词匹配)完成意图识别,选中 Skill 后再调用主 Agent。(推荐,省 Token 且逻辑可控)
- ReAct 动态工具模式:给 LLM 提供一个专门用于“激活技能”的工具,让主 Agent 在 ReAct 循环中自己决定什么时候调用该工具去读取 SKILL.md。
下面我们采用工程落地的最佳实践 ——【方案 1:轻量意图路由器 + 动态 Skill 调配】,构建一个完全可运行的 100% 自动匹配代码。
1 | [用户输入: "我想把 ORD002 的钱退了"] |
完整代码实现
代码结构:
1 | ├── pom.xml |
SkillRouter:定义意图路由器接口
1 | import dev.langchain4j.service.SystemMessage; |
MultiSkillAssistant:AI 助手主接口,主 Agent 用于接收动态路由好的 SOP 正文并执行:
1 | import dev.langchain4j.service.SystemMessage; |
SkillManager:增强版 SkillManager(带路由与自动加载能力)
1 | import java.util.*; |
AutoSkillApp入口:这里将路由判定、Skill SOP 选取、Tool 挂载全流程自动化封装为一个入口方法。
1 | import dev.langchain4j.model.chat.ChatModel; |
测试结果
1 | ------------------------------------------------ |
这种设计模式的核心优势:
- 精准控制 Token 消耗:第一阶段路由(Router)消耗极少(几十 Tokens);第二阶段主 Agent 只加载选中的单一 SKILL.md,彻底解决了多个业务 SOP 混在一起导致 Context 爆炸的问题。
- 零硬编码扩展:以后新增 Skill(比如 change-address),只需在类路径下放一个新的 skills/change-address/SKILL.md 并在 SkillManager 注册即可,路由与装载逻辑完全通用。
- 消除 LLM 幻觉:在做退款任务时,主 Agent 的 Prompt 里完全没有订单扣款或发送确认邮件的 SOP 规范,从根本上杜绝了 LLM 跨业务流程误操作的可能性。
对 MCP 的支持
另外,LangChain4j 完全可以通过集成 MCP 来为 Agent 提供和加载 Skill。传统上,SKILL 通常以本地 SKILL.md(Prompt SOP + 本地 Java @Tool)的形式存在。而在 MCP 架构下,Skill 被进一步微服务化/解耦化:
- MCP Tool 充当动态技能组件:MCP 服务端(MCP Server)可以向 LangChain4j 客户端动态暴露 Tools、Prompts(即 SOP 模版)以及 Resources。
- 免编译、动态接入:LangChain4j 可以在运行时通过 McpToolProvider 或 McpClient 从远程或本地 MCP Server 动态拉取最新的工具定义和提示词。新增或修改一个 Skill,完全不需要重新编译 Java 代码或重启服务。
代码示例
1 | <dependency> |
在 LangChain4j 中,结合 MCP 加载 Skill 工具主要有两种常见模式:
方案 1:静态/启动时绑定 MCP Skill Tools
如果你的 MCP Server(比如一个专门处理订单业务的 order-mcp-server)提供了该 Skill 所需的所有工具,可以直接将其转为 LangChain4j 的 ToolProvider:
1 | import dev.langchain4j.mcp.McpToolProvider; |
方案 2:基于意图路由动态选择并加载 MCP Skill(最佳实践)
如果存在多个 MCP Server(例如 order-mcp-server、refund-mcp-server、inventory-mcp-server),且你不希望一次性把所有 MCP 工具都透出给 LLM(避免 Token 浪费与幻觉),结合前面的路由机制,可以在运行时动态按需选择 MCP 工具:
1 | import dev.langchain4j.agent.tool.ToolSpecification; |
实践套路
- MCP Prompts 与 SKILL.md 的映射:MCP 协议自带 Prompts 规范(prompts/list 与 prompts/get)。你可以把 SKILL.md 中的标准 SOP 写入 MCP Server 的 Prompt 定义中。LangChain4j Agent 在激活某个 Skill 时,通过 MCP 获取对应的 System Prompt SOP + Tool 列表,实现 SOP 与工具的全套动态装载。
- 传输协议选择:如果是本地/单体部署,使用 StdioMcpTransport(通过子进程 stdin/stdout 通信),适合与本地 Python/Node.js 编写的技能工具配合;如果是分布式微服务,使用 SseMcpTransport(基于 HTTP Server-Sent Events),将 Skill 工具打包成独立的云端微服务,LangChain4j 作为 MCP Client 远程调用。