Java开发者转型AI Agent开发：从Spring Boot到LangChain4j实战指南

最近在技术社区和招聘市场上AI Agent智能体的热度持续攀升很多有Java后端开发经验的同学都在关注如何向这个新兴领域转型。然而网上的资料要么过于零散不成体系要么偏向理论研究缺乏实战对于习惯了Spring Boot、微服务等成熟技术栈的Java开发者来说上手门槛不低。本文将为你系统梳理从Java开发者视角切入Agent开发的完整路径涵盖核心概念、主流框架、实战项目搭建以及避坑指南力求提供一份可落地、可复现的“转型地图”。1. Agent智能体开发从概念到价值在深入代码之前我们首先要厘清几个核心概念这对于理解后续的框架和开发至关重要。1.1 什么是AI Agent你可以将AI Agent理解为一个具备“感知-思考-行动”循环的智能程序。它不仅仅是调用一次大语言模型LLM的API而是能够根据目标自主规划步骤、使用工具如搜索、执行代码、操作数据库、评估结果并持续迭代的自治系统。一个经典的类比是大模型如GPT-4是一个知识渊博但被动的“大脑”你问它答。而Agent则是给这个“大脑”配上了“眼睛”感知环境、“手”执行工具和“记忆”存储历史使其能主动完成复杂任务比如自动分析数据并生成报告、根据用户需求订制旅行计划等。1.2 为什么Java开发者适合转型Agent开发工程化思维优势Java开发者擅长设计高可用、可扩展、易维护的系统架构。Agent系统本质上是一个复杂的分布式系统涉及任务调度、状态管理、工具集成、异步通信等这正是Java后端开发的强项。成熟的生态体系在Agent需要集成的“工具”层面Java拥有极其丰富的库和框架无论是数据库操作JDBC, JPA、网络通信HTTP Client、消息队列Kafka, RabbitMQ还是企业级集成都能找到成熟稳定的解决方案。性能与稳定性需求生产环境的Agent往往需要处理高并发、长周期任务对内存管理、垃圾回收、多线程有严格要求。Java在JVM层面的优化和监控工具链如JProfiler, VisualVM为此提供了坚实保障。市场需求明确随着企业级AI应用落地单纯的Prompt工程已无法满足复杂业务流程自动化需求。能够将AI能力“工程化”、“服务化”的Agent开发人才正成为稀缺资源。1.3 Agent的核心架构组件一个典型的Agent系统通常包含以下组件理解它们有助于我们选择框架规划器Planner将复杂目标拆解为可执行的子任务序列。工具ToolsAgent可以调用的外部能力如计算器、搜索引擎、API、数据库等。记忆Memory存储对话历史、任务状态、执行结果分为短期会话记忆和长期向量数据库记忆。执行引擎Execution Engine协调规划、工具调用和记忆更新的核心循环。评估器Evaluator对执行结果进行质量评估决定是否重试或调整计划。2. 环境准备与核心工具栈对于Java开发者我们不需要从零造轮子而是基于成熟的框架和云服务来构建。以下是推荐的环境和工具栈。2.1 基础开发环境JDK推荐 JDK 17 或 21LTS版本确保稳定的语言特性和性能。构建工具Maven 或 Gradle。本文示例使用 Maven。IDEIntelliJ IDEA首选或 Eclipse。版本控制Git。2.2 核心框架选择目前主流的Agent开发框架主要有两类Python系和Java/云原生系。对于Java开发者我们有更“原生”的选择LangChain4j这是Python版LangChain的Java移植是目前Java生态中最活跃的Agent框架。它提供了与Python版类似的高层抽象Chains, Agents, Tools并深度集成Spring Boot。Spring AI由Spring官方团队出品旨在为Spring生态提供一流的AI应用开发体验。它抽象了不同AI供应商的API并正在积极构建Agent等高级功能背靠Spring生态未来可期。云服务商SDK如阿里云灵积、百度千帆、腾讯云TI-ONE等提供的Agent构建平台SDK。优势是开箱即用、免运维但可能锁定特定云厂商。本文将以LangChain4jSpring Boot的组合作为主要实战框架因为它社区活跃、文档较全且设计理念与Java开发者熟悉的Spring风格接近。2.3 大模型API准备Agent的核心“大脑”需要一个大模型。你可以选择OpenAI GPT系列通过API调用需准备API Key。国内大模型如通义千问、文心一言、智谱GLM、月之暗面Kimi等通常有更友好的国内访问速度和成本。本地部署模型使用Ollama等工具本地运行Llama、Qwen等开源模型适合数据敏感场景。为简化示例我们将使用OpenAI兼容的API例如来自国内服务商提供的兼容接口或本地部署的兼容服务你需要准备相应的API Key和Base URL。3. 使用LangChain4j构建你的第一个Agent让我们从一个最简单的例子开始创建一个能使用计算器和网络搜索工具的Agent。3.1 创建Spring Boot项目使用 Spring Initializr 或IDE创建新项目。Project: MavenLanguage: JavaSpring Boot: 3.2.xDependencies:Spring Web,Lombok(可选简化代码)生成项目后在pom.xml中添加 LangChain4j 依赖。!-- pom.xml -- dependencies !-- Spring Boot 基础依赖 -- dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency !-- LangChain4j 核心依赖 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j/artifactId version0.31.0/version !-- 请检查最新版本 -- /dependency !-- LangChain4j 的 OpenAI 兼容模块 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-open-ai/artifactId version0.31.0/version /dependency !-- LangChain4j 与 Spring Boot 集成 -- dependency groupIddev.langchain4j/groupId artifactIdlangchain4j-spring-boot-starter/artifactId version0.31.0/version /dependency /dependencies3.2 配置大模型连接在application.yml或application.properties中配置你的大模型连接信息。# application.yml langchain4j: open-ai: chat-model: api-key: ${OPENAI_API_KEY:sk-your-key-here} # 建议使用环境变量 base-url: ${OPENAI_BASE_URL:https://api.openai.com/v1} # 如果使用兼容服务修改此处 temperature: 0.7 timeout: 60s3.3 定义自定义工具Tool工具是Agent能力的延伸。我们来定义一个简单的计算器工具和一个模拟的网络搜索工具。// 文件路径src/main/java/com/example/agent/tools/CalculatorTool.java package com.example.agent.tools; import dev.langchain4j.agent.tool.Tool; import org.springframework.stereotype.Component; Component public class CalculatorTool { Tool(用于计算两个数字的和。输入应为两个数字。) public double add(double a, double b) { return a b; } Tool(用于计算两个数字的差。输入应为两个数字。) public double subtract(double a, double b) { return a - b; } Tool(用于计算两个数字的乘积。输入应为两个数字。) public double multiply(double a, double b) { return a * b; } Tool(用于计算两个数字的商。输入应为两个数字除数不能为零。) public double divide(double a, double b) { if (b 0) { throw new IllegalArgumentException(除数不能为零); } return a / b; } }// 文件路径src/main/java/com/example/agent/tools/WebSearchTool.java package com.example.agent.tools; import dev.langchain4j.agent.tool.Tool; import org.springframework.stereotype.Component; import java.util.List; import java.util.ArrayList; Component public class WebSearchTool { Tool(在互联网上搜索给定查询词的信息。返回模拟的搜索结果摘要。) public String searchWeb(String query) { // 注意这是一个模拟工具。真实场景应集成SerperAPI、Google Search API等。 // 此处仅为演示Tool的集成方式。 System.out.printf([模拟搜索] 正在搜索: %s%n, query); // 模拟返回一些结果 return String.format(关于%s的搜索结果摘要这是一个模拟的搜索工具返回的信息。在实际项目中你需要替换为真实的搜索API调用。, query); } }关键点使用Tool注解来标注一个方法使其成为Agent可用的工具。注解中的描述非常重要LLM会根据描述来决定何时以及如何使用这个工具。3.4 装配并运行一个简单的Agent现在我们将这些工具装配到一个Agent中并通过一个REST API来与它交互。// 文件路径src/main/java/com/example/agent/service/SimpleAgentService.java package com.example.agent.service; import dev.langchain4j.agent.tool.ToolExecutionRequest; import dev.langchain4j.agent.tool.ToolSpecification; import dev.langchain4j.data.message.AiMessage; import dev.langchain4j.data.message.UserMessage; import dev.langchain4j.memory.ChatMemory; import dev.langchain4j.memory.chat.MessageWindowChatMemory; import dev.langchain4j.model.openai.OpenAiChatModel; import dev.langchain4j.model.output.Response; import dev.langchain4j.service.AiServices; import jakarta.annotation.PostConstruct; import lombok.extern.slf4j.Slf4j; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.beans.factory.annotation.Qualifier; import org.springframework.stereotype.Service; import com.example.agent.tools.CalculatorTool; import com.example.agent.tools.WebSearchTool; import java.util.List; Service Slf4j public class SimpleAgentService { Autowired private CalculatorTool calculatorTool; Autowired private WebSearchTool webSearchTool; // 定义Agent的接口 interface Assistant { String chat(String userMessage); } private Assistant assistant; PostConstruct public void init() { // 1. 创建聊天模型LLM OpenAiChatModel model OpenAiChatModel.builder() .baseUrl(System.getenv().getOrDefault(OPENAI_BASE_URL, https://api.openai.com/v1)) .apiKey(System.getenv().getOrDefault(OPENAI_API_KEY, demo)) .temperature(0.7) .timeout(java.time.Duration.ofSeconds(60)) .build(); // 2. 创建聊天记忆保留最近10轮对话 ChatMemory memory MessageWindowChatMemory.withMaxMessages(10); // 3. 使用AiServices创建Agent并绑定工具和记忆 assistant AiServices.builder(Assistant.class) .chatLanguageModel(model) .tools(calculatorTool, webSearchTool) // 注入工具 .chatMemory(memory) // 注入记忆 .build(); } public String chatWithAgent(String userMessage) { try { log.info(用户提问: {}, userMessage); String response assistant.chat(userMessage); log.info(Agent回复: {}, response); return response; } catch (Exception e) { log.error(Agent对话出错, e); return 抱歉处理您的请求时出现了问题: e.getMessage(); } } }// 文件路径src/main/java/com/example/agent/controller/AgentController.java package com.example.agent.controller; import com.example.agent.service.SimpleAgentService; import lombok.RequiredArgsConstructor; import org.springframework.web.bind.annotation.*; RestController RequestMapping(/api/agent) RequiredArgsConstructor public class AgentController { private final SimpleAgentService agentService; PostMapping(/chat) public String chat(RequestBody ChatRequest request) { return agentService.chatWithAgent(request.getMessage()); } // 简单的请求体 public static class ChatRequest { private String message; // getter and setter public String getMessage() { return message; } public void setMessage(String message) { this.message message; } } }3.5 运行与测试启动Spring Boot应用。使用curl、Postman 或任何HTTP客户端发送请求。curl -X POST http://localhost:8080/api/agent/chat \ -H Content-Type: application/json \ -d {message: 请先计算 125 乘以 8 等于多少然后搜索一下LangChain4j的最新版本信息。}预期行为 Agent会理解你的请求包含两个动作计算和搜索。它会先调用CalculatorTool.multiply(125, 8)得到结果1000。然后它会调用WebSearchTool.searchWeb(LangChain4j latest version)并将模拟的搜索结果与计算的结果整合生成一段连贯的回复例如“125乘以8等于1000。关于LangChain4j的最新版本根据模拟搜索目前最新版本是0.31.0……”。通过这个简单的例子你已经成功创建了一个具备多工具协作能力的AI Agent。它展示了LangChain4j如何将LLM、工具和记忆粘合在一起。4. 进阶实战构建具备记忆与复杂规划能力的Agent基础工具调用只是第一步。一个强大的Agent还需要记忆上下文和进行复杂任务规划的能力。4.1 实现持久化记忆使用向量数据库短期记忆MessageWindowChatMemory只在会话内有效。为了实现跨会话的长期记忆我们需要向量数据库如Chroma, Pinecone, 或本地的In-memory/本地文件。这里我们使用LangChain4j内置的InMemoryEmbeddingStore来演示生产环境请替换为ChromaEmbeddingStore或PineconeEmbeddingStore。// 文件路径src/main/java/com/example/agent/service/AgentWithMemoryService.java package com.example.agent.service; import dev.langchain4j.data.embedding.Embedding; import dev.langchain4j.data.segment.TextSegment; import dev.langchain4j.memory.chat.ChatMemoryProvider; import dev.langchain4j.memory.chat.MessageWindowChatMemory; import dev.langchain4j.model.embedding.AllMiniLmL6V2EmbeddingModel; import dev.langchain4j.model.embedding.EmbeddingModel; import dev.langchain4j.model.openai.OpenAiChatModel; import dev.langchain4j.retriever.EmbeddingStoreRetriever; import dev.langchain4j.service.AiServices; import dev.langchain4j.store.embedding.EmbeddingMatch; import dev.langchain4j.store.embedding.EmbeddingStore; import dev.langchain4j.store.embedding.inmemory.InMemoryEmbeddingStore; import jakarta.annotation.PostConstruct; import lombok.extern.slf4j.Slf4j; import org.springframework.stereotype.Service; import java.util.List; import static java.util.stream.Collectors.joining; Service Slf4j public class AgentWithMemoryService { interface KnowledgeableAssistant { String chat(String message); void memorizeFact(String fact); // 一个让Agent主动记忆事实的方法 } private KnowledgeableAssistant assistant; private EmbeddingStoreTextSegment embeddingStore; private EmbeddingModel embeddingModel; PostConstruct public void init() { // 1. 初始化嵌入模型和存储用于长期记忆 embeddingModel new AllMiniLmL6V2EmbeddingModel(); // 本地轻量嵌入模型 embeddingStore new InMemoryEmbeddingStore(); // 2. 创建检索器用于从记忆库中查找相关信息 EmbeddingStoreRetriever retriever EmbeddingStoreRetriever.from(embeddingStore, embeddingModel, 3); // 每次检索最相关的3条 // 3. 创建聊天模型和记忆提供者 OpenAiChatModel chatModel OpenAiChatModel.builder() .apiKey(System.getenv(OPENAI_API_KEY)) .baseUrl(System.getenv(OPENAI_BASE_URL)) .build(); ChatMemoryProvider memoryProvider memoryId - MessageWindowChatMemory.withMaxMessages(10); // 4. 构建Agent并注入检索器作为工具的一部分通过ContentRetrieverTool assistant AiServices.builder(KnowledgeableAssistant.class) .chatLanguageModel(chatModel) .contentRetriever(retriever) // 关键注入检索器Agent在需要背景知识时会自动查询 .chatMemoryProvider(memoryProvider) .build(); } public String chat(String userMessage) { return assistant.chat(userMessage); } // 手动添加知识到长期记忆库 public void addToMemory(String text) { Embedding embedding embeddingModel.embed(text).content(); TextSegment segment TextSegment.from(text); embeddingStore.add(embedding, segment); log.info(已记忆信息: {}, text); } // 查询记忆库中的相关信息用于调试 public ListString searchMemory(String query) { Embedding queryEmbedding embeddingModel.embed(query).content(); ListEmbeddingMatchTextSegment relevantMatches embeddingStore.findRelevant(queryEmbedding, 3); return relevantMatches.stream() .map(match - match.embedded().text() (相关性: match.score() )) .toList(); } }这个服务中的Agent在回答问题时会先从其“长期记忆”向量存储中检索与问题相关的历史信息将这些信息作为上下文提供给LLM从而做出更有依据的回答。4.2 实现自定义规划与执行循环对于更复杂的任务你可能需要更精细地控制Agent的“思考”过程。LangChain4j提供了ReAct等内置Agent但有时需要自定义。下面是一个简化版的自定义规划执行循环示例// 文件路径src/main/java/com/example/agent/service/CustomAgentService.java package com.example.agent.service; import dev.langchain4j.agent.tool.ToolExecutor; import dev.langchain4j.agent.tool.ToolSpecification; import dev.langchain4j.data.message.*; import dev.langchain4j.model.openai.OpenAiChatModel; import dev.langchain4j.model.output.Response; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.stereotype.Service; import java.util.*; Service Slf4j RequiredArgsConstructor public class CustomAgentService { private final OpenAiChatModel chatModel; private final ToolExecutor toolExecutor; // 需要注册你的工具到Spring Context private final ListToolSpecification toolSpecifications; // 工具规格列表 public String executeComplexTask(String goal) { StringBuilder fullLog new StringBuilder(); fullLog.append(目标: ).append(goal).append(\n\n); // 初始化对话历史 ListChatMessage messages new ArrayList(); messages.add(SystemMessage.from(你是一个善于规划和执行复杂任务的助手。请逐步思考必要时使用工具。)); messages.add(UserMessage.from(goal)); int maxSteps 10; for (int step 1; step maxSteps; step) { fullLog.append(--- 步骤 ).append(step).append( ---\n); // 1. 规划/思考让LLM给出下一步行动可能是最终答案或工具调用 ResponseAiMessage response chatModel.generate(messages); AiMessage aiMessage response.content(); messages.add(aiMessage); fullLog.append(AI思考: ).append(aiMessage.text()).append(\n); // 2. 检查是否需要工具调用 if (aiMessage.hasToolExecutionRequests()) { ListToolExecutionRequest toolCalls aiMessage.toolExecutionRequests(); for (ToolExecutionRequest toolCall : toolCalls) { // 3. 执行工具 fullLog.append(执行工具: ).append(toolCall.name()).append( 参数: ).append(toolCall.arguments()).append(\n); String toolResult toolExecutor.execute(toolCall, null); // 第二个参数可以是ToolExecutorContext fullLog.append(工具结果: ).append(toolResult).append(\n); // 4. 将结果返回给LLM ToolExecutionResultMessage resultMessage ToolExecutionResultMessage.from(toolCall, toolResult); messages.add(resultMessage); } } else { // 没有工具调用说明任务完成或给出了最终答案 fullLog.append(\n任务完成。最终答案:\n).append(aiMessage.text()); return aiMessage.text(); // 返回最终答案 } } fullLog.append(\n达到最大步骤限制任务未完成。); log.info(fullLog.toString()); return 任务执行超时或过于复杂。; } }这个自定义循环清晰地展示了Agent的“思考-行动-观察”过程。你可以在此基础上添加更复杂的逻辑比如对工具结果进行评估、动态调整计划等。5. 常见问题与排查思路Java Agent开发避坑指南在开发过程中你可能会遇到以下典型问题。问题现象可能原因排查思路与解决方案启动报错No qualifying bean of type OpenAiChatModel1.application.yml中LangChain4j配置前缀错误或格式不对。2. 未添加langchain4j-spring-boot-starter依赖。3. API Key或Base URL未配置。1. 检查yml配置缩进和属性名langchain4j.open-ai.chat-model.api-key。2. 确认pom.xml依赖已添加且版本一致。3. 确保环境变量或配置文件中包含正确的密钥和地址。Agent不调用工具直接回答“我不知道”1. 工具方法上的Tool注解描述不清晰。2. 传递给LLM的System Prompt未明确指示其使用工具。3. 工具参数类型或格式与LLM理解不匹配。1. 优化Tool注解中的描述确保准确说明工具功能和输入格式。2. 在系统消息或初始化时明确告诉LLM“你拥有以下工具请根据需要调用”。3. 确保工具方法参数是简单类型String, int, double等复杂对象需序列化。工具调用结果未被正确整合到后续回答中1. 对话历史Memory未正确管理丢失了工具执行结果消息。2. 自定义Agent循环中未将ToolExecutionResultMessage添加回消息列表。1. 检查使用的ChatMemory实现如MessageWindowChatMemory容量是否足够。2. 在自定义循环中确保每次工具执行后将结果以ToolExecutionResultMessage格式追加到messages列表。性能问题响应慢Token消耗高1. 每次请求都携带过长的对话历史。2. 向量检索时返回的上下文片段过多、过长。3. 工具执行本身是慢操作如网络请求。1. 使用TokenWindowChatMemory限制历史Token数或定期总结历史。2. 调整检索器参数如maxResults,minScore只返回最相关的少量片段。3. 对慢工具调用进行异步处理或设置超时。java.lang.OutOfMemoryError: Insufficient memory1. 向量数据库尤其是In-memory存储了大量高维向量。2. 大模型上下文窗口开得太大缓存了过多中间状态。3. 应用本身JVM堆内存设置过小。1. 对于生产环境使用外置向量数据库Chroma, Pinecone。2. 优化记忆策略清理旧消息。3. 调整JVM启动参数-Xmx4g等并监控堆内存使用情况。依赖冲突特别是与Spring Boot版本LangChain4j版本与Spring Boot版本不兼容。查看LangChain4j官方文档或GitHub仓库的Issue确认与你Spring Boot版本兼容的LangChain4j版本。通常需要保持依赖版本较新且匹配。6. 工程化最佳实践与进阶方向将Agent从Demo推向生产需要考虑更多工程化因素。6.1 配置管理与安全敏感信息API Key等绝对不要硬编码在代码中。使用Spring Cloud Config、Apollo、环境变量或云厂商的密钥管理服务。配置分离将不同环境dev, test, prod的模型参数如temperature, timeout进行分离管理。权限控制为工具调用添加权限校验。例如操作数据库的工具只能由特定角色的用户触发。6.2 可观测性与监控日志记录详细记录Agent的决策过程、工具调用详情、Token使用量、耗时。结构化日志JSON格式便于后续分析。链路追踪集成Micrometer、OpenTelemetry为每个用户会话生成Trace ID追踪完整的“用户输入 - Agent思考 - 工具调用 - 最终输出”链路。指标监控监控Agent的响应延迟、成功率、工具调用失败率、Token消耗成本等核心指标。6.3 稳定性与容错LLM调用重试与降级为LLM API调用配置重试机制如指数退避和熔断器如Resilience4j。当主要模型不可用时可降级到备用模型或返回缓存结果。工具调用超时与隔离为每个工具调用设置合理的超时时间并使用线程池隔离防止慢工具拖垮整个Agent。输入输出校验与过滤对用户输入进行严格的校验和清洗防止Prompt注入攻击。对模型输出进行必要的过滤和格式化确保符合业务规范。6.4 测试策略单元测试单独测试每个工具函数的正确性。集成测试测试Agent与LLM、向量数据库的集成。可以使用Mock Server来模拟LLM和外部API的响应。端到端测试构建典型用户场景的测试用例验证Agent从输入到输出的整体表现。由于LLM输出的非确定性需要关注核心逻辑而非字面匹配。6.5 进阶学习方向多Agent系统Swarm研究如何让多个特化Agent协作完成超复杂任务如AutoGen, CrewAI的设计理念。强化学习RL与评估引入人类反馈或自动评估器让Agent通过强化学习优化其规划和工具使用策略。与现有系统深度集成将Agent作为智能中间件深度集成到你的微服务架构、工作流引擎如Camunda或数据管道中。探索专用框架针对特定场景可以研究如Hermes Agent专注于工作流自动化、Harness与CI/CD管道集成等框架理解其与通用框架的区别和适用场景。从Java开发者转型Agent开发最大的优势在于你已具备强大的系统工程能力。AI Agent领域不缺想法缺的是能将想法稳健、高效、规模化落地的工程实现。掌握本文介绍的核心概念、框架用法和工程实践你已具备了坚实的起点。接下来选择一个你熟悉的业务场景如智能客服、数据分析助手、自动化运维从构建一个能解决实际痛点的简单Agent开始在实践中不断迭代和深化理解。