AI Agent 开发入门学习路线 —— Java 版

面向 Java 开发者，从零到能独立开发一个可用 Agent 的完整路线。

前置假设：你已具备 Java 基础（Spring Boot、Maven/Gradle、多线程）。

〇、先说结论：Java 能做 Agent 吗？

能，而且越来越能。 虽然 Python 生态在 AI 领域领先半个身位，但 Java 生态的 Agent 开发体系已基本成熟：

• Spring AI 对标 LangChain，Spring 生态原生集成

• LangChain4j 是 LangChain 的 Java 移植，社区活跃

• 生产环境中 Java 在稳定性、可观测性、企业集成方面有天然优势

如果你的团队技术栈是 Java，完全没必要为了做 Agent 切到 Python。

一、核心认知：Agent 到底是什么

一句话：Agent 是一个能自主感知环境、制定计划、调用工具、完成多步任务的 AI 系统。

Agent = LLM + 规划(Planning) + 工具(Tools) + 记忆(Memory)

与普通 ChatBot 的关键区别：

二、Java AI 生态概览（先看地图再出发）

2.1 核心框架

怎么选？

• Spring 技术栈团队 → Spring AI（原生 DI、自动配置、Actuator 监控）

• 想跟 LangChain 社区文档走 → LangChain4j（概念一脉相承，迁移成本低）

• 建议两个都了解一下，核心概念互通

2.2 周边生态

2.3 需要提前了解的 LLM 概念

跟 Java 无关，但做 Agent 必须懂：

• Token：计费单位，不是字数。英文 1 token ≈ 0.75 词，中文 1 token ≈ 0.5 字

• Context Window：一次请求能塞多少 token（决定你能给 Agent 多少上下文）

• Temperature：0=每次输出一致，1=有创造性

• System Prompt vs User Prompt：角色设定 vs 具体问题

• Function Calling / Tool Use：LLM 选择调用哪个函数，这是 Agent 的"手"

• RAG：给 LLM 外挂知识库，检索相关内容塞进 prompt

先花半天搞定 Spring AI 或 LangChain4j 的 quickstart，体验一下 Java 调用 LLM。

三、Agent 四大核心支柱（重点，2 周深入）

3.1 规划（Planning）

Agent 怎么把"帮我调研一下 Spring AI 的最佳实践"拆成可执行的步骤？

• ReAct（Reasoning + Acting）：

  思考 → 行动 → 观察结果 → 再思考 → 再行动 → ... → 完成

  这是最经典的 Agent 模式，理解它就理解了 Agent 的本质。

• Plan-and-Execute：先出完整计划，再逐步执行

• Reflection：执行完自我检查，发现错误就修正

关键实践：不依赖任何框架，用纯 Java + OkHttp/WebClient 调用 OpenAI API，手写一个 ReAct 循环。这是理解 Agent 最快的方式。

伪代码框架：

while (!finished) {
 var thought = llm.think(context, tools);
 if (thought.isFinalAnswer()) break;
 var result = executeTool(thought.getToolName(), thought.getArgs());
 context.add(result);
}

3.2 工具使用（Tool Use）

Agent 不能只会聊天，必须能做事。

Java 中的工具定义方式：

// Spring AI 方式 —— 用 @Tool 注解
@Tool(description = "搜索指定股票的最新价格")
public StockPrice getStockPrice(@ToolParam(description = "股票代码") String symbol) {
    return stockService.query(symbol);
}
​
// LangChain4j 方式 —— 用 @Tool 注解
@Tool("查询订单状态")
public OrderStatus queryOrder(@P("订单ID") String orderId) {
    return orderService.findById(orderId);
}

工具设计原则：

• 单一职责，一个工具只做一件事

• 清晰的 description（这是给 LLM 看的，决定它会不会选对工具）

• 参数类型明确 + 描述清晰

• 处理好异常，不要让 LLM 看到堆栈信息

3.3 记忆系统（Memory）

Spring AI 的方案：

• ChatMemory 接口，内置 InMemoryChatMemory、CassandraChatMemory 等实现

• 向量存储：VectorStore 接口，支持 PgVector、Redis、Milvus 等多种后端

3.4 多 Agent 协作

Java 生态的多 Agent 方案不如 Python 的 CrewAI 那样开箱即用，但可以用 Spring AI 或 LangChain4j 自己编排：

常见协作模式：

1. 流水线：Agent A 输出 → Agent B 输入（串行）

2. 并发：多个 Agent 同时执行，汇总结果（适合代码 Review、多维度评估）

3. 对话：Agent 之间互相通信协调（可以用消息队列或直接方法调用）

四、框架深入实战（4-6 周）

4.1 Spring AI 核心模块（2-3 周）

Spring AI 是现阶段 Java Agent 开发的首选。

学习路径：

关键代码示例 —— Spring AI 中的 Agent：

@RestController
public class AgentController {
​
    private final ChatClient chatClient;
​
    // 注册工具
    @Bean
    public ToolCallback[] tools(OrderService orderService) {
        return ToolCallbacks.from(orderService);
    }
​
    @PostMapping("/agent/chat")
    public Flux<String> chat(@RequestBody String userMessage) {
        return chatClient.prompt()
            .user(userMessage)
            .tools(tools)      // 注入工具
            .stream()
            .content();
    }
}

Spring AI 会自动处理：LLM 决定调用哪个工具 → 执行对应方法 → 把结果还给 LLM → 继续推理。

4.2 LangChain4j 速览（1-2 周）

如果团队不绑定 Spring，或者想跟 LangChain 社区文档走，LangChain4j 是很好的选择。

核心 API：

// 定义工具
@Tool("搜索网页内容")
String searchWeb(@P("搜索关键词") String query) { ... }
​
// 构建 Agent
AiServices.builder(Assistant.class)
    .chatLanguageModel(model)
    .tools(new WebSearchTool())
    .chatMemory(MessageWindowChatMemory.withMaxMessages(20))
    .build();

LangChain4j 特色：

• AiServices：声明式 Agent 接口，像写 MyBatis Mapper 一样定义 Agent

• 与 Quarkus、Micronaut 良好集成

• 对多种 LLM 提供商都有适配器

4.3 MCP（Model Context Protocol）（1 周）

Anthropic 提出的开放协议，相当于"工具调用的 USB-C 接口"——统一标准，一次编写，所有 Agent 都能用。

Java 中实践 MCP：

// 方式一：Spring AI MCP Boot Starter
// 引入依赖后，配置 mcp.client.connection 即可自动发现远端工具
​
// 方式二：LangChain4j MCP
McpClient mcpClient = new DefaultMcpClient.Builder()
    .transport(new StdioMcpTransport("path/to/mcp-server"))
    .build();
​
// 获取远端工具并注入 Agent
List<ToolSpecification> remoteTools = mcpClient.listTools();

MCP 的价值：你的 Agent 可以直接复用社区里成百上千个现成 MCP Server（搜索引擎、数据库、文件系统、GitHub API...），不用自己写工具代码。

五、渐进式项目实战（核心环节）

项目 1：命令行 Todo Agent（3-5 天）

• 目标：理解 Agent 循环本质

• 技术：纯 Java + OkHttp + OpenAI API（不用任何 AI 框架）

• 实现：手写 ReAct 循环，手动解析 LLM 返回的 function call

• 验收：自然语言输入"明天下午提醒我开会"，能正确调 addTodo() 方法

项目 2：企业内部知识库问答（1-2 周）

• 目标：掌握 RAG 全流程

• 技术：Spring AI + PgVector/Redis + Apache Tika 文档解析

• 流程：文档上传 → 解析 → 切片 → 向量化 → 存入向量库 → 检索 → 增强 → 生成

• 验收：上传公司制度文档，能用自然语言准确提问并得到带引用的回答

项目 3：智能客服工单 Agent（2-3 周）

• 目标：完整的业务 Agent

• 功能：

  • 理解用户问题，分类（咨询/投诉/故障报修）

  • 查知识库回答简单问题

  • 复杂问题自动创建工单、分配处理人

  • 查询工单进度

• 技术：Spring AI + 数据库 + 工单系统 API

• 关键点：多工具编排、Human-in-the-loop（升级人工客服时介入）

项目 4：技术调研报告 Agent（2 周）

• 目标：多步规划 + 外部工具串联

• 功能：输入技术主题 → 制定搜索计划 → 多轮搜索 → 信息整合 → 生成 Markdown 报告

• 技术：LangChain4j + Web Search API + 文件输出

• 验收：对"Spring AI vs LangChain4j 选型对比"产出一份结构化报告

项目 5（进阶）：代码审查 Agent

• 功能：读取 Git 仓库 MR/PR → 多维度审查（代码规范、安全性、性能） → 输出审查报告

• 技术：Spring AI + Git API（JGit/GitLab API）+ 多个专用 Agent

• 验收：能对真实 PR 提出有参考价值的审查意见

六、生产化考量（Java 的强项）

6.1 架构设计

┌─────────────────────────────────────────┐
│              API Gateway                 │
├─────────────────────────────────────────┤
│           Agent Service (Spring Boot)    │
│  ┌─────────┐ ┌──────────┐ ┌──────────┐  │
│  │ Planner │ │ Executor │ │ Reflector│  │
│  └─────────┘ └──────────┘ └──────────┘  │
│  ┌─────────┐ ┌──────────┐ ┌──────────┐  │
│  │ Memory  │ │Tool Registry│ │  MCP   │  │
│  └─────────┘ └──────────┘ └──────────┘  │
├─────────────────────────────────────────┤
│  Redis    │  PostgreSQL  │  Message Queue│
└─────────────────────────────────────────┘

6.2 Java 生态优势

• 可观测性：Micrometer + Prometheus + Grafana 开箱即用，监控 token 消耗、工具调用耗时

• 异步处理：Reactor / WebFlux 原生支持 SSE 流式响应

• 稳定性：完善的连接池、熔断（Resilience4j）、重试机制

• 任务持久化：长任务存数据库，服务重启不丢状态

• 企业集成：天然对接 SSO、权限系统、审计日志

6.3 需要特别注意的

• 线程安全：ChatMemory 等有状态组件在多线程下的保护

• Token 消耗监控：Agent 循环会放大 token 消耗，必须做费用追踪

• 超时控制：Agent 可能无限循环，必须设置最大步数 + 总超时

• 工具调用的幂等性：Agent 可能重复调用同一个工具

七、推荐学习节奏（8-12 周）

八、学习资源

框架文档

• Spring AI 官方文档 —— 必读

• LangChain4j 官方文档 —— 必读

• Spring AI MCP 文档

必读文章

• Anthropic - Building Effective Agents —— Agent 设计理念圣经

• Lilian Weng - LLM Powered Autonomous Agents —— 经典综述

• Spring 官方博客 - Spring AI 系列

示例项目

• Spring AI 官方示例

• LangChain4j 示例

九、避坑指南

1. 别上来就学框架。先用 Java 手写一个 ReAct 循环，理解了再上 Spring AI。

2. Prompt 是第一武器。加了 @Tool 不代表 Agent 就会用了——工具的 description 写得好不好，直接决定 LLM 会不会选对工具。

3. Agent 不总是答案。能用 if-else / 规则引擎 / 状态机解决的，别上 Agent。Agent 贵、慢、不稳定。

4. 控制循环上限。Agent 最容易出的问题是无限循环或步数爆炸，务必设 maxIterations。

5. 工具做好异常处理。LLM 拿到一个 500 错误堆栈后会开始"幻觉"，吞掉异常，返回简洁的错误描述。

6. Token 成本要监控。Agent 每次循环都在烧钱，用 Micrometer 打点，Grafana 建面板。

7. 流式响应提升体验。用户等不了 Agent 执行 30 秒才给结果，用 SSE（Spring WebFlux）实时推送进度。

一句话总结：Java Agent 开发的路线就是——理解 ReAct 循环本质 → Spring AI 打通全流程 → MCP 接外部生态 → 生产化落地。框架会变，但 LLM + 规划 + 工具 + 记忆这四块拼图不变。