1. Java 工程师转型 AI Agent 的底层逻辑

1.1 为什么 Java 工程师适合切入 AI Agent

这两年身边不少写 Java 的朋友都在焦虑，看着 Python 生态里各种 AI 框架层出不穷，总觉得自己被时代甩下了。但实际情况恰恰相反，Java 工程师转型 AI Agent 有着天然的优势，只是很多人没意识到而已。

先说最核心的一点：AI Agent 的本质是工程问题，不是算法问题。大模型本身的能力由模型厂商负责迭代，而 Agent 要做的是把模型能力编排成可用的业务流程——这恰恰是 Java 工程师最擅长的事情。你写了五年的 Spring 依赖注入、事务管理、状态机、消息队列，这些经验在 Agent 开发里全部用得上，而且用得比 Python 工程师更顺手。

我见过太多 Python 写的 Agent Demo，跑起来很炫，一上生产就崩：并发一高就内存泄漏，任务一多就状态混乱，异常处理全靠 try-except 兜底。这些问题在 Java 世界里早就有了成熟的解决方案——线程池、响应式编程、状态机引擎、分布式锁。Agent 从 Demo 到生产之间的鸿沟，正是 Java 工程师的价值所在。

再具体一点，Java 生态里现在有两个主力框架：LangChain4j和Spring AI。前者对标 Python 的 LangChain，功能全面、迭代快；后者背靠 Spring 官方，和现有 Spring Boot 项目集成几乎零成本。如果你所在的公司已经在用 Spring Cloud 微服务架构，引入 Spring AI 就是加个依赖的事，不需要重构任何东西。

1.2 转型路上最容易踩的三个认知坑

第一个坑是把 Agent 当成聊天机器人。很多人以为接个大模型 API，加个对话循环就是 Agent 了。真正的 Agent 核心在于"自主决策"——它能根据目标拆解任务、选择工具、观察结果、调整策略。这个循环在学术上叫 ReAct（Reasoning + Acting），后面我会详细拆解。

第二个坑是过度迷信 Python 生态。Python 在模型训练和实验阶段确实强，但 Agent 落地阶段拼的是工程稳定性。我实测过一个场景：同样的工具调用逻辑，Python 版本在 200 QPS 下开始出现连接池耗尽，Java 版本用 WebClient 加连接池配置轻松扛住 800 QPS。这不是语言优劣，而是生态成熟度的差异。

第三个坑是忽视 Prompt 工程和上下文管理。Java 工程师习惯写确定性代码，但 Agent 的行为有很大一部分由 Prompt 决定。你需要学会用自然语言"编程"，同时用工程手段管理上下文窗口——什么时候截断、什么时候摘要、什么时候召回历史，这些都是实打实的工程决策。

1.3 一条务实的转型路线图

我给身边朋友的建议路线是这样的，按顺序来，不要跳步：

1. 第一周：跑通 Spring AI 或 LangChain4j 的 Hello World，理解 ChatClient、Prompt、Message 这几个核心抽象
2. 第二到三周：实现一个带工具调用的 Agent，比如让它能查数据库、调天气 API
3. 第四到五周：引入 ReAct 模式，让 Agent 能多步推理，处理需要组合工具的任务
4. 第六到八周：加上 RAG（检索增强生成），让 Agent 能基于私有知识库回答
5. 第九周起：做并发压测、可观测性、成本控制，把 Demo 变成能上线的服务

这个路线走下来大概两到三个月，前提是你每天能投入两小时以上。别指望一周速成，Agent 开发涉及的知识面比普通 CRUD 宽得多。

2. 核心框架选型：LangChain4j 与 Spring AI 怎么选

2.1 两个框架的定位差异

选框架这件事，我的经验是先看你的项目上下文，再看框架本身。脱离场景谈选型都是耍流氓。

Spring AI的定位很明确：让 Spring 开发者用最熟悉的方式接入 AI 能力。它的 API 设计完全遵循 Spring 的哲学——自动配置、依赖注入、声明式编程。你写一个@Bean配置 ChatClient，然后在 Service 里注入使用，和写 JdbcTemplate 的感觉一模一样。目前 Spring AI 已经迭代到 2.0.x 版本，对国内主流模型平台的支持也逐步完善，通过 OpenAI 兼容协议可以对接大部分国产大模型。

LangChain4j的定位是"Java 版的 LangChain"，功能覆盖面更广。它提供了 AiServices 这种声明式接口，你定义一个 Java 接口，加几个注解，框架自动帮你生成实现。它还内置了 RAG 的完整链路、多种记忆（Memory）实现、工具调用编排等高级能力。如果你要做复杂的 Agent 逻辑，LangChain4j 的抽象层次更合适。

我个人的判断标准是这样的：

2.2 依赖引入与基础配置实操

先说 Spring AI 的引入方式。以 Maven 为例，核心依赖是这样：

<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-openai-spring-boot-starter</artifactId> <version>1.0.0</version> </dependency>

然后在application.yml里配置模型接入信息：

spring: ai: openai: base-url: https://your-model-endpoint/v1 api-key: ${AI_API_KEY} chat: options: model: qwen-plus temperature: 0.7 max-tokens: 2048

这里有个细节要注意：api-key 一定要走环境变量，不要硬编码在配置文件里。我见过太多项目把密钥提交到 Git 仓库，这是安全事故。

LangChain4j 的引入稍微不同，它把不同能力拆成了独立模块：

<dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-open-ai</artifactId> <version>0.35.0</version> </dependency> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-spring-boot-starter</artifactId> <version>0.35.0</version> </dependency>

LangChain4j 的配置方式更灵活，你可以用编程式创建模型实例：

ChatLanguageModel model = OpenAiChatModel.builder() .baseUrl("https://your-model-endpoint/v1") .apiKey(System.getenv("AI_API_KEY")) .modelName("qwen-plus") .temperature(0.7) .timeout(Duration.ofSeconds(60)) .build();

提示：timeout这个参数千万别漏。大模型响应时间波动很大，默认超时往往不够用，我一般设 60 秒起步，复杂推理任务设到 120 秒。

2.3 声明式 AI 服务：LangChain4j 的杀手锏

LangChain4j 最让我惊艳的是 AiServices 机制。你只需要定义一个接口：

interface CustomerServiceAgent { @SystemMessage("你是一名电商客服助手，负责处理订单查询和退换货咨询") String chat(@MemoryId String sessionId, @UserMessage String message); }

然后一行代码生成实现：

CustomerServiceAgent agent = AiServices.builder(CustomerServiceAgent.class) .chatLanguageModel(model) .chatMemoryProvider(sessionId -> MessageWindowChatMemory.withMaxMessages(20)) .build();

框架自动帮你处理了 Prompt 组装、消息历史管理、响应解析。这种声明式风格对 Java 工程师极其友好，几乎不需要学习成本。@MemoryId注解配合chatMemoryProvider实现了多会话隔离，每个用户的对话历史独立存储，这在做多用户 Agent 服务时是刚需。

Spring AI 也有类似的抽象，叫ChatClient，用法上更偏向流式 API：

String response = chatClient.prompt() .system("你是一名电商客服助手") .user(message) .call() .content();

两者对比，LangChain4j 的接口式声明更适合复杂 Agent，Spring AI 的流式 API 更适合简单对话场景。选哪个取决于你的业务复杂度。

3. ReAct 模式：让 Agent 真正会"思考"

3.1 ReAct 的核心原理拆解

ReAct 这个词拆开就是 Reasoning + Acting，中文叫"推理与行动"。它的核心思想是让大模型在回答问题前，先输出思考过程，再决定调用什么工具，观察工具返回结果后继续思考，循环往复直到得出最终答案。

这个模式解决了一个关键问题：大模型的知识是静态的，但现实世界的任务是动态的。你问它"今天北京天气怎么样"，它训练数据里没有今天的天气，直接回答就是胡编。但如果你给它一个天气查询工具，它就能先思考"我需要查天气"，然后调用工具，拿到结果后再组织回答。

ReAct 的循环结构大致是这样的：

1. Thought（思考）：模型分析当前状态，决定下一步做什么
2. Action（行动）：选择一个工具并生成调用参数
3. Observation（观察）：执行工具，把结果返回给模型
4. 重复 1-3，直到模型认为可以给出最终答案
5. Final Answer（最终答案）：输出面向用户的回答

关键在于，这个循环不是硬编码的，而是通过 Prompt 引导模型自主决定何时停止。这就带来了灵活性，也带来了不确定性——模型可能陷入死循环，也可能选错工具。工程上需要加最大迭代次数、超时控制、工具白名单等约束。

3.2 用 LangChain4j 实现一个 ReAct Agent

LangChain4j 对工具调用有原生支持。先定义一个工具类：

public class WeatherTools { @Tool("查询指定城市的实时天气") public String getWeather(@P("城市名称") String city) { // 实际调用天气 API return weatherApi.query(city); } @Tool("查询指定城市的空气质量指数") public String getAirQuality(@P("城市名称") String city) { return aqiApi.query(city); } }

@Tool注解告诉框架这个方法可以被 Agent 调用，@P注解描述参数含义。然后把这个工具注册给 Agent：

interface WeatherAgent { @SystemMessage("你是一个天气助手，可以查询天气和空气质量。" + "如果用户问题需要多个信息，请依次调用工具获取。") String ask(@UserMessage String question); } WeatherAgent agent = AiServices.builder(WeatherAgent.class) .chatLanguageModel(model) .tools(new WeatherTools()) .build(); String answer = agent.ask("北京今天适合户外运动吗？");

当用户问"北京今天适合户外运动吗"，Agent 会自主判断需要先查天气、再查空气质量，然后综合两个结果给出建议。整个过程不需要你写任何 if-else 逻辑，全靠模型自主决策。

3.3 工具调用的参数设计与避坑

工具设计有几个坑我踩过，分享给你：

第一，工具描述要写清楚。模型是根据@Tool里的描述来决定用哪个工具的。如果你写"查询天气"，模型可能不知道是查实时还是预报。写成"查询指定城市的实时天气状况，包括温度、湿度、风力"，模型判断就准确多了。

第二，参数类型尽量简单。模型生成复杂嵌套 JSON 的准确率会下降。能用 String 就别用对象，能用基本类型就别用集合。如果确实需要复杂参数，考虑拆成多个工具。

第三，工具要有幂等性和超时保护。模型可能重复调用同一个工具，如果你的工具是"下单"这种非幂等操作，就会出大问题。我的做法是给所有写操作加幂等键，给所有外部调用加超时。

第四，控制工具数量。工具太多会让模型选择困难，实测超过 10 个工具后准确率明显下降。如果业务需要很多工具，考虑做工具分组，或者用路由层先做一次粗筛。

注意：ReAct 循环一定要设最大迭代次数，我一般设 5-8 次。不设的话，遇到模型钻牛角尖的情况，会一直循环烧 token，成本失控。

3.4 Spring AI 的工具调用实现

Spring AI 的工具调用走的是另一套 API，用@Tool注解配合FunctionCallback注册：

@Component public class OrderTools { @Tool(description = "根据订单号查询订单状态") public String queryOrder(@ToolParam(description = "订单号") String orderId) { return orderService.getStatus(orderId); } }

在调用时通过toolCallbacks传入：

String response = chatClient.prompt() .user("帮我查一下订单 12345 的状态") .toolCallbacks(ToolCallbacks.from(orderTools)) .call() .content();

Spring AI 的工具调用底层也是基于模型的 function calling 能力，原理和 LangChain4j 一致，只是 API 风格不同。选哪个看你项目里已经用了哪个框架。

4. RAG 实战：给 Agent 装上私有知识

4.1 RAG 解决什么问题

Agent 再聪明，也不知道你公司内部的业务规则、产品文档、历史工单。RAG（Retrieval-Augmented Generation，检索增强生成）就是解决这个问题的：把私有知识向量化存起来，用户提问时先检索相关内容，再连同问题一起喂给模型。

RAG 的核心链路是四步：文档加载 → 文本切分 → 向量化 → 检索召回。每一步都有讲究，做不好效果会大打折扣。

4.2 文档切分的参数选择

切分是最容易被忽视但影响最大的环节。切太大，检索精度低；切太小，语义不完整。我的经验参数是：

• 块大小（chunk size）：500-800 字符。中文场景下，500 字符大约是一到两段话，语义相对完整
• 重叠（overlap）：块大小的 10%-20%，防止关键信息被切断
• 切分策略：优先按段落、标题切，其次按句子，最后才按固定长度硬切

LangChain4j 提供了现成的切分器：

DocumentSplitter splitter = DocumentSplitters.recursive(600, 100); List<TextSegment> segments = splitter.split(document);

recursive策略会优先按段落切，段落太长再按句子切，最后才硬切。这个策略在大多数场景下效果都不错。

4.3 向量化与检索的工程细节

向量化就是把文本转成高维向量，语义相近的文本向量距离也近。LangChain4j 支持多种向量模型：

EmbeddingModel embeddingModel = OpenAiEmbeddingModel.builder() .baseUrl("https://your-endpoint/v1") .apiKey(System.getenv("AI_API_KEY")) .modelName("text-embedding-v3") .build(); EmbeddingStore<TextSegment> store = new InMemoryEmbeddingStore<>(); EmbeddingStoreIngestor ingestor = EmbeddingStoreIngestor.builder() .documentSplitter(splitter) .embeddingModel(embeddingModel) .embeddingStore(store) .build(); ingestor.ingest(document);

生产环境别用InMemoryEmbeddingStore，它重启就丢数据。常见选择是 Milvus、Qdrant、PgVector。如果团队已经在用 PostgreSQL，PgVector 是最省事的选择，不用额外维护一套向量数据库。

检索召回时，多路召回是个提升效果的关键技巧。简单说就是同时用向量检索和关键词检索，然后合并结果。向量检索擅长语义匹配，关键词检索擅长精确匹配，两者互补。LangChain4j 支持组合多个 Retriever：

Retriever<TextSegment> vectorRetriever = EmbeddingStoreContentRetriever.builder() .embeddingStore(store) .embeddingModel(embeddingModel) .maxResults(5) .minScore(0.7) .build();

minScore这个参数很重要，它过滤掉相似度太低的结果。不设的话，即使知识库里没有相关内容，也会硬召回几条不相关的，反而干扰模型判断。

4.4 RAG 效果调优的实战经验

RAG 做出来容易，做好难。我总结了几个调优方向：

召回不准：先检查切分是否合理，再看 embedding 模型是否适合中文。有些英文模型在中文上效果很差，换成中文优化的模型立竿见影。

答案不完整：可能是召回数量不够，把maxResults从 3 调到 5 或 8 试试。也可能是切分太碎，把 chunk size 调大。

答案有幻觉：在 Prompt 里明确要求"只根据提供的资料回答，资料中没有的信息就说不知道"。这句话能显著降低幻觉率。

响应太慢：向量检索本身很快，慢往往在 embedding 计算上。可以考虑缓存高频问题的 embedding，或者用更轻量的模型。

5. 并发与性能：Agent 上生产的必修课

5.1 Agent 服务的并发模型

Agent 服务和普通 CRUD 服务最大的区别是响应时间长且不稳定。一次 Agent 调用可能涉及多次模型请求和工具调用，耗时从几百毫秒到几十秒不等。如果用传统的 Tomcat 线程池模型，每个请求占一个线程，高并发下线程池很快耗尽。

我的建议是用响应式编程模型。Spring WebFlux 配合 WebClient 做非阻塞调用，少量线程就能支撑大量并发。Spring AI 和 LangChain4j 都提供了流式和响应式 API。

如果团队不熟悉响应式，退而求其次用虚拟线程（Java 21+）。虚拟线程的阻塞成本极低，可以像写同步代码一样写异步逻辑，是 Java 工程师的福音：

try (var executor = Executors.newVirtualThreadPerTaskExecutor()) { Future<String> future = executor.submit(() -> agent.ask(question)); String result = future.get(30, TimeUnit.SECONDS); }

5.2 连接池与超时配置

模型 API 调用本质是 HTTP 请求，连接池配置直接影响并发能力。以 WebClient 为例：

HttpClient httpClient = HttpClient.create() .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 5000) .responseTimeout(Duration.ofSeconds(60)) .doOnConnected(conn -> conn .addHandlerLast(new ReadTimeoutHandler(60)) .addHandlerLast(new WriteTimeoutHandler(60))); ConnectionProvider provider = ConnectionProvider.builder("ai-pool") .maxConnections(200) .pendingAcquireTimeout(Duration.ofSeconds(10)) .maxIdleTime(Duration.ofSeconds(30)) .build();

maxConnections要根据你的 QPS 和平均响应时间算。公式是：最大连接数 ≈ QPS × 平均响应时间（秒）。假设 100 QPS，平均响应 2 秒，那至少需要 200 个连接。留点余量，设 250 比较稳妥。

5.3 限流、降级与成本控制

Agent 服务有个特殊风险：成本失控。模型调用是按 token 计费的，一个死循环的 Agent 可能几分钟烧掉几十块钱。必须做几层防护：

第一层，请求限流。用 Resilience4j 或 Sentinel 对入口做限流，防止突发流量打爆。

第二层，单次调用预算。给每个 Agent 任务设最大 token 消耗和最大迭代次数，超了就强制终止。

第三层，降级策略。模型服务不可用时，降级到规则引擎或返回缓存结果，别让整个服务挂掉。

第四层，监控告警。记录每次调用的 token 消耗、响应时间、工具调用次数，设置异常告警阈值。

CircuitBreaker circuitBreaker = CircuitBreaker.ofDefaults("aiService"); Supplier<String> decorated = CircuitBreaker.decorateSupplier( circuitBreaker, () -> agent.ask(question));

5.4 可观测性建设

Agent 的行为是概率性的，出问题时很难复现。所以全链路日志是刚需。我一般记录这些信息：

• 请求 ID、用户 ID、会话 ID
• 完整的 Prompt（脱敏后）
• 模型的每次响应，包括思考过程和工具调用
• 每次工具调用的入参和返回
• 总耗时、token 消耗、迭代次数

这些数据存到 Elasticsearch 或 ClickHouse，配合 Grafana 做可视化。出问题时能快速定位是 Prompt 问题、工具问题还是模型问题。

6. 常见问题排查与避坑清单

6.1 高频问题速查表

6.2 几个容易忽视的细节

Prompt 版本管理。Prompt 是 Agent 的"代码"，改动会影响行为。建议把 Prompt 抽到配置文件或数据库，加版本号，方便回滚和 A/B 测试。

工具调用的幂等性。前面提过，这里再强调一次。模型可能因为超时重试而重复调用工具，所有写操作必须幂等。

上下文窗口管理。多轮对话历史会不断增长，最终超出模型上下文窗口。需要做截断或摘要。LangChain4j 的MessageWindowChatMemory就是按消息数量截断，简单有效。

敏感信息过滤。用户输入和工具返回都可能包含敏感信息，进模型前要脱敏，出模型后要审核。这是合规要求，也是安全底线。

模型版本锁定。模型厂商会不定期更新模型，行为可能变化。生产环境要锁定具体版本号，别用latest这种浮动标签。

6.3 我踩过的三个真实坑

坑一：以为工具越多越好。早期我给 Agent 注册了 20 多个工具，结果模型选择准确率惨不忍睹，经常调错工具。后来精简到 8 个核心工具，准确率立刻上来了。工具不在多，在于每个都清晰。

坑二：忽视 Prompt 的稳定性。同一个 Prompt，在不同模型、不同温度参数下表现差异很大。我做过测试，temperature 从 0.7 调到 0.3，工具调用的准确率提升了近 20 个百分点。生产环境建议用较低的温度，牺牲一点创造性换稳定性。

坑三：没做成本监控。有次上线一个新功能，Agent 逻辑有个边界情况会触发无限循环，一晚上烧掉了几百块。从那以后我所有 Agent 都强制加最大迭代次数和 token 预算，超了直接熔断。

7. 从 Demo 到生产的落地建议

7.1 分阶段推进策略

别想着一步到位做个全能 Agent。我的建议是分三个阶段：

阶段一：单点验证。选一个边界清晰、容错率高的场景，比如内部知识问答、日志分析助手。这个阶段目标是跑通链路，验证技术可行性。

阶段二：能力扩展。在验证过的场景上增加工具调用、多轮对话、RAG 等能力，同时补齐监控、限流、降级等工程设施。

阶段三：规模化。抽象出通用的 Agent 框架，支持多业务线快速接入。这个阶段要考虑多租户隔离、权限控制、成本分摊等问题。

7.2 团队协作与分工

Agent 项目不是一个人能搞定的。理想的团队配置是：

• Agent 工程师：负责 Prompt 设计、工具开发、流程编排
• 后端工程师：负责服务框架、并发、存储、监控
• 算法工程师：负责模型选型、效果评估、微调（如果需要）
• 产品经理：负责场景定义、效果验收、用户反馈闭环

小团队可以一人多岗，但效果评估这个角色不能缺。Agent 的效果很难用传统测试用例覆盖，需要有人持续做人工评估和 badcase 分析。

7.3 效果评估体系

Agent 的效果评估是个难题。我一般从四个维度看：

准确性：回答是否正确，工具调用是否合理。用人工标注的测试集评估。

完整性：是否覆盖了用户问题的所有方面。多轮对话场景尤其重要。

效率：平均响应时间、平均迭代次数、平均 token 消耗。

稳定性：相同问题多次调用结果的一致性。这个指标能反映 Prompt 的鲁棒性。

建议建一个持续评估的流水线，每次 Prompt 或工具改动后自动跑一遍测试集，对比指标变化。这比拍脑袋判断靠谱得多。

7.4 后续扩展方向

Agent 落地之后，还有不少可以深挖的方向：

多 Agent 协作：让多个专职 Agent 分工合作，比如一个负责检索、一个负责推理、一个负责审核。LangChain4j 和 Spring AI 都在往这个方向演进。

工作流编排：把 Agent 能力封装成可视化的工作流节点，让业务人员也能配置。市面上已经有一些低代码平台在做这件事，Java 侧可以基于 Spring AI 自建。

本地模型部署：对数据敏感的场景，可以考虑本地部署开源模型。Java 通过 Ollama 或类似方案也能接入，只是性能和效果需要权衡。

Agent 中台化：把 Agent 的通用能力（会话管理、工具注册、监控告警）抽象成中台服务，各业务线按需接入。这是大厂已经在走的路。

我个人在实际操作中的体会是，Java 工程师转型 AI Agent，最大的障碍不是技术，而是心态。别被 Python 生态的繁荣吓到，Agent 落地的核心是工程能力，而这恰恰是 Java 工程师的强项。把 Spring 那套依赖注入、AOP、事务、并发控制的经验迁移过来，你会发现 Agent 开发没那么神秘。真正需要补的是 Prompt 工程和效果评估的方法论，这两块多练多总结，两三个月就能上手。

最后分享一个小技巧：刚开始做 Agent 时，把每次模型交互的完整 Prompt 和响应都打印出来，人工看几十条，你对模型行为的直觉就建立起来了。这比看任何教程都管用。