1. 为什么 Java 工程师转 AI Agent 有天然优势这两年身边不少写 Java 的朋友都在焦虑同一件事AI Agent 这么火自己是不是要被时代甩下了。我的判断恰恰相反——Java 工程师转 AI Agent起点比很多纯算法背景的人还要高。原因很实在Agent 这东西本质上不是模型有多聪明而是工程能不能扛住。一个能上生产的 Agent背后是并发调度、状态管理、超时重试、可观测性、权限隔离这一整套后端功夫而这些恰恰是 Java 工程师天天在干的事。先把概念对齐一下。所谓AI Agent你可以理解成一个会自己决定下一步做什么的程序。传统程序是你写死 if-elseAgent 是你给它一个目标它自己拆解、自己调工具、自己看结果、自己决定要不要再来一轮。这个自己决定的循环业界最经典的范式就是ReActReasoning Acting也就是思考—行动—观察三步循环。而LangChain4j和Spring AI这两个库就是把这套循环用 Java 的方式封装好让你不用去写 Python 也能搭 Agent。那 Java 工程师的优势在哪我列几个最直接的并发与线程池Agent 一次请求可能要调好几次大模型、好几次工具天然是 IO 密集型。Java 的线程池、CompletableFuture、虚拟线程JDK 21玩得溜扛并发就是基本功。生态成熟Spring Boot 的依赖注入、AOP、事务、配置管理直接套到 Agent 的编排上比 Python 那边手搓要稳得多。类型安全Java 是静态类型语言Agent 的工具入参出参用 POJO 定义编译期就能挡掉一堆低级错误这在多工具编排时特别香。可观测性Micrometer、Actuator、链路追踪Java 这套监控体系是现成的Agent 上线后你能看到每一步耗时、token 消耗、失败率。所以这篇不是给你灌鸡汤而是把从原理到落地这条路径讲透。适合谁看有 Java 基础、想切入 AI Agent 的后端工程师也适合已经在用 LangChain4j 或 Spring AI、但卡在能跑 demo 上不了生产这一步的人。下面我按设计思路—核心细节—实操落地—问题排查四块展开中间会穿插我自己踩过的坑。2. 整体设计思路Java 做 Agent 到底该怎么选型2.1 LangChain4j 和 Spring AI 到底选哪个这是被问得最多的问题。我的结论是看你的项目底色。如果你本来就是 Spring Boot 全家桶团队对 Spring 那套注解、自动配置很熟那 Spring AI 上手最快它跟 Spring 生态是无缝的Tool注解、ChatClient这些设计非常Spring 味。如果你要的是更灵活的 Agent 编排、更丰富的记忆Memory和检索RAG组件LangChain4j 的抽象层次更细可玩性更高。我做过一个对比直接上表维度Spring AILangChain4j上手门槛低Spring 用户几乎零成本中需要理解它的抽象体系与 Spring 集成原生自动配置需要手动装配Agent 编排能力够用偏简洁更强链式组合灵活RAG 组件有但相对基础丰富多路召回等支持好工具调用Tool注解很优雅Tool 手动注册都行适合场景企业级业务系统嵌入 AI复杂 Agent、独立 AI 服务提示不要一上来就纠结选哪个。两个库的核心概念是通的——模型、提示词、工具、记忆、检索。先吃透一套另一套半天就能迁移。2.2 ReAct 循环在 Java 里怎么落地ReAct 听起来玄乎拆开就是一段循环逻辑。用大白话讲Reason把用户问题 可用工具列表 历史对话一起丢给大模型让它输出我打算调用哪个工具、参数是什么。ActJava 这边解析出工具名和参数反射调用对应的方法。Observe把工具返回的结果再塞回上下文进入下一轮 Reason。终止当模型输出最终答案而不是工具调用时循环结束。关键点在于谁来控制这个循环。有两种做法一种是让模型自己决定模型输出结构化的工具调用指令另一种是你在 Java 侧写死循环次数上限。生产环境我强烈建议两者结合——既让模型自主决策又在 Java 侧加最大轮次比如 5 轮和超时兜底。为什么因为模型偶尔会陷入反复调同一个工具的死循环你不加护栏它能把你的 token 烧光。2.3 为什么必须做工具Tool的边界设计Agent 的能力边界完全由你给它哪些工具决定。我见过太多人一上来就给 Agent 挂十几个工具结果模型选择困难准确率暴跌。我的经验是单个 Agent 的工具数量控制在 5 到 8 个超过就拆分。而且每个工具的描述description要写得像给新人看的接口文档——说清楚什么时候用、参数什么含义、返回什么。模型选工具靠的就是这段描述你写得含糊它就选错。另外工具方法本身要做幂等和权限校验。比如一个删除订单的工具你不能让模型随便调得在 Java 侧校验当前用户有没有权限、这个订单是不是能删。模型是不可信的所有安全边界必须在 Java 代码里守住。3. 核心细节解析模型、提示词、工具、记忆四件套3.1 模型接入与参数调优不管用哪个库第一步都是接模型。以 Spring AI 为例配置大概长这样spring: ai: openai: api-key: ${API_KEY} base-url: ${BASE_URL} chat: options: model: qwen-plus temperature: 0.3 max-tokens: 2048这里有几个参数必须讲清楚因为它们直接决定 Agent 的表现temperature控制随机性。Agent 场景我一般设 0.1 到 0.3因为工具调用需要稳定不能今天调 A 明天调 B。创意写作才需要调高。max-tokens单次输出上限。设太小模型思考到一半被截断工具调用参数就不完整设太大浪费钱。一般 2048 够用。top-p和 temperature 二选一调别同时大改否则行为不可预测。注意不同模型的工具调用能力差异很大。有些模型对 function calling 支持不好会输出一堆自然语言而不是结构化指令。选模型时一定要先测它的工具调用稳定性别等上线才发现。3.2 提示词工程System Prompt 是 Agent 的灵魂System Prompt 决定了 Agent 的人设和行为规范。我写 Agent 的 System Prompt 一般包含四块角色定义你是谁负责什么。能力说明你能调用哪些工具分别在什么场景用。行为约束不能做什么比如不确定时不要编造直接说不知道。输出格式要求它按什么格式回复。举个我实际用的模板你是一个订单查询助手。你可以调用以下工具 - queryOrder(orderId): 根据订单号查询订单详情 - queryLogistics(orderId): 查询订单物流信息 规则 1. 用户问订单状态时先调 queryOrder。 2. 用户问物流时先调 queryOrder 确认订单存在再调 queryLogistics。 3. 如果工具返回为空如实告知用户不要编造。 4. 每次只调用一个工具等结果返回后再决定下一步。这段看着简单但每一条都是踩坑换来的。比如第 4 条每次只调一个工具是因为早期我让它一次调多个结果参数串了排查半天。3.3 工具定义从 Java 方法到模型可调用的函数在 LangChain4j 里定义一个工具非常直观public class OrderTools { Tool(根据订单号查询订单详情返回订单状态、金额、下单时间) public Order queryOrder(P(订单号格式为纯数字) String orderId) { return orderService.getById(orderId); } Tool(根据订单号查询物流轨迹) public ListLogistics queryLogistics(P(订单号) String orderId) { return logisticsService.queryByOrderId(orderId); } }Tool里的描述就是给模型看的P是参数说明。这里有个细节返回对象要能被序列化成 JSON而且字段名要清晰。模型是读 JSON 来理解结果的你返回一个字段叫st的对象它根本不知道是啥。我一般会专门定义对外的 DTO字段名用orderStatus、amount这种自解释的。3.4 记忆管理短期记忆和长期记忆分开处理Agent 的记忆分两种。短期记忆是当前对话的上下文直接拼在 prompt 里就行但要注意 token 上限太长要做滑动窗口截断。长期记忆是跨会话的比如用户的历史偏好这个得存数据库用的时候检索出来。我的做法是短期记忆用MessageWindowChatMemory保留最近 N 轮长期记忆用向量库存需要时做相似度检索。别把两者混在一起否则 prompt 会爆炸。4. 实操落地从零搭一个能用的 Agent4.1 环境准备与依赖引入先明确版本。JDK 建议 17 或 2121 有虚拟线程对 IO 密集的 Agent 很友好。Maven 依赖以 LangChain4j 为例dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.35.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version0.35.0/version /dependencySpring AI 的话用它的 starterdependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId /dependency提示版本一定要对齐。LangChain4j 的各个模块版本号要一致Spring AI 要注意它和 Spring Boot 版本的兼容矩阵别乱升。4.2 组装一个带工具的 AgentLangChain4j 的组装代码ChatLanguageModel model OpenAiChatModel.builder() .apiKey(System.getenv(API_KEY)) .baseUrl(System.getenv(BASE_URL)) .modelName(qwen-plus) .temperature(0.2) .build(); OrderTools tools new OrderTools(orderService, logisticsService); Assistant assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .tools(tools) .chatMemory(MessageWindowChatMemory.withMaxMessages(20)) .build(); String answer assistant.chat(帮我查一下订单 12345 的物流);AiServices是 LangChain4j 的核心它帮你把模型、工具、记忆组装成一个可以直接调用的接口。Assistant是你自己定义的接口方法签名就是对话入口。4.3 并发场景怎么扛这是 Java 工程师最该发挥的地方。Agent 一次请求内部要串行调好几次模型和工具单请求延迟可能好几秒。要扛并发几个手段线程池隔离给 Agent 调用单独一个线程池别和主业务抢资源。核心线程数按QPS × 平均耗时估算比如 QPS 50、平均 3 秒那至少 150 个并发线程。虚拟线程JDK 21 的虚拟线程特别适合这种 IO 密集场景Executors.newVirtualThreadPerTaskExecutor()一行搞定不用再纠结线程池大小。超时与熔断模型调用必须设超时比如 30 秒配合 Resilience4j 做熔断防止模型服务抖动拖垮整个系统。限流模型 API 一般有 QPS 限制用令牌桶在入口限流超出的请求快速失败而不是排队。我实测下来用虚拟线程 超时兜底单机扛几百并发问题不大瓶颈通常在模型服务那边。4.4 可观测性上线前必须补的一课Agent 最怕的是黑盒——用户说答错了你完全不知道它中间调了什么工具、模型返回了什么。所以必须埋点每次模型调用的输入 prompt、输出、耗时、token 数都记日志。每次工具调用的入参、出参、耗时记日志。用 Micrometer 打指标接入 Prometheus Grafana 看板。我一般会定义一个AgentTrace对象把一轮对话的所有步骤串起来用 traceId 关联。出问题时一查就知道是哪一步崩的。5. 常见问题与排查技巧实录5.1 模型不调工具直接瞎编答案这是最高频的问题。原因通常有三个一是工具描述写得太烂模型不知道啥时候用二是 System Prompt 没强调必须先调工具三是模型本身工具调用能力弱。排查顺序先看日志里模型到底输出了什么如果它压根没输出工具调用指令那就是 prompt 或模型的问题。解决办法是把工具描述改具体System Prompt 里加禁止凭记忆回答必须调用工具核实。5.2 工具调用参数解析失败模型输出的参数格式不对比如该传数字传了字符串或者 JSON 少了个引号。这个在弱模型上很常见。我的做法是参数尽量用 String 接收在 Java 侧做转换和校验别指望模型输出完美类型。另外可以在工具描述里明确参数格式比如订单号必须是 8 位纯数字。5.3 Agent 陷入死循环模型反复调同一个工具或者两个工具来回调。护栏必须加最大轮次限制我一般设 5超过就强制返回抱歉我暂时无法完成。同时可以在 prompt 里加如果同一个工具连续调用两次结果相同请停止并告知用户。5.4 并发下上下文串了这个坑很隐蔽。如果你把 ChatMemory 定义成单例共享多个用户并发时上下文会互相污染。正确做法是每个会话一个 Memory 实例用 sessionId 做 key 管理。Spring AI 里可以用ChatMemory配合会话存储LangChain4j 里自己维护一个MapString, ChatMemory。5.5 常见问题速查表现象可能原因排查方向解决手段不调工具瞎编描述差/模型弱看模型原始输出改描述、加约束、换模型参数解析失败模型输出格式乱看工具调用日志用 String 接收校验死循环无轮次限制看调用轮次加最大轮次护栏上下文串了Memory 共享看 sessionId按会话隔离 Memory响应慢串行调用多看各步耗时虚拟线程超时缓存token 超限上下文太长看 prompt 长度滑动窗口截断提示排查 Agent 问题第一件事永远是打开日志看模型原始输入输出。90% 的问题看一眼日志就清楚了别瞎猜。6. 我踩过的几个坑和一点个人体会说几个文档里不会写、但实际会遇到的坑。第一个是工具返回数据太大。有次我让工具返回一个订单的完整对象里面嵌套了几十个字段结果模型被淹没直接忽略了关键信息。后来我改成只返回必要字段问题就没了。工具返回要精不要全。第二个是模型对中文工具描述的理解。实测下来工具描述用中文写对国产模型效果更好但如果用国外模型英文描述反而更准。这个要按你用的模型来调别一刀切。第三个是别迷信框架。LangChain4j 和 Spring AI 都在快速迭代API 经常变遇到问题先看官方文档和 GitHub issue别在网上抄过时的代码。我因为抄了个旧版本 APIdebug 了一下午。最后分享一个我自己的判断Java 工程师转 AI Agent真正的门槛不在模型原理而在工程化。模型能力是别人的但怎么把它稳稳地接进你的系统、扛住并发、看得见摸得着这是你的价值。把 ReAct 循环理解透把工具边界设计好把并发和可观测性做扎实你搭出来的 Agent 就能上生产而不是停在 demo。这条路我走过不难但要细心。