从 @Tool 到 Agent 流水线：LangChain4j 进阶教学，一个库打全套

★

本篇目标 ：在入门篇"接口即 AI 服务"的基础上，补齐工具调用、RAG、持久化记忆，最后掀开 LangChain4j 的压轴新东西------Agentic 模块：AgenticScope 共享状态、Supervisor 编排、Saga 式工具补偿。

前置知识 ：上一篇入门教学 LangChain4j 入门教学（Java 后端狂喜版）

01 复习 30 秒，然后上车

上篇你已经会把 AI 调用写成一行接口调用。但那个 PetAssistant 还只是个"只会说话的实习生"------本篇给它配齐工具箱、资料库、团队协作能力，一步步推到 Agent。

能力	上篇	本篇
说话	✅ AiServices	---
动手	❌	`@Tool` 工具调用
带资料	❌	RAG 三件套
多步自主干活	❌	Agentic 模块

02 `@Tool`：把你的 Java 方法"借"给模型

和 Spring AI 的 @Tool 思路完全一致，注解一挂，模型就能"请求调用"你的方法（记住那条铁律：模型只点单，执行永远在你的应用里）：

bash 复制代码

@Component
public class ClinicTools {

    @Tool("查询指定科室的门诊时间与剩余号源")
    public String querySchedule(
            @P("科室名称，如：内科、外科、皮肤科") String department) {
        return scheduleService.query(department);
    }

    @Tool("为指定宠物挂指定科室的号，仅当用户明确要求挂号时调用")
    public String makeAppointment(
            @P("宠物昵称") String petName,
            @P("科室名称") String department) {
        return appointmentService.book(petName, department);
    }
}

@Tool("描述")：描述写给模型看，写清"何时调用"，这是调用准确率的第一决定因素；
@P("...")：参数说明，等价于 Spring AI 的 @ToolParam；
Spring Boot 下零配置 ：@Component 类里的 @Tool 方法会被 starter 自动拾取、挂到 @AiService 接口上（上下文只有一个 AI Service 时）。

上手成本几乎为零------你在宠物门诊项目里写过的 ClinicTools，把 @ToolParam 换成 @P 就能直接复用。

03 RAG 三步走：Ingestor → Retriever → 自动挂载

LangChain4j 把 RAG 拆成离线入库 和在线检索两段、三个核心角色，比 Spring AI 的 Advisor 体系更"看得见摸得着"：

bash 复制代码

【离线】Document → EmbeddingStoreIngestor → EmbeddingStore
【在线】用户问题 → EmbeddingStoreContentRetriever → 相关片段 → 自动注入 prompt

3.1 第一步：离线入库（EmbeddingStoreIngestor）

bash 复制代码

// 解析 + 切分 + 向量化 + 入库，一个 Builder 全包
List<Document> docs = FileSystemDocumentLoader.loadDocuments(
        Path.of("docs"), new TextDocumentParser());

EmbeddingStoreIngestor.builder()
        .documentSplitter(DocumentSplitters.recursive(500, 50)) // 500 字符/块，重叠 50
        .embeddingModel(embeddingModel)                          // OpenAI 兼容向量模型
        .embeddingStore(embeddingStore)                          // InMemory / Qdrant / PgVector...
        .ingest(docs);

3.2 第二步：在线检索器（EmbeddingStoreContentRetriever）

bash 复制代码

ContentRetriever retriever = EmbeddingStoreContentRetriever.builder()
        .embeddingStore(embeddingStore)
        .embeddingModel(embeddingModel)
        .maxResults(5)      // topK
        .minScore(0.6)      // 相似度下限
        .build();

3.3 第三步：挂上就生效

bash 复制代码

PetAssistant assistant = AiServices.builder(PetAssistant.class)
        .chatModel(model)
        .contentRetriever(retriever)   // ← 挂上，之后每次提问自动检索注入
        .build();

Spring Boot 场景下更简单：把 ContentRetriever 声明为 bean，@AiService自动装配就接上了。

04 记忆进阶：`ChatMemoryProvider`，一人一仓

入门篇的 @MemoryId 默认用内存记忆。生产环境两件事必须做：按用户隔离 + 持久化：

bash 复制代码

PetAssistant assistant = AiServices.builder(PetAssistant.class)
        .chatModel(model)
        .chatMemoryProvider(memoryId -> MessageWindowChatMemory.builder()
                .id(memoryId)
                .maxMessages(20)
                .chatMemoryStore(new RedisChatMemoryStore())   // 自己实现 ChatMemoryStore 接口
                .build())
        .build();

实现一个 ChatMemoryStore（getMessages / updateMessages / deleteMessages 三个方法）就能把记忆落到 Redis / DB------接口只有一个，成本很低。

05 压轴登场：Agentic 模块，把"多步任务"编排成 Java 代码

前面所有能力里，"干什么"都是你写死的。Agent 的区别是：模型自己拆解目标、决定步骤、循环执行直到完成。 LangChain4j 1.x 后期把这块做成了独立模块 langchain4j-agentic

5.1 三个核心概念

概念	是什么	一句话理解
`@Agent`	把一个 AI Service 方法声明为"智能体"，可声明输出名、通道	每个接口方法 = 一名员工
`AgenticScope`	智能体间的共享状态容器	会议室白板，谁都能读写上游产出
编排模式	sequence / parallel / loop / conditional / supervisor	流水线、并行组、返工环、分流器、主管

5.2 骨架示例：宠物门诊的"接诊流水线"

bash 复制代码

interface TriageAgent {
    @UserMessage("根据病情{{symptom}}判断科室和紧急程度")
    @Agent("分诊")
    TriageResult triage(@V("symptom") String symptom);
}

interface ScheduleAgent {
    @UserMessage("根据分诊结果{{triageResult}}查询排班并给出挂号建议")
    @Agent(outputKey = "schedule")   // 结果写入 AgenticScope
    String schedule(@V("triageResult") TriageResult triageResult);
}

// 顺序编排：分诊 → 查排班，scope 自动传递
var flow = AgenticServices.sequenceBuilder(TriageResult.class, ChatModel.class)
        .subAgents(agenticScope -> triageAgent, agenticScope -> scheduleAgent)
        .build();

String advice = flow.invoke(Map.of("symptom", "猫吐了 3 天"));

5.3 为什么值得盯住它

几个 1.x 后期版本落地的能力，在 Java 生态里都是头一份：

Supervisor 主管模式：让一个"主管智能体"动态决定把任务派给哪个子智能体（1.12 起支持流式）；
Saga 式工具补偿 ：多个工具连续调用中途失败时，自动执行已调用工具的补偿操作（1.19）------给 Agent 加上了事务语义，挂号失败自动取消已扣的号源这种场景直接受益；
执行状态可持久化恢复（1.13）：长流程 Agent 中断后能续跑；
MCP 与 A2A 集成：把远程 MCP 工具当本地工具接、把别的 Agent 系统当子智能体接；LangChain4j 是最早跟上 MCP 新规范的 Java 框架之一。

★

💡 类比

如果 AiServices 是"把一个员工 Mapper 化"，Agentic 就是"把整个部门组织架构图写成 Java 代码"：sequence 是流水线，parallel 是并行开发组，loop 是"验收不通过就返工"，supervisor 是部门主管派活，AgenticScope 是大家的共享文档。

06 顺手的加分项：可观测性

生产化别忘两件套，都是"注册个 bean"级别的成本：

**ChatModelListener**：onRequest / onResponse / onError 三回调，自动注入所有 ChatModel，打日志、记 trace 都在这；
Micrometer 指标 ：加 langchain4j-micrometer-metrics + actuator，/actuator/metrics/gen_ai.client.token.usage 直接看 token 消耗（可按 input/output 过滤）------计费和限流的数据源就有了。

07 Spring AI vs LangChain4j：到底选哪个？

阶段3 学完必须能回答这个问题。给一张诚实的决策表：

你的情况	建议
重度 Spring 技术栈、要 Advisor 链 / 和 Spring 生态深度整合	Spring AI
非 Spring（Quarkus / Micronaut / 纯 Java）、Java 17 存量项目	LangChain4j
要最广的模型 / 向量库覆盖，或最早尝鲜 MCP / Agentic	LangChain4j
团队只维护一套框架、已有 Spring AI 投入	留在 Spring AI，概念可平移
想两边都通吃	恭喜，概念 80% 重合，切换成本低

两个框架没有技术上的碾压关系：Spring AI 的优势是"Spring 原生"，LangChain4j 的优势是"抽象更激进 + 生态跟进更快"。真实的工程选择往往取决于团队栈和运维约束，而不是功能清单。

08 总结：毕业，你已经双修了

回头盘点，LangChain4j 两篇你拿下了：ChatModel → AiServices/@AiService（Mapper 化的 AI 调用）→ @Tool 工具 → RAG 三件套 → 持久化记忆 → Agentic 编排（@Agent / AgenticScope / Supervisor / 补偿）。

至此你成了"双框架 Java AI 工程师 "：Spring AI 和 LangChain4j 的概念在脑子里已经能自由映射。这个双修视角在面试里非常值钱------面试官问"为什么选 A 不选 B"，你答的是架构权衡而不是"我用过哪个"。

下一站 ，按学习路线进入 Python 生态 ：看看 LangChain / LangGraph 的原教旨主义版本长什么样，为什么全世界的 Agent 论文示例都用 Python 写，以及 Java 工程师应该"借"哪些思想回去。之后就是终极实战：Agent 项目实战。

若对你有帮助，点赞、推荐、分享！

**关注我，**持续更新AI Agent学习内容，早日学会Agent开发！

从 @Tool 到 Agent 流水线：LangChain4j 进阶教学，一个库打全套

01 复习 30 秒，然后上车

02 @Tool：把你的 Java 方法"借"给模型

03 RAG 三步走：Ingestor → Retriever → 自动挂载

3.1 第一步：离线入库（EmbeddingStoreIngestor）

3.2 第二步：在线检索器（EmbeddingStoreContentRetriever）

3.3 第三步：挂上就生效

04 记忆进阶：ChatMemoryProvider，一人一仓

05 压轴登场：Agentic 模块，把"多步任务"编排成 Java 代码

5.1 三个核心概念

5.2 骨架示例：宠物门诊的"接诊流水线"

5.3 为什么值得盯住它

06 顺手的加分项：可观测性

07 Spring AI vs LangChain4j：到底选哪个？

08 总结：毕业，你已经双修了

02 `@Tool`：把你的 Java 方法"借"给模型

04 记忆进阶：`ChatMemoryProvider`，一人一仓