一个面向 Java 开发者的 Agent 学习型仓库。
本仓库用统一的“健康知识咨询助手”业务主线，对比三套主流 Java Agent / LLM 应用框架在工程组织、核心抽象、流程编排、工具调用、RAG、结构化输出和可观测性上的差异。

仓库目标不是只做“能跑的 Demo”，而是沉淀一套可复用的学习与开发方法：

• 可运行：每个子工程都能独立启动、测试和冒烟验证
• 可对比：三个框架在同一业务语义下横向比较
• 可复盘：每个模块都有 docs/、spec/、smoke-test/
• 可迁移：后续学习其他 Java Agent 框架时可以复用这套结构

当前包含 3 个已完成的学习子工程：

flowchart LR
    A[agent-learn-spring-ai\n基线工程] --> B[agent-learn-spring-ai-alibaba\n复杂 Agent / Graph / Workflow]
    A --> C[agent-learn-langchain4j\nAiServices / 原生 Tool / 显式编排]

    A1[Prompt\nMemory\nTool\nMCP\nStructured Output\nRAG\nState Machine] --> A
    B1[ReactAgent\nAgent Framework\nGraph Workflow\nRouting Pattern\n国内模型生态] --> B
    C1[AiServices\nChatMemory\n@Tool\nStructured Output\n应用层 Workflow] --> C

flowchart TD
    S[准备做 Java Agent / LLM 应用] --> Q1{是否优先做\n基础能力打底与稳健集成?}
    Q1 -->|是| A[优先看 Spring AI]
    Q1 -->|否| Q2{是否需要\n复杂流程编排 / 多 Agent / Graph?}
    Q2 -->|是| B[优先看 Spring AI Alibaba]
    Q2 -->|否| Q3{是否更看重\n原生 Agent 抽象与高灵活度?}
    Q3 -->|是| C[优先看 LangChain4j]
    Q3 -->|否| A

这是整个仓库的业务与文档基线工程，重点学习 Spring AI 的基础能力组合与项目自定义编排方式。

已覆盖的核心内容：

• ChatClient / LLM Provider 接入
• Prompt 工程与角色边界控制
• 会话记忆与事实抽取
• Tool Calling
• MCP Client 集成
• Structured Output
• RAG 检索增强
• State Machine Workflow
• 可观测性、测试与评测

适合理解的问题：

• 一个“纯 Spring 风格”的 AI 应用如何逐步搭起来
• 不依赖重型 Agent 框架时，如何自己组织业务编排
• Spring AI 的原子能力如何组合成完整业务链路

入口文档：

• agent-learn-spring-ai/README.md

这是在 Spring AI 基线上，进一步学习 Spring AI Alibaba 增强能力的工程，重点放在 Agent Framework、Graph / Workflow、上下文工程和更贴近国内模型生态的接入体验。

已覆盖的核心内容：

• ReactAgent 主链路
• Agent Framework 组织方式
• Graph / Workflow 编排
• 工具调用、RAG、结构化分诊
• Routing 模式最小示例
• traceId、日志串联、评测与复盘
• DashScope 与 Anthropic-compatible 双 Provider

适合理解的问题：

• 当业务进入多步骤、多分支时，框架如何帮你组织 Agent 系统
• 相比原生 Spring AI，哪些流程治理能力可以交给框架
• 在国内企业环境下，Spring AI Alibaba 的工程价值体现在哪里

入口文档：

• agent-learn-spring-ai-alibaba/README.md

这是基于 LangChain4j 的对比工程，重点学习 AiServices、原生 Tool Calling、ChatMemory、Structured Output，以及“框架能力 + 应用层显式编排”的组合方式。

已覆盖的核心内容：

• AiServices 接口式 Agent
• 单一记忆源的会话管理
• 原生 @Tool / @P Tool Calling
• RAG 最小闭环
• /api/triage 结构化输出
• 应用层 Workflow 编排
• 模式对比、测试评测、文档复盘
• DashScope 与 Anthropic-compatible 双 Provider

适合理解的问题：

• LangChain4j 的“自然写法”是什么
• 什么能力适合用框架原生抽象，什么能力更适合在应用层补足
• 不依赖图式工作流框架时，如何用显式编排保持链路清晰

入口文档：

• agent-learn-langchain4j/README.md

Spring AI 更突出：

• Spring 生态一致性好
• 基础能力齐全，适合从零搭完整链路
• 更适合作为“Java AI 应用基线框架”
• MCP、Structured Output、Prompt / Memory / Tool 组合路径清晰

Spring AI Alibaba 更突出：

• Agent Framework 更完整
• Graph / Workflow 能力更适合复杂流程
• 多 Agent 模式表达更自然
• 国内模型生态接入更友好
• 更贴近企业级 Agent 平台化、治理化诉求

LangChain4j 更突出：

• AiServices 接口式抽象简洁
• Tool Calling、Memory、Structured Output 组合自然
• 原生感强，适合快速做 Agent 组件实验
• 灵活度高，不强制你接受一套重型流程框架

适合：

• 你已经在 Spring Boot 体系里，希望先稳定接入 LLM 能力
• 场景以单 Agent、单链路应用为主
• 你希望对 Prompt、Memory、Tool、RAG 的工程组织保持较强自控
• 你要先做一套“容易理解、容易调试、容易打基线”的项目

典型场景：

• 企业知识问答
• 内部 Copilot
• 客服辅助问答
• 结构化抽取、分诊、表单辅助填写

适合：

• 流程明显更复杂，已经进入多步骤、多分支、多 Agent 组织阶段
• 你希望更系统地表达 Graph / Workflow / Agent Pattern
• 项目更偏企业平台化、流程治理和国内模型生态接入
• 团队可以接受更高的抽象与学习成本，换取更强的流程表达力

典型场景：

• 多阶段审批 / SOP Agent
• 路由型、顺序型、多 Agent 协同系统
• 复杂服务编排型企业 Agent
• 需要更强流程控制和治理能力的内部智能平台

适合：

• 你想更直接地学习 Agent 核心机制，而不先被较重的框架抽象包住
• 你要快速试验 AiServices、Tool Calling、Memory、RAG 等核心能力
• 你希望应用层保留较高自由度，自行决定 workflow 要做到什么程度
• 你要做“中等复杂度”的 Agent 应用，但不想一开始就上图式工作流

典型场景：

• 原型验证
• 教学项目
• 中小型 Agent 服务
• 需要灵活试验不同 Agent 设计模式的研发场景

如果你的目标是“先学会 Java AI 应用开发”，优先看 agent-learn-spring-ai。
如果你的目标是“进入复杂 Agent 编排和企业流程治理”，重点看 agent-learn-spring-ai-alibaba。
如果你的目标是“掌握 Agent 核心机制并保持高灵活度”，重点看 agent-learn-langchain4j。

可以把三者理解成三种不同风格：

• Spring AI：基础扎实、工程中性、适合打基线
• Spring AI Alibaba：编排更强、平台感更强、适合复杂流程
• LangChain4j：抽象直接、灵活度高、适合做 Agent 原生实验

推荐按下面顺序学习：

1. agent-learn-spring-ai
2. agent-learn-spring-ai-alibaba
3. agent-learn-langchain4j

这样最容易建立完整认知：

• 先理解基础能力如何组合
• 再理解更强的 Agent / Workflow 框架如何接管复杂流程
• 最后再理解另一套更原生、更灵活的 Agent 抽象方式

这个仓库最终沉淀的，不只是三个 Demo，而是三种 Java Agent 工程思路：

• 基于 Spring 基线能力做稳健组合
• 基于框架增强能力做复杂流程编排
• 基于原生 Agent 组件做灵活实验与快速迭代

如果后续继续扩展新框架，建议保持当前统一结构：

• README.md
• docs/
• spec/
• smoke-test/

这样新的学习工程可以继续在同一业务基线下横向比较，而不用每次都重新从零搭方法论。