1. 为什么 Java 工程师转 AI Agent 有天然优势1.1 转型焦虑背后的真实机会窗口这两年身边不少 Java 同行都在聊转型的事有人焦虑有人已经悄悄动手了。我自己的判断是Java 工程师转 AI Agent 开发不是从零开始而是把已有的工程能力迁移到一个新场景里。这个判断不是安慰话是我实际做了几个 Agent 项目之后得出的结论。先看一个现实市面上大量 AI Agent 的教程和开源项目都是 Python 写的LangChain、AutoGPT、CrewAI 这些确实生态成熟。但真正要把 Agent 落到企业生产环境里光靠一个 Jupyter Notebook 跑通 Demo 是远远不够的。你需要考虑并发、事务、权限、监控、部署、和现有业务系统对接——这些恰恰是 Java 工程师干了多年的活。我见过太多团队用 Python 快速搭了个 Agent 原型结果一上生产就崩并发一高就内存泄漏和公司现有的 Spring Boot 微服务集群对接困难日志和链路追踪体系完全对不上。这时候 Java 生态的价值就出来了。LangChain4j 和 Spring AI 这两个框架本质上就是把 Python 生态里验证过的 Agent 模式用 Java 工程师熟悉的方式重新实现了一遍。所以这篇文章我想讲清楚三件事AI Agent 的核心原理到底是什么Java 生态里怎么落地以及从写 CRUD 到写 Agent 中间需要补哪些认知。适合有 Java 基础、想切入 AI Agent 方向但不知道从哪下手的工程师也适合已经在用 Python 做 Agent 但想了解 Java 方案差异的读者。1.2 Java 工程师已有的三项可迁移能力很多人一提到转 AI 就觉得自己数学不行、算法不懂其实这是把训练模型和使用模型混为一谈了。做 AI Agent 开发绝大多数人不需要训练模型你需要的是调用模型、编排流程、管理状态。这三件事 Java 工程师其实很擅长。第一项是依赖注入和面向接口编程。Agent 的核心是工具调用模型决定调用哪个工具、传什么参数然后框架去执行。这套机制本质上就是策略模式加反射调用。Spring 的 IoC 容器天生适合管理各种 Tool Bean你写一个Tool注解的方法框架自动注册、自动描述给模型这套思路 Java 工程师一看就懂。第二项是状态管理和并发控制。Agent 执行是多轮循环的每一轮都要维护对话历史、工具调用结果、中间状态。这跟你在 Web 应用里管理 Session、处理并发请求是同一类问题。热词里有人问ai agent 怎么扛并发这个问题对 Java 工程师来说反而是舒适区——线程池、异步编排、响应式编程这些你本来就在用。第三项是工程化思维。Python 脚本跑通和 Java 服务上线之间隔着一条鸿沟。配置管理、健康检查、优雅停机、灰度发布这些在 Agent 场景里同样需要。Spring AI 之所以能快速起来就是因为它把这些企业级能力直接带进了 AI 开发。1.3 需要补的三块认知短板当然优势归优势短板也得正视。我自己踩过的坑主要集中在三块。一是对 LLM 的能力边界要有直觉。模型不是万能的它会幻觉、会不按格式输出、会在长上下文里丢失信息。你得知道什么任务适合交给模型什么任务必须用代码兜底。比如数值计算、精确匹配这类千万别指望模型老老实实写代码。二是Prompt 工程和上下文管理。这是新东西Java 工程师以前不接触。System Prompt 怎么写、Few-shot 示例怎么给、上下文超长了怎么截断或摘要这些都需要实践积累。我一开始写的 Prompt 模型经常不听话后来才明白 Prompt 本质是给模型的需求文档你需求写得含糊它实现得就离谱。三是对 Token 成本和延迟的敏感度。传统 Java 服务你关心 QPS 和 RTAgent 场景里你还得关心 Token 消耗。一次 Agent 调用可能触发十几轮模型交互成本是普通接口的几十倍。这个账要会算不然上线后账单会让你怀疑人生。2. AI Agent 的核心原理拆解2.1 Agent 和普通 LLM 调用的本质区别先把这个概念理清楚不然后面全是糊涂账。普通 LLM 调用是一问一答你给一段 Prompt模型返回一段文本结束。Agent 不一样Agent 是给一个目标模型自己决定怎么一步步完成。举个具体例子。你问普通 LLM北京今天天气怎么样它要么不知道要么瞎编。但如果你给它一个天气查询工具Agent 会这样工作先分析你的意图是查天气然后决定调用天气工具传入北京这个参数拿到工具返回的真实数据最后组织成自然语言回答你。整个过程模型自主决策这就是 Agent。核心区别在于循环和工具。普通调用是一次性的Agent 是一个循环思考、行动、观察、再思考直到任务完成。这个循环模式有个专门的名字叫 ReAct也就是 Reasoning Acting。热词里出现的 ReAct 就是这个东西它是目前主流 Agent 架构的基础范式。ReAct 的工作流程可以拆成四步。第一步是 Thought模型根据当前状态思考下一步该干什么。第二步是 Action模型决定调用哪个工具、传什么参数。第三步是 Observation框架执行工具并把结果返回给模型。第四步是判断如果任务完成就输出最终答案没完成就回到第一步继续循环。这个循环最多跑多少轮需要你设置一个上限防止死循环烧钱。2.2 ReAct 循环的工程化实现要点理解了原理落地时还有几个关键点要注意。循环终止条件必须设。模型有时候会陷入我再查一下的循环尤其是工具返回结果不理想时。我一般设置最大迭代次数 10 到 15 轮超过就强制返回当前结果并记录告警。这个值不是拍脑袋定的是根据你的任务复杂度来的。简单问答 5 轮够了复杂的数据分析任务可能要 20 轮。工具描述的质量决定 Agent 的上限。模型靠工具的名称和描述来决定调不调用、怎么调用。你写个工具叫queryData描述是查询数据模型根本不知道什么时候该用它。正确的写法是queryUserOrderHistory描述写清楚根据用户 ID 查询该用户过去 90 天的订单记录返回订单号、金额、状态列表。描述越具体模型判断越准。中间状态的持久化。Agent 执行可能耗时几十秒甚至几分钟如果中途服务重启状态就丢了。生产环境里我会把每一轮的 Thought、Action、Observation 都存到数据库或 Redis支持断点续跑。这个设计思路跟工作流引擎是一样的热词里提到的 flowork、dify 工作流本质都是这个思路。2.3 从单 Agent 到多 Agent 协作单 Agent 能解决不少问题但复杂任务需要多个 Agent 分工。比如一个帮我分析这份财报并生成 PPT的任务可以拆成数据提取 Agent、分析 Agent、文案 Agent、排版 Agent。每个 Agent 专注一件事通过消息传递协作。多 Agent 架构目前主流有两种模式。一种是编排式有一个主 Agent 负责拆解任务、分发给子 Agent、汇总结果类似项目经理带团队。另一种是协作式Agent 之间平等对话通过共享黑板或消息队列交换信息。前者可控性强适合生产环境后者灵活但容易失控适合探索性任务。Java 生态里实现多 Agent我倾向于用编排式因为 Java 工程师对流程编排本来就很熟。你可以把主 Agent 看成一个状态机每个子 Agent 是一个状态节点用 Spring StateMachine 或者自己写个简单的调度器都能实现。关键是每个子 Agent 的输入输出要定义清楚接口化这样才能独立测试和替换。3. Java 生态的 Agent 框架选型3.1 LangChain4j 和 Spring AI 的定位差异Java 里做 Agent绕不开这两个框架。我用下来的感受是LangChain4j 更像一个工具箱Spring AI 更像一个框架。LangChain4j 的设计哲学是贴近 Python 的 LangChain提供了大量细粒度的组件ChatLanguageModel、EmbeddingStore、DocumentSplitter、ToolSpecification 等等。你想怎么拼就怎么拼灵活度高。适合需要深度定制、对底层细节有掌控需求的场景。它的 Agent 实现也比较直接AiServices配合Tool注解就能快速搭起来。Spring AI 则是把 AI 能力当成 Spring 生态的一等公民。它的核心抽象是ChatClient用起来跟RestClient、WebClient一个风格链式调用很 Spring。优势在于和 Spring Boot 的自动配置、依赖注入、可观测性无缝集成。你现有的 Spring Boot 项目想加个 AI 功能引入 Spring AI 的 starter 就能用几乎零改造。选型建议很直接新项目、纯 AI 应用用 LangChain4j 更灵活已有 Spring Boot 体系、要把 AI 嵌进现有业务用 Spring AI 更顺。当然两者也能混用LangChain4j 的很多组件 Spring AI 也能对接。3.2 版本选择和依赖管理版本这块要特别注意AI 框架迭代极快API 变动频繁。我踩过的坑是照着半年前的教程写代码结果依赖一升级全编译不过。LangChain4j 目前稳定版本在 0.35 左右核心依赖是langchain4j和langchain4j-open-ai或者对应你用的模型厂商的模块。如果你要用 Agent 和工具调用还需要langchain4j-core里的相关类。建议用 BOM 统一管理版本避免各模块版本不一致。Spring AI 的版本要注意1.0 之前 API 变动很大现在 1.0.x 已经相对稳定。热词里提到的 spring ai 2.0 是较新的版本线引入了更多 Agent 相关的能力。如果你要用 Spring AI Alibaba 对接国内模型注意它的版本要和 Spring AI 主版本匹配不然会有兼容问题。热词里有人问spring ai alibaba 停更了吗据我观察它还在维护只是节奏比主框架慢一些选型时建议锁定一个稳定版本别追最新。依赖管理上我强烈建议用 Maven 或 Gradle 的 dependencyManagement 锁死版本并且把模型厂商的 SDK 版本也一起锁。因为模型 API 也在变SDK 版本不匹配会出现各种奇怪的序列化错误。3.3 模型接入的几种方式Java 接入模型有几种路径各有取舍。直连官方 API是最简单的方式LangChain4j 和 Spring AI 都提供了 OpenAI 兼容的客户端。国内模型如通义千问、文心一言、智谱等大多提供 OpenAI 兼容接口配置 base_url 和 api_key 就能用。热词里spring ai 2.0 连接百炼 qwen说的就是这个场景百炼平台提供 OpenAI 兼容端点Spring AI 直接配就行。通过云厂商 SDK接入比如阿里云百炼、火山引擎等都有自己的 Java SDK。这种方式能用到厂商特有的能力但会绑定厂商迁移成本高。本地部署模型通过 Ollama 或类似工具暴露 OpenAI 兼容接口Java 端无感知。适合对数据隐私要求高、或者想省 Token 成本的场景。但本地模型能力通常弱于云端大模型复杂 Agent 任务可能跑不动。我的建议是开发阶段用云端 API 快速验证生产环境根据成本和合规要求决定。如果要做多模型路由可以在 Java 层封装一个统一的ModelRouter根据任务类型、成本预算、可用性动态选择模型。这个抽象层很有必要能让你在模型涨价或降级时快速切换。4. 从零搭建一个 Java Agent 的完整实操4.1 项目骨架和依赖配置光说不练假把式我带你搭一个能跑的 Agent。目标做一个智能运维助手能查询服务器状态、重启服务、查看日志。这个场景足够典型涉及多个工具调用和多轮决策。先建一个 Spring Boot 项目Java 17 起步Spring AI 要求 17。核心依赖如下dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version1.0.0/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency如果你用 LangChain4j依赖换成dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version0.35.0/version /dependency dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.35.0/version /dependency配置文件里配好模型端点spring: ai: openai: api-key: ${API_KEY} base-url: https://dashscope.aliyuncs.com/compatible-mode chat: options: model: qwen-plus temperature: 0.1temperature 设低一点Agent 场景需要稳定输出不需要创意。0.1 到 0.3 之间比较合适。4.2 工具类的定义和注册工具是 Agent 的手脚。在 Spring AI 里用Tool注解标记方法即可Component public class OpsTools { Tool(description 查询指定服务器的CPU、内存、磁盘使用率参数为服务器IP) public ServerStatus queryServerStatus(String ip) { // 实际调用监控系统API return monitorClient.getStatus(ip); } Tool(description 重启指定服务器上的指定服务参数为服务器IP和服务名) public String restartService(String ip, String serviceName) { // 实际调用运维平台API return opsClient.restart(ip, serviceName); } Tool(description 查询指定服务器最近N条日志参数为服务器IP、服务名、条数) public ListString queryLogs(String ip, String serviceName, int lines) { return logClient.tail(ip, serviceName, lines); } }这里有个关键细节工具方法的参数类型要简单。String、int、boolean 这类基本类型模型处理得最好。如果你传一个复杂的嵌套对象模型很可能构造不出来。如果确实需要复杂参数拆成多个简单参数或者在工具内部做转换。工具注册到 ChatClientBean public ChatClient chatClient(ChatClient.Builder builder, OpsTools opsTools) { return builder .defaultSystem(你是一个运维助手帮助用户诊断和解决服务器问题。 遇到需要实际操作时调用相应工具。操作前先确认参数。) .defaultTools(opsTools) .build(); }System Prompt 里我特意加了操作前先确认参数因为重启服务这种危险操作模型如果参数传错后果很严重。这个约束能显著降低误操作概率。4.3 Agent 执行流程和状态管理调用 Agent 的代码很简洁RestController public class AgentController { private final ChatClient chatClient; PostMapping(/agent/chat) public String chat(RequestBody ChatRequest request) { return chatClient.prompt() .user(request.getMessage()) .call() .content(); } }但生产环境不能这么简单。你需要加会话管理、超时控制、循环上限、日志记录。我一般会封装一个AgentExecutorpublic class AgentExecutor { private static final int MAX_ITERATIONS 15; private static final Duration TIMEOUT Duration.ofSeconds(60); public AgentResult execute(String sessionId, String userInput) { AgentContext context contextStore.load(sessionId); context.appendUserMessage(userInput); for (int i 0; i MAX_ITERATIONS; i) { if (context.isTimeout(TIMEOUT)) { return AgentResult.timeout(context.getPartialResult()); } ChatResponse response chatClient.prompt() .messages(context.getMessages()) .call() .chatResponse(); context.appendAssistantMessage(response); if (response.hasToolCalls()) { ListToolResult results toolExecutor.execute(response.getToolCalls()); context.appendToolResults(results); continue; } return AgentResult.success(response.getContent()); } return AgentResult.maxIterationsReached(context.getPartialResult()); } }这段代码的核心是循环加状态累积。每一轮把模型输出和工具结果都追加到上下文里下一轮模型能看到完整历史。MAX_ITERATIONS和TIMEOUT是两道保险防止失控。4.4 上下文管理和 Token 控制上下文会随着循环不断增长很快就能撑爆模型的上下文窗口。必须做管理。我的策略是分层保留System Prompt 永远保留最近 5 轮完整保留更早的轮次做摘要压缩。摘要用一个便宜的小模型来做把多轮对话压缩成一段话。这样既保留了关键信息又控制了 Token 量。public ListMessage compressContext(ListMessage history) { if (tokenCount(history) MAX_CONTEXT_TOKENS * 0.7) { return history; } ListMessage recent history.subList(history.size() - 10, history.size()); ListMessage old history.subList(0, history.size() - 10); String summary summaryModel.summarize(old); return List.of(new SystemMessage(历史摘要 summary), ...recent); }阈值设 70% 是留缓冲因为工具返回结果可能很长一次就撑爆。这个比例可以根据你的模型上下文窗口调整128K 窗口的模型可以放宽到 80%。5. 生产环境必须解决的五个工程问题5.1 并发场景下的 Agent 隔离热词里ai agent 怎么扛并发这个问题问到了痛点。Agent 是有状态的多个请求共享一个 Agent 实例会串数据。解决方案是每个会话一个独立的上下文对象Agent 执行器本身无状态。具体做法用ConcurrentHashMap或者 Redis 存会话上下文key 是 sessionId。每次请求根据 sessionId 取出上下文执行完再写回。执行器本身是单例的线程安全。但还有个坑模型 API 调用是阻塞的高并发下线程池会被打满。我一般用异步方式调用配合CompletableFuture和自定义线程池。线程池大小根据模型 API 的 QPS 限制来定别设太大不然会被限流。private final ExecutorService agentPool new ThreadPoolExecutor( 10, 50, 60L, TimeUnit.SECONDS, new LinkedBlockingQueue(200), new ThreadPoolExecutor.CallerRunsPolicy() );队列满了用 CallerRunsPolicy 让调用线程自己执行起到背压作用。这比直接拒绝请求体验好。5.2 工具调用的安全边界Agent 能调用工具就意味着它能产生真实副作用。重启服务、删除数据、发送消息这些操作一旦被模型误触发后果严重。我的做法是分级授权。只读工具查询状态、看日志直接放行写操作工具重启、删除需要二次确认。确认机制可以是在工具方法里检查一个confirmed标志或者把写操作设计成先返回一个待确认的操作 ID用户确认后再执行。另外工具参数要做校验。模型可能传入不存在的服务器 IP、非法的服务名。工具方法内部必须做参数合法性检查不能信任模型传进来的任何东西。这一点跟 Web 开发里不能信任前端参数是一个道理。5.3 可观测性建设Agent 执行是个黑盒出了问题很难排查。必须把每一轮的输入输出都记录下来。我一般记录这几个维度sessionId、轮次、模型输入 Token 数、模型输出 Token 数、工具调用名称和参数、工具执行耗时、最终结果。这些数据打到日志系统同时上报到监控平台。关键指标包括平均轮次、工具调用成功率、超时率、Token 消耗趋势。有了这些数据你才能回答为什么这个请求花了 30 秒、为什么这个月成本涨了一倍这类问题。没有可观测性的 Agent 系统上线就是灾难。5.4 降级和熔断策略模型 API 会挂会限流会超时。你的 Agent 系统不能因为模型不可用就整个瘫痪。降级策略分几层。第一层是重试网络抖动导致的失败重试 2 到 3 次指数退避。第二层是模型切换主模型不可用时切到备用模型比如从 qwen-max 切到 qwen-plus。第三层是功能降级Agent 不可用时退化成普通的问答或者返回预设话术。熔断用 Resilience4j 或者 Sentinel 都行配置好失败率阈值和熔断时长。我一般设失败率超过 50% 且请求数超过 20 就熔断熔断 30 秒后半开试探。5.5 成本控制的实际手段Token 成本是 Agent 落地的隐形杀手。我算过一笔账一个中等复杂度的 Agent 任务平均 8 轮循环每轮输入 2000 Token、输出 500 Token一次任务就是 2 万 Token。按 qwen-plus 的价格一天一万次调用就是几十块钱一个月上千。如果用的是更贵的模型成本翻几倍。控制手段有几个。Prompt 精简System Prompt 别写太长工具描述够用就行。上下文压缩前面讲过的摘要策略。模型分级简单任务用小模型复杂任务才用大模型。缓存相同或相似的查询结果缓存起来避免重复调用。设置预算上限每个用户或每个会话设 Token 配额超了就拒绝。这些手段组合起来成本能降 60% 以上。别小看这些优化规模化之后省下的都是真金白银。6. 常见问题排查实录6.1 模型不调用工具怎么办这是新手最常遇到的问题。你定义好了工具模型却直接编答案不调用。原因通常有三个。一是工具描述不够清晰模型不知道什么时候该用。解决方法是把描述写具体包含使用场景。二是System Prompt 没引导加一句需要实时数据时必须调用工具不要凭记忆回答。三是模型能力不够小模型对工具调用的支持差换个强一点的模型试试。还有个隐蔽原因工具参数类型不匹配。模型想调用但构造不出参数就放弃了。检查一下参数类型是不是都是基本类型复杂类型拆简单。6.2 循环不终止怎么破模型陷入我再查一下的循环反复调用同一个工具。这通常是因为工具返回的结果没有满足模型的预期它以为没查到就再查一遍。解决方法是在工具返回结果里加明确的状态标识。比如查询成功返回{status: success, data: [...]}查询无结果返回{status: empty, message: 未找到符合条件的记录}。模型看到 empty 就知道不用再查了。另外在 System Prompt 里加约束同一个工具用相同参数最多调用一次如果结果不理想尝试其他方法或直接告知用户。 配合最大迭代次数限制双保险。6.3 工具执行超时怎么处理工具调用外部系统可能超时。如果不处理整个 Agent 就卡住了。每个工具方法都要设超时。用CompletableFuture配合orTimeout或者用 Resilience4j 的 TimeLimiter。超时后返回一个明确的错误信息给模型让它决定是重试还是换方案。Tool(description ...) public String queryServerStatus(String ip) { try { return CompletableFuture.supplyAsync(() - monitorClient.getStatus(ip)) .orTimeout(5, TimeUnit.SECONDS) .join(); } catch (Exception e) { return 查询超时请稍后重试或检查服务器 ip 是否可达; } }返回的错误信息要能让模型理解并做出决策别返回一堆堆栈信息。6.4 常见问题速查表问题现象可能原因排查方向解决方案模型不调用工具描述不清/未引导/模型弱检查工具描述和 System Prompt细化描述加引导语换强模型循环不终止结果不明确/无约束看工具返回格式加状态标识设最大轮次工具超时卡死无超时控制检查工具方法加超时和异常兜底上下文超限历史累积过多看 Token 计数摘要压缩分层保留并发串数据上下文共享检查会话隔离每会话独立上下文成本飙升轮次多/模型贵看 Token 消耗统计分级模型加缓存设配额输出格式错乱Prompt 不明确检查输出要求给 Few-shot 示例加格式约束这张表是我实际排查问题的经验总结遇到问题先对照着看能省不少时间。6.5 几个容易忽视的细节最后分享几个我踩过的坑。模型返回的 JSON 可能带 markdown 代码块标记。你要求它返回 JSON它给你返回json {...} 。解析前先去掉这些标记或者用宽容的解析器。工具方法的异常要捕获。工具内部抛异常框架可能直接把异常抛给模型模型看到一堆堆栈会懵。统一在工具层捕获转成自然语言的错误描述。会话清理要有策略。会话上下文不能无限增长设个过期时间比如 30 分钟不活跃就清理。不然内存会被慢慢吃光。测试要用真实模型。Mock 模型测不出 Prompt 的问题因为 Mock 不会真的理解你的指令。关键流程一定要用真实模型跑通。版本升级要谨慎。AI 框架 API 变动频繁升级前先在测试环境验证别直接上生产。我有次升级 LangChain4j 小版本工具调用的行为就变了排查了半天。这些细节看起来琐碎但生产环境出问题往往就是这些地方。Agent 开发跟传统开发最大的不同就是引入了模型这个不确定的组件你必须用工程手段把不确定性圈起来让系统整体可控。这也是 Java 工程师的强项——我们习惯了处理各种不确定性把它变成稳定的服务。