最近在技术社区和招聘市场上一个词的热度持续攀升Agent智能体。无论是AI领域的突破性应用还是企业数字化转型中对自动化流程的渴求都让具备自主感知、决策和执行能力的Agent成为了新的技术焦点。对于广大Java开发者而言这既是挑战也是机遇。挑战在于传统的后端开发思维需要向更复杂的AI驱动、状态管理和任务编排演进机遇在于Java庞大的生态和成熟的工程体系恰恰是构建稳定、可靠、可扩展的Agent系统的绝佳基石。如果你是一名Java开发者正在思考如何切入AI Agent开发或者你的团队正准备将Agent能力落地到实际业务中却苦于资料零散、概念抽象、不知从何下手那么这篇文章正是为你准备的。本文将彻底摒弃空泛的概念炒作从一个Java工程师的视角出发手把手带你构建一个可运行、可扩展的Agent系统。我们将从核心概念拆解开始逐步深入到环境搭建、框架选型、代码实战并最终探讨生产级的最佳实践和避坑指南。无论你是想个人转型学习还是为公司项目做技术预研这篇文章都将提供一条清晰的路径。1. Agent智能体从概念到工程落地在深入代码之前我们必须统一认知到底什么是Agent它和传统的程序、微服务有何本质区别1.1 Agent的核心定义与特征一个智能体Agent在计算机科学中通常被定义为一个驻留在特定环境中的实体它能够通过传感器Sensors感知环境并利用执行器Actuators对环境施加影响其核心目标是自主地完成既定目标。与我们熟悉的“服务”或“函数”相比Agent具备几个关键特征自主性Autonomy能在没有直接外部干预的情况下运作控制自身内部状态和行为。反应性Reactivity能感知环境包括用户输入、系统事件、其他Agent的消息等并及时做出响应。主动性Pro-activeness不仅对环境变化做出反应还能主动发起目标导向的行为。社交能力Social Ability能通过某种通信语言如ACL与其他Agent或人类进行交互以完成自身目标或帮助其他Agent。在当今AI驱动的语境下Agent通常特指LLM-powered Agent大语言模型驱动的智能体。其核心思想是将大语言模型LLM作为Agent的“大脑”负责理解、规划和决策而外部的工具Tools、记忆Memory和执行环境则构成了其“身体”和“经验”。1.2 为什么Java开发者适合做Agent开发你可能会问现在Agent的Demo和教程大多基于PythonJava还有机会吗答案是肯定的而且优势显著。工程化与稳定性Java语言及其生态Spring Boot, Maven/Gradle在构建高并发、分布式、高可用的企业级系统方面经验丰富。一个生产级的Agent系统绝不仅仅是调用API它涉及任务调度、状态持久化、故障恢复、监控告警等这正是Java的强项。庞大的现有系统集成企业中大量的核心业务系统ERP, CRM 金融交易系统都是用Java构建的。用Java开发Agent可以最自然、最安全地与这些系统进行深度集成和交互避免跨语言调用的复杂性和性能损耗。成熟的并发与多线程模型Agent系统本质上是异步、并发的。Java的CompletableFuture、响应式编程如Project Reactor、以及丰富的线程池工具为构建高效、可控的Agent执行引擎提供了坚实基础。强大的生态工具链从构建工具、依赖管理、到容器化部署、APM监控Java拥有最成熟的企业级开发生态。这能极大降低Agent系统从开发到运维的全生命周期成本。因此“Java Agent”的结合瞄准的是企业级、生产可用的智能自动化场景而非简单的原型演示。1.3 典型应用场景分析理解场景能帮助我们更好地设计Agent。以下是一些Java Agent可能大显身手的领域智能客服与工单处理Agent能理解用户自然语言描述的问题自动查询知识库、检索相似工单甚至执行预定义的脚本如重启服务、重置密码来尝试解决无法解决时再精准转交人工。自动化运维与监控监控系统告警触发后Agent能自动分析日志、关联指标判断根因并执行预案如扩容、切换流量、回滚版本。内部业务流程助手员工可以通过自然语言命令Agent完成诸如“为新项目XXX申请云服务器并配置网络”、“查询上季度A产品的销售数据并生成图表”等复杂流程Agent自动串联多个内部系统API。数据分析与报告生成Agent接受如“分析本月用户活跃度下降原因”的指令自动连接数据仓库、执行查询、进行初步分析并生成包含核心洞察的报告草稿。2. 环境准备与核心组件选型开始编码前我们需要搭建开发环境并选择合适的技术栈。我们的目标是构建一个轻量级但结构清晰的Agent框架。2.1 基础开发环境JDK建议使用JDK 17或JDK 21LTS版本。新版本的GC和语言特性对长期运行的服务更友好。构建工具Maven或Gradle。本文示例使用Maven。IDEIntelliJ IDEA推荐或 Eclipse。LLM API你需要一个大型语言模型的API访问权限。我们将使用OpenAI GPT系列模型如gpt-3.5-turbo作为“大脑”示例。你也可以替换为国内可访问的模型如通义千问、文心一言等原理相通。准备你的OPENAI_API_KEY。2.2 核心框架与库选择我们将以Spring Boot为基础整合一个轻量级的Agent核心框架。这里我们不直接使用最重型的框架而是通过核心库自底向上构建以加深理解。Spring Boot (3.x)提供基础的Web、配置管理和依赖注入能力。OpenAI Java Client用于调用OpenAI API。我们使用非官方的com.theokanning.openai-gpt3-java库它简单易用。JSON处理使用Spring Boot默认集成的Jackson。工具执行引擎我们将自己实现一个简单的工具注册和执行机制这是Agent的“手”。记忆模块为了简化我们使用内存存储如ConcurrentHashMap作为短期记忆。生产环境需替换为Redis或数据库。2.3 初始化Spring Boot项目使用 Spring Initializr 或IDE创建项目。Project: MavenLanguage: JavaSpring Boot: 3.2.xGroup:com.exampleArtifact:agent-demoDependencies:Spring Web(提供Web能力用于接收Agent指令)Spring Boot DevTools(开发热加载)Lombok(简化代码可选)生成项目后在pom.xml中添加OpenAI客户端依赖dependency groupIdcom.theokanning.openai-gpt3-java/groupId artifactIdservice/artifactId version0.18.2/version !-- 请检查最新版本 -- /dependency3. Agent核心架构与原理拆解一个典型的LLM驱动Agent包含以下几个核心组件我们将逐一实现。3.1 组件一工具Tools—— Agent的能力延伸工具是Agent与外部世界交互的接口。每个工具对应一个可执行的功能比如调用一个API、执行一段计算、查询数据库等。工具接口设计// 文件路径src/main/java/com/example/agent/core/tool/Tool.java package com.example.agent.core.tool; import com.fasterxml.jackson.databind.JsonNode; /** * 工具接口。所有Agent可用的工具都必须实现此接口。 */ public interface Tool { /** * 工具的唯一名称用于LLM识别和调用。 */ String getName(); /** * 工具的自然语言描述用于帮助LLM理解何时使用此工具。 */ String getDescription(); /** * 工具执行方法的参数JSON Schema定义。 * 用于告诉LLM调用此工具时需要提供哪些参数。 * return 参数结构的JsonNode描述 */ JsonNode getParametersSchema(); /** * 执行工具的核心方法。 * param arguments 调用参数通常是一个JSON字符串或对象。 * return 执行结果通常是字符串格式将被反馈给LLM。 */ String execute(String arguments); }示例工具实现计算器// 文件路径src/main/java/com/example/agent/core/tool/impl/CalculatorTool.java package com.example.agent.core.tool.impl; import com.example.agent.core.tool.Tool; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import lombok.extern.slf4j.Slf4j; import org.springframework.stereotype.Component; Slf4j Component public class CalculatorTool implements Tool { private static final ObjectMapper mapper new ObjectMapper(); Override public String getName() { return calculator; } Override public String getDescription() { return 一个简单的计算器用于执行基本的数学运算加、减、乘、除。; } Override public JsonNode getParametersSchema() { // 定义JSON Schema告诉LLM需要提供operation和两个operands ObjectNode schema mapper.createObjectNode(); schema.put(type, object); schema.put(description, 计算参数); ObjectNode properties mapper.createObjectNode(); properties.set(operation, mapper.createObjectNode() .put(type, string) .put(description, 运算类型可选值add, subtract, multiply, divide) .put(enum, mapper.createArrayNode().add(add).add(subtract).add(multiply).add(divide))); properties.set(num1, mapper.createObjectNode() .put(type, number) .put(description, 第一个操作数)); properties.set(num2, mapper.createObjectNode() .put(type, number) .put(description, 第二个操作数)); schema.set(properties, properties); schema.putArray(required).add(operation).add(num1).add(num2); return schema; } Override public String execute(String arguments) { try { JsonNode argsNode mapper.readTree(arguments); String operation argsNode.get(operation).asText(); double num1 argsNode.get(num1).asDouble(); double num2 argsNode.get(num2).asDouble(); double result; switch (operation) { case add: result num1 num2; break; case subtract: result num1 - num2; break; case multiply: result num1 * num2; break; case divide: if (num2 0) { return 错误除数不能为零。; } result num1 / num2; break; default: return 错误不支持的运算类型 operation 。; } return String.format(计算结果%.2f, result); } catch (Exception e) { log.error(计算器工具执行失败参数: {}, arguments, e); return 执行计算时发生错误 e.getMessage(); } } }3.2 组件二工具管理器ToolManager—— 能力的注册与发现Agent需要知道它有哪些工具可用。ToolManager负责工具的注册、存储和按名称检索。// 文件路径src/main/java/com/example/agent/core/tool/ToolManager.java package com.example.agent.core.tool; import org.springframework.stereotype.Component; import javax.annotation.PostConstruct; import java.util.HashMap; import java.util.List; import java.util.Map; Component public class ToolManager { private final MapString, Tool toolRegistry new HashMap(); private final ListTool tools; // 通过Spring自动注入所有Tool Bean public ToolManager(ListTool tools) { this.tools tools; } PostConstruct public void init() { for (Tool tool : tools) { toolRegistry.put(tool.getName(), tool); System.out.println(已注册工具: tool.getName() - tool.getDescription()); } } public Tool getTool(String name) { return toolRegistry.get(name); } public MapString, Tool getAllTools() { return new HashMap(toolRegistry); } }3.3 组件三记忆Memory—— Agent的上下文与历史记忆让Agent拥有“短期记忆”能记住对话历史或任务上下文从而进行连贯的交互。我们实现一个简单的对话记忆。// 文件路径src/main/java/com/example/agent/core/memory/Memory.java package com.example.agent.core.memory; import java.util.List; /** * 记忆接口用于存储和检索Agent的交互历史。 */ public interface Memory { /** * 添加一条消息到记忆。 * param role 角色如 user, assistant, system * param content 消息内容 */ void addMessage(String role, String content); /** * 获取最近的N条消息历史。 * param limit 获取的消息条数限制 * return 消息历史列表 */ ListMessage getRecentMessages(int limit); /** * 清空记忆。 */ void clear(); class Message { private final String role; private final String content; // 省略构造函数、getter/setter } }基于内存的实现// 文件路径src/main/java/com/example/agent/core/memory/impl/SimpleConversationMemory.java package com.example.agent.core.memory.impl; import com.example.agent.core.memory.Memory; import org.springframework.stereotype.Component; import java.util.ArrayList; import java.util.List; import java.util.concurrent.CopyOnWriteArrayList; Component public class SimpleConversationMemory implements Memory { private final ListMessage messages new CopyOnWriteArrayList(); private static final int MAX_HISTORY 20; // 防止内存无限增长 Override public synchronized void addMessage(String role, String content) { messages.add(new Message(role, content)); // 限制历史记录长度 if (messages.size() MAX_HISTORY) { messages.remove(0); } } Override public ListMessage getRecentMessages(int limit) { int fromIndex Math.max(0, messages.size() - limit); return new ArrayList(messages.subList(fromIndex, messages.size())); } Override public synchronized void clear() { messages.clear(); } // 内部类 Message 实现... }3.4 组件四Agent核心引擎AgentEngine—— 大脑与调度中心这是最核心的部分它负责接收用户输入。结合记忆构造发送给LLM的提示词Prompt。调用LLM API并获得响应。解析LLM的响应判断是需要调用工具还是直接回复。执行工具并将结果再次反馈给LLM形成循环ReAct模式直到任务完成。// 文件路径src/main/java/com/example/agent/core/engine/AgentEngine.java package com.example.agent.core.engine; import com.example.agent.core.tool.Tool; import com.example.agent.core.tool.ToolManager; import com.example.agent.core.memory.Memory; import com.theokanning.openai.completion.chat.*; import com.theokanning.openai.service.OpenAiService; import lombok.extern.slf4j.Slf4j; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Component; import javax.annotation.PostConstruct; import java.time.Duration; import java.util.*; import java.util.stream.Collectors; Slf4j Component public class AgentEngine { private OpenAiService openAiService; private final ToolManager toolManager; private final Memory memory; Value(${openai.api.key}) private String apiKey; Value(${openai.model:gpt-3.5-turbo}) private String model; Value(${openai.api.timeout:60}) private int timeoutSeconds; // 系统提示词定义Agent的角色和能力 private static final String SYSTEM_PROMPT_TEMPLATE 你是一个专业的助手可以调用工具来帮助用户解决问题。 你可以使用的工具如下 %s 当用户提出需要计算、查询或操作时你应该思考是否需要使用工具。 如果你决定使用工具请严格按照以下JSON格式回复且只回复这个JSON不要有任何其他文字 {action: tool_call, tool_name: 工具名称, arguments: {参数1: 值1, 参数2: 值2}} 如果不需要使用工具或者工具执行后得到了最终答案请直接以自然语言回复用户。 注意arguments必须是一个有效的JSON对象符合对应工具的参数要求。 ; public AgentEngine(ToolManager toolManager, Memory memory) { this.toolManager toolManager; this.memory memory; } PostConstruct public void init() { if (apiKey null || apiKey.isBlank()) { throw new IllegalArgumentException(OpenAI API Key 未配置请在application.properties中设置openai.api.key); } this.openAiService new OpenAiService(apiKey, Duration.ofSeconds(timeoutSeconds)); log.info(AgentEngine 初始化完成使用模型: {}, model); } /** * 处理用户输入的核心方法。 * param userInput 用户输入 * return Agent的最终回复 */ public String process(String userInput) { // 1. 将用户输入加入记忆 memory.addMessage(user, userInput); log.info(处理用户输入: {}, userInput); // 2. 准备对话历史和新消息 ListChatMessage messages prepareChatMessages(); // 3. 与LLM交互可能涉及多轮工具调用简化示例这里只做单轮或有限轮 int maxIterations 5; // 防止无限循环 for (int i 0; i maxIterations; i) { ChatCompletionRequest request ChatCompletionRequest.builder() .model(model) .messages(messages) .temperature(0.2) // 低随机性保证工具调用格式稳定 .build(); ChatCompletionResult result openAiService.createChatCompletion(request); ChatMessage assistantMessage result.getChoices().get(0).getMessage(); String content assistantMessage.getContent().trim(); log.debug(LLM 原始回复: {}, content); // 4. 解析LLM回复 ParsedResponse parsedResponse parseResponse(content); if (parsedResponse.isToolCall()) { // 5. 执行工具调用 String toolResult executeTool(parsedResponse.getToolName(), parsedResponse.getArguments()); log.info(工具 {} 执行结果: {}, parsedResponse.getToolName(), toolResult); // 将工具执行结果作为一条“系统”或“工具”消息加入历史供下一轮LLM参考 memory.addMessage(system, 工具 parsedResponse.getToolName() 返回结果: toolResult); // 重新准备消息进入下一轮循环 messages prepareChatMessages(); } else { // 6. 得到最终回复 memory.addMessage(assistant, content); return content; } } return 抱歉在处理您的问题时经过多轮尝试仍未完成。请简化您的问题或稍后再试。; } private ListChatMessage prepareChatMessages() { ListChatMessage messages new ArrayList(); // 系统提示词动态注入工具描述 String toolsDescription buildToolsDescription(); String systemPrompt String.format(SYSTEM_PROMPT_TEMPLATE, toolsDescription); messages.add(new ChatMessage(ChatMessageRole.SYSTEM.value(), systemPrompt)); // 从记忆中添加最近的对话历史例如最近10轮 ListMemory.Message history memory.getRecentMessages(10); for (Memory.Message msg : history) { messages.add(new ChatMessage(msg.getRole(), msg.getContent())); } return messages; } private String buildToolsDescription() { return toolManager.getAllTools().values().stream() .map(tool - String.format(- 工具名称: %s\n 描述: %s\n 参数格式: %s, tool.getName(), tool.getDescription(), tool.getParametersSchema().toString())) .collect(Collectors.joining(\n\n)); } private ParsedResponse parseResponse(String content) { // 简单解析JSON判断是否为工具调用。生产环境应用更健壮的JSON解析库。 try { if (content.startsWith({) content.contains(\action\:\tool_call\)) { // 使用Jackson解析此处简化实际需完整解析 com.fasterxml.jackson.databind.ObjectMapper mapper new com.fasterxml.jackson.databind.ObjectMapper(); Map?, ? map mapper.readValue(content, Map.class); if (tool_call.equals(map.get(action))) { String toolName (String) map.get(tool_name); String arguments mapper.writeValueAsString(map.get(arguments)); return ParsedResponse.toolCall(toolName, arguments); } } } catch (Exception e) { log.warn(解析LLM响应失败视为自然语言回复。内容: {}, content, e); } return ParsedResponse.textResponse(content); } private String executeTool(String toolName, String arguments) { Tool tool toolManager.getTool(toolName); if (tool null) { return 错误未知的工具 toolName 。; } try { return tool.execute(arguments); } catch (Exception e) { log.error(执行工具 {} 时发生异常参数: {}, toolName, arguments, e); return 工具执行过程中发生错误: e.getMessage(); } } // 内部类用于封装解析结果 lombok.Data private static class ParsedResponse { private final boolean toolCall; private final String toolName; private final String arguments; private final String text; static ParsedResponse toolCall(String toolName, String arguments) { return new ParsedResponse(true, toolName, arguments, null); } static ParsedResponse textResponse(String text) { return new ParsedResponse(false, null, null, text); } } }4. 完整实战构建一个数学助手Agent现在我们将所有组件串联起来创建一个简单的Web接口让用户能与我们的Agent交互。4.1 创建Web控制器Controller// 文件路径src/main/java/com/example/agent/controller/AgentController.java package com.example.agent.controller; import com.example.agent.core.engine.AgentEngine; import lombok.RequiredArgsConstructor; import org.springframework.web.bind.annotation.*; RestController RequestMapping(/api/agent) RequiredArgsConstructor public class AgentController { private final AgentEngine agentEngine; PostMapping(/chat) public String chat(RequestBody ChatRequest request) { if (request.getMessage() null || request.getMessage().trim().isEmpty()) { return 请输入有效消息。; } return agentEngine.process(request.getMessage()); } PostMapping(/reset) public String reset() { // 这里需要注入Memory Bean来清空为了简化我们假设AgentEngine提供了reset方法 // 实际应在AgentEngine中暴露memory.clear() return 对话历史已重置。; } lombok.Data public static class ChatRequest { private String message; } }4.2 应用配置文件# 文件路径src/main/resources/application.properties # OpenAI 配置 (务必替换成你自己的Key并确保网络可访问) openai.api.keysk-your-openai-api-key-here openai.modelgpt-3.5-turbo openai.api.timeout30 # 服务器端口 server.port8080 # 日志级别 logging.level.com.example.agentDEBUG4.3 运行与测试启动应用运行AgentDemoApplication的main方法。使用工具测试使用curl或 Postman 发送 POST 请求。curl -X POST http://localhost:8080/api/agent/chat \ -H Content-Type: application/json \ -d {message: 请计算一下 125 乘以 38 等于多少}预期过程Agent收到问题。LLM判断需要调用calculator工具。回复JSON{action: tool_call, tool_name: calculator, arguments: {operation: multiply, num1: 125, num2: 38}}AgentEngine解析并执行计算器工具。工具返回结果“计算结果4750.00”。该结果被加入记忆再次调用LLM。LLM根据工具结果组织最终回复“125乘以38等于4750。”你将收到这个最终回复。多轮对话测试# 第一轮 curl ... -d {message: 你好} # 回复你好有什么可以帮你的吗 # 第二轮 curl ... -d {message: 上面的结果再加上100} # 回复你指的是哪个结果呢如果你指的是之前的计算结果4750那么4750加上100等于4850。这展示了记忆模块的作用Agent能引用上下文。5. 常见问题与深度排查指南在开发和生产运行Agent时你会遇到各种问题。以下是一些典型问题及解决思路。5.1 LLM相关问题问题现象可能原因排查步骤与解决方案调用API超时或网络错误1. 网络不通或代理问题。2. API Key无效或额度不足。3. 服务端响应慢。1. 检查网络连接使用curl或ping测试API端点可达性。2. 在OpenAI Dashboard检查Key状态和余额。3. 增加openai.api.timeout配置并考虑实现重试机制。LLM回复格式不符合预期无法解析工具调用1. 系统提示词SYSTEM_PROMPT不够清晰。2. 温度temperature参数过高导致输出随机。3. 模型能力不足。1.优化提示词工程明确指令提供更严格的输出格式示例Few-Shot Prompting。2.降低temperature如设为0.1使输出更确定。3. 升级到更强大的模型如gpt-4或使用OpenAI的function calling特性替代自行解析。回复内容包含无关信息或“思考过程”提示词未要求LLM“只回复JSON”或“不要有其他文字”。在系统提示词中强调输出格式例如“你必须只输出指定的JSON格式不要输出任何其他解释、道歉或标记。”5.2 工具执行与集成问题问题现象可能原因排查步骤与解决方案ToolManager找不到工具1. Tool类未加Component注解。2. 工具名称getName()与LLM调用的名称不匹配。1. 检查Spring Boot启动日志确认工具Bean已被加载和注册。2. 在buildToolsDescription()方法中打印所有注册的工具列表进行核对。工具执行参数解析失败1. LLM生成的参数JSON格式错误。2. 参数类型或值与工具期望的不符。1. 在parseResponse和工具execute方法中增加更详细的日志和异常捕获。2. 在提示词中提供更精确的参数Schema示例甚至使用JSON Schema标准描述。工具执行慢或阻塞主线程工具涉及网络IO、复杂计算或数据库查询。将工具执行异步化。使用Async注解或CompletableFuture.supplyAsync()避免阻塞Agent的响应循环。5.3 内存与性能问题问题现象可能原因排查思路内存占用持续增长1. 记忆Memory未做容量限制。2. 聊天消息或工具结果过大。3. 内存泄漏如未正确管理LLM客户端连接。1. 像SimpleConversationMemory一样实现历史消息上限。2. 对长文本进行摘要Summarization后再存入记忆。3. 使用Profiling工具如VisualVM, JProfiler分析堆内存。Agent响应越来越慢1. 记忆历史过长导致每次请求的Prompt巨大LLM处理变慢且Token费用高。2. 工具调用链路过长ReAct循环次数多。1.实现记忆窗口或摘要只保留最近N轮对话或将更早的对话总结成一段摘要。2.设置最大迭代次数如代码中的maxIterations防止死循环。3.优化提示词引导LLM更高效地规划减少不必要的工具调用。5.4 生产环境部署问题API Key管理绝对不要将API Key硬编码在代码或配置文件中提交到代码仓库。使用环境变量、配置中心如Apollo或云厂商的密钥管理服务。容错与降级LLM服务可能不稳定。必须为LLM API调用和工具调用添加重试、熔断如Resilience4j和超时控制。监控与可观测性记录关键指标LLM调用耗时、Token使用量、工具调用成功率、Agent会话时长。集成Micrometer和Prometheus/Grafana。安全性工具权限控制不是所有用户都能调用所有工具。需要实现基于用户/角色的工具访问权限校验。输入输出过滤对用户输入和LLM输出进行必要的安全检查防止Prompt注入攻击。敏感信息确保工具不会泄露或处理未经授权的敏感数据。6. 进阶架构与最佳实践当你的Agent从Demo走向生产需要考虑更复杂的架构和工程实践。6.1 架构演进从单体到分布式工具服务化将复杂的工具拆分为独立的微服务。Agent核心通过RPC或消息队列调用这些服务实现解耦和独立扩缩容。专用记忆存储使用Redis存储短期会话记忆使用数据库如PostgreSQL存储长期记忆和知识库。这支持多实例部署和会话持久化。任务队列与异步处理对于耗时的Agent任务如生成报告不应阻塞HTTP请求。可以将用户请求放入消息队列如RabbitMQ, Kafka由后台Worker进程消费并处理通过WebSocket或轮询通知用户结果。Agent池与负载均衡高并发下可以部署多个Agent实例通过网关进行负载均衡。需要解决有状态如记忆的问题通常将会话ID与特定的Agent实例或共享存储关联。6.2 提示词工程优化提示词的质量直接决定Agent的性能。结构化输出强烈建议使用OpenAI的Function Calling或JSON Mode。这能保证LLM输出结构化的数据彻底解决解析问题。我们的示例中手动解析JSON是简化方案。少样本示例Few-Shot在系统提示词中提供几个“用户输入-理想输出”的配对示例能极大地提升LLM遵循指令的能力。思维链Chain-of-Thought对于复杂问题在提示词中鼓励LLM“逐步思考”可以提高其推理和工具调用的准确性。动态上下文管理根据对话长度和复杂度动态选择注入记忆的策略全量历史、最近N条、摘要等以平衡效果和Token成本。6.3 利用现有Java Agent框架当项目复杂度提升时可以考虑基于成熟的开源框架开发避免重复造轮子。LangChain4JJava版的LangChain提供了强大的Chain、Tool、Memory、Agent抽象和大量集成。这是目前Java生态中最活跃的Agent框架。Spring AISpring官方推出的AI应用开发框架提供了统一的API访问多种模型OpenAI, Azure OpenAI, Ollama等并集成了Prompt管理、向量数据库等能力与Spring Boot无缝集成。使用LangChain4J重构工具调用的优势// 示例使用LangChain4J定义工具 Tool(计算两个数字的和) public String addNumbers(P(第一个数字) double a, P(第二个数字) double b) { return String.valueOf(a b); } // LangChain4J会自动处理工具描述、JSON Schema生成以及与LLM的交互大大简化代码。6.4 测试策略Agent系统的测试更具挑战性因为涉及非确定性的LLM。单元测试隔离测试每个Tool的实现、Memory的操作、Response的解析逻辑。Mock掉LLM调用。集成测试使用一个固定的、简单的Mock LLM例如总是返回预定格式的工具调用来测试AgentEngine的完整流程。端到端测试针对关键用户旅程编写测试用例使用真实的LLM但可能是低成本模型如gpt-3.5-turbo进行测试主要验证功能是否贯通并对输出进行断言如是否包含某个关键词。评估Evaluation生产前需要一套评估体系来衡量Agent的质量例如任务完成率、工具调用准确率、用户满意度人工评估。这通常需要构建一个测试用例集和评估标准。从Java后端开发转向Agent智能体开发并非要抛弃原有的技术栈而是将Java在工程化、稳定性、系统集成方面的优势与AI的感知和决策能力相结合。这条路的核心在于理解Agent的架构范式感知-规划-执行循环并运用扎实的软件工程能力将其实现。本文带你从零构建了一个具备工具调用和记忆能力的Agent内核这只是一个起点。接下来你可以沿着这些方向深入集成更强大的框架深入研究LangChain4J或Spring AI利用其生态快速集成搜索引擎、数据库等工具。设计复杂的Agent工作流实现多个Agent协同Multi-Agent或设计支持复杂规划Planning的Agent。专注垂直领域将Agent能力与你的业务领域如金融、运维、客服深度结合打造真正创造价值的专家系统。Agent开发的世界刚刚开启充满了可能性。拿起你熟悉的Java工具开始构建属于你的智能体吧。在实践过程中多思考架构的扩展性、系统的稳定性和最终的用户价值这将是你在这一波技术浪潮中脱颖而出的关键。 Java开发者实战指南：从零构建AI Agent智能体系统
最近在技术社区和招聘市场上一个词的热度持续攀升Agent智能体。无论是AI领域的突破性应用还是企业数字化转型中对自动化流程的渴求都让具备自主感知、决策和执行能力的Agent成为了新的技术焦点。对于广大Java开发者而言这既是挑战也是机遇。挑战在于传统的后端开发思维需要向更复杂的AI驱动、状态管理和任务编排演进机遇在于Java庞大的生态和成熟的工程体系恰恰是构建稳定、可靠、可扩展的Agent系统的绝佳基石。如果你是一名Java开发者正在思考如何切入AI Agent开发或者你的团队正准备将Agent能力落地到实际业务中却苦于资料零散、概念抽象、不知从何下手那么这篇文章正是为你准备的。本文将彻底摒弃空泛的概念炒作从一个Java工程师的视角出发手把手带你构建一个可运行、可扩展的Agent系统。我们将从核心概念拆解开始逐步深入到环境搭建、框架选型、代码实战并最终探讨生产级的最佳实践和避坑指南。无论你是想个人转型学习还是为公司项目做技术预研这篇文章都将提供一条清晰的路径。1. Agent智能体从概念到工程落地在深入代码之前我们必须统一认知到底什么是Agent它和传统的程序、微服务有何本质区别1.1 Agent的核心定义与特征一个智能体Agent在计算机科学中通常被定义为一个驻留在特定环境中的实体它能够通过传感器Sensors感知环境并利用执行器Actuators对环境施加影响其核心目标是自主地完成既定目标。与我们熟悉的“服务”或“函数”相比Agent具备几个关键特征自主性Autonomy能在没有直接外部干预的情况下运作控制自身内部状态和行为。反应性Reactivity能感知环境包括用户输入、系统事件、其他Agent的消息等并及时做出响应。主动性Pro-activeness不仅对环境变化做出反应还能主动发起目标导向的行为。社交能力Social Ability能通过某种通信语言如ACL与其他Agent或人类进行交互以完成自身目标或帮助其他Agent。在当今AI驱动的语境下Agent通常特指LLM-powered Agent大语言模型驱动的智能体。其核心思想是将大语言模型LLM作为Agent的“大脑”负责理解、规划和决策而外部的工具Tools、记忆Memory和执行环境则构成了其“身体”和“经验”。1.2 为什么Java开发者适合做Agent开发你可能会问现在Agent的Demo和教程大多基于PythonJava还有机会吗答案是肯定的而且优势显著。工程化与稳定性Java语言及其生态Spring Boot, Maven/Gradle在构建高并发、分布式、高可用的企业级系统方面经验丰富。一个生产级的Agent系统绝不仅仅是调用API它涉及任务调度、状态持久化、故障恢复、监控告警等这正是Java的强项。庞大的现有系统集成企业中大量的核心业务系统ERP, CRM 金融交易系统都是用Java构建的。用Java开发Agent可以最自然、最安全地与这些系统进行深度集成和交互避免跨语言调用的复杂性和性能损耗。成熟的并发与多线程模型Agent系统本质上是异步、并发的。Java的CompletableFuture、响应式编程如Project Reactor、以及丰富的线程池工具为构建高效、可控的Agent执行引擎提供了坚实基础。强大的生态工具链从构建工具、依赖管理、到容器化部署、APM监控Java拥有最成熟的企业级开发生态。这能极大降低Agent系统从开发到运维的全生命周期成本。因此“Java Agent”的结合瞄准的是企业级、生产可用的智能自动化场景而非简单的原型演示。1.3 典型应用场景分析理解场景能帮助我们更好地设计Agent。以下是一些Java Agent可能大显身手的领域智能客服与工单处理Agent能理解用户自然语言描述的问题自动查询知识库、检索相似工单甚至执行预定义的脚本如重启服务、重置密码来尝试解决无法解决时再精准转交人工。自动化运维与监控监控系统告警触发后Agent能自动分析日志、关联指标判断根因并执行预案如扩容、切换流量、回滚版本。内部业务流程助手员工可以通过自然语言命令Agent完成诸如“为新项目XXX申请云服务器并配置网络”、“查询上季度A产品的销售数据并生成图表”等复杂流程Agent自动串联多个内部系统API。数据分析与报告生成Agent接受如“分析本月用户活跃度下降原因”的指令自动连接数据仓库、执行查询、进行初步分析并生成包含核心洞察的报告草稿。2. 环境准备与核心组件选型开始编码前我们需要搭建开发环境并选择合适的技术栈。我们的目标是构建一个轻量级但结构清晰的Agent框架。2.1 基础开发环境JDK建议使用JDK 17或JDK 21LTS版本。新版本的GC和语言特性对长期运行的服务更友好。构建工具Maven或Gradle。本文示例使用Maven。IDEIntelliJ IDEA推荐或 Eclipse。LLM API你需要一个大型语言模型的API访问权限。我们将使用OpenAI GPT系列模型如gpt-3.5-turbo作为“大脑”示例。你也可以替换为国内可访问的模型如通义千问、文心一言等原理相通。准备你的OPENAI_API_KEY。2.2 核心框架与库选择我们将以Spring Boot为基础整合一个轻量级的Agent核心框架。这里我们不直接使用最重型的框架而是通过核心库自底向上构建以加深理解。Spring Boot (3.x)提供基础的Web、配置管理和依赖注入能力。OpenAI Java Client用于调用OpenAI API。我们使用非官方的com.theokanning.openai-gpt3-java库它简单易用。JSON处理使用Spring Boot默认集成的Jackson。工具执行引擎我们将自己实现一个简单的工具注册和执行机制这是Agent的“手”。记忆模块为了简化我们使用内存存储如ConcurrentHashMap作为短期记忆。生产环境需替换为Redis或数据库。2.3 初始化Spring Boot项目使用 Spring Initializr 或IDE创建项目。Project: MavenLanguage: JavaSpring Boot: 3.2.xGroup:com.exampleArtifact:agent-demoDependencies:Spring Web(提供Web能力用于接收Agent指令)Spring Boot DevTools(开发热加载)Lombok(简化代码可选)生成项目后在pom.xml中添加OpenAI客户端依赖dependency groupIdcom.theokanning.openai-gpt3-java/groupId artifactIdservice/artifactId version0.18.2/version !-- 请检查最新版本 -- /dependency3. Agent核心架构与原理拆解一个典型的LLM驱动Agent包含以下几个核心组件我们将逐一实现。3.1 组件一工具Tools—— Agent的能力延伸工具是Agent与外部世界交互的接口。每个工具对应一个可执行的功能比如调用一个API、执行一段计算、查询数据库等。工具接口设计// 文件路径src/main/java/com/example/agent/core/tool/Tool.java package com.example.agent.core.tool; import com.fasterxml.jackson.databind.JsonNode; /** * 工具接口。所有Agent可用的工具都必须实现此接口。 */ public interface Tool { /** * 工具的唯一名称用于LLM识别和调用。 */ String getName(); /** * 工具的自然语言描述用于帮助LLM理解何时使用此工具。 */ String getDescription(); /** * 工具执行方法的参数JSON Schema定义。 * 用于告诉LLM调用此工具时需要提供哪些参数。 * return 参数结构的JsonNode描述 */ JsonNode getParametersSchema(); /** * 执行工具的核心方法。 * param arguments 调用参数通常是一个JSON字符串或对象。 * return 执行结果通常是字符串格式将被反馈给LLM。 */ String execute(String arguments); }示例工具实现计算器// 文件路径src/main/java/com/example/agent/core/tool/impl/CalculatorTool.java package com.example.agent.core.tool.impl; import com.example.agent.core.tool.Tool; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import lombok.extern.slf4j.Slf4j; import org.springframework.stereotype.Component; Slf4j Component public class CalculatorTool implements Tool { private static final ObjectMapper mapper new ObjectMapper(); Override public String getName() { return calculator; } Override public String getDescription() { return 一个简单的计算器用于执行基本的数学运算加、减、乘、除。; } Override public JsonNode getParametersSchema() { // 定义JSON Schema告诉LLM需要提供operation和两个operands ObjectNode schema mapper.createObjectNode(); schema.put(type, object); schema.put(description, 计算参数); ObjectNode properties mapper.createObjectNode(); properties.set(operation, mapper.createObjectNode() .put(type, string) .put(description, 运算类型可选值add, subtract, multiply, divide) .put(enum, mapper.createArrayNode().add(add).add(subtract).add(multiply).add(divide))); properties.set(num1, mapper.createObjectNode() .put(type, number) .put(description, 第一个操作数)); properties.set(num2, mapper.createObjectNode() .put(type, number) .put(description, 第二个操作数)); schema.set(properties, properties); schema.putArray(required).add(operation).add(num1).add(num2); return schema; } Override public String execute(String arguments) { try { JsonNode argsNode mapper.readTree(arguments); String operation argsNode.get(operation).asText(); double num1 argsNode.get(num1).asDouble(); double num2 argsNode.get(num2).asDouble(); double result; switch (operation) { case add: result num1 num2; break; case subtract: result num1 - num2; break; case multiply: result num1 * num2; break; case divide: if (num2 0) { return 错误除数不能为零。; } result num1 / num2; break; default: return 错误不支持的运算类型 operation 。; } return String.format(计算结果%.2f, result); } catch (Exception e) { log.error(计算器工具执行失败参数: {}, arguments, e); return 执行计算时发生错误 e.getMessage(); } } }3.2 组件二工具管理器ToolManager—— 能力的注册与发现Agent需要知道它有哪些工具可用。ToolManager负责工具的注册、存储和按名称检索。// 文件路径src/main/java/com/example/agent/core/tool/ToolManager.java package com.example.agent.core.tool; import org.springframework.stereotype.Component; import javax.annotation.PostConstruct; import java.util.HashMap; import java.util.List; import java.util.Map; Component public class ToolManager { private final MapString, Tool toolRegistry new HashMap(); private final ListTool tools; // 通过Spring自动注入所有Tool Bean public ToolManager(ListTool tools) { this.tools tools; } PostConstruct public void init() { for (Tool tool : tools) { toolRegistry.put(tool.getName(), tool); System.out.println(已注册工具: tool.getName() - tool.getDescription()); } } public Tool getTool(String name) { return toolRegistry.get(name); } public MapString, Tool getAllTools() { return new HashMap(toolRegistry); } }3.3 组件三记忆Memory—— Agent的上下文与历史记忆让Agent拥有“短期记忆”能记住对话历史或任务上下文从而进行连贯的交互。我们实现一个简单的对话记忆。// 文件路径src/main/java/com/example/agent/core/memory/Memory.java package com.example.agent.core.memory; import java.util.List; /** * 记忆接口用于存储和检索Agent的交互历史。 */ public interface Memory { /** * 添加一条消息到记忆。 * param role 角色如 user, assistant, system * param content 消息内容 */ void addMessage(String role, String content); /** * 获取最近的N条消息历史。 * param limit 获取的消息条数限制 * return 消息历史列表 */ ListMessage getRecentMessages(int limit); /** * 清空记忆。 */ void clear(); class Message { private final String role; private final String content; // 省略构造函数、getter/setter } }基于内存的实现// 文件路径src/main/java/com/example/agent/core/memory/impl/SimpleConversationMemory.java package com.example.agent.core.memory.impl; import com.example.agent.core.memory.Memory; import org.springframework.stereotype.Component; import java.util.ArrayList; import java.util.List; import java.util.concurrent.CopyOnWriteArrayList; Component public class SimpleConversationMemory implements Memory { private final ListMessage messages new CopyOnWriteArrayList(); private static final int MAX_HISTORY 20; // 防止内存无限增长 Override public synchronized void addMessage(String role, String content) { messages.add(new Message(role, content)); // 限制历史记录长度 if (messages.size() MAX_HISTORY) { messages.remove(0); } } Override public ListMessage getRecentMessages(int limit) { int fromIndex Math.max(0, messages.size() - limit); return new ArrayList(messages.subList(fromIndex, messages.size())); } Override public synchronized void clear() { messages.clear(); } // 内部类 Message 实现... }3.4 组件四Agent核心引擎AgentEngine—— 大脑与调度中心这是最核心的部分它负责接收用户输入。结合记忆构造发送给LLM的提示词Prompt。调用LLM API并获得响应。解析LLM的响应判断是需要调用工具还是直接回复。执行工具并将结果再次反馈给LLM形成循环ReAct模式直到任务完成。// 文件路径src/main/java/com/example/agent/core/engine/AgentEngine.java package com.example.agent.core.engine; import com.example.agent.core.tool.Tool; import com.example.agent.core.tool.ToolManager; import com.example.agent.core.memory.Memory; import com.theokanning.openai.completion.chat.*; import com.theokanning.openai.service.OpenAiService; import lombok.extern.slf4j.Slf4j; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Component; import javax.annotation.PostConstruct; import java.time.Duration; import java.util.*; import java.util.stream.Collectors; Slf4j Component public class AgentEngine { private OpenAiService openAiService; private final ToolManager toolManager; private final Memory memory; Value(${openai.api.key}) private String apiKey; Value(${openai.model:gpt-3.5-turbo}) private String model; Value(${openai.api.timeout:60}) private int timeoutSeconds; // 系统提示词定义Agent的角色和能力 private static final String SYSTEM_PROMPT_TEMPLATE 你是一个专业的助手可以调用工具来帮助用户解决问题。 你可以使用的工具如下 %s 当用户提出需要计算、查询或操作时你应该思考是否需要使用工具。 如果你决定使用工具请严格按照以下JSON格式回复且只回复这个JSON不要有任何其他文字 {action: tool_call, tool_name: 工具名称, arguments: {参数1: 值1, 参数2: 值2}} 如果不需要使用工具或者工具执行后得到了最终答案请直接以自然语言回复用户。 注意arguments必须是一个有效的JSON对象符合对应工具的参数要求。 ; public AgentEngine(ToolManager toolManager, Memory memory) { this.toolManager toolManager; this.memory memory; } PostConstruct public void init() { if (apiKey null || apiKey.isBlank()) { throw new IllegalArgumentException(OpenAI API Key 未配置请在application.properties中设置openai.api.key); } this.openAiService new OpenAiService(apiKey, Duration.ofSeconds(timeoutSeconds)); log.info(AgentEngine 初始化完成使用模型: {}, model); } /** * 处理用户输入的核心方法。 * param userInput 用户输入 * return Agent的最终回复 */ public String process(String userInput) { // 1. 将用户输入加入记忆 memory.addMessage(user, userInput); log.info(处理用户输入: {}, userInput); // 2. 准备对话历史和新消息 ListChatMessage messages prepareChatMessages(); // 3. 与LLM交互可能涉及多轮工具调用简化示例这里只做单轮或有限轮 int maxIterations 5; // 防止无限循环 for (int i 0; i maxIterations; i) { ChatCompletionRequest request ChatCompletionRequest.builder() .model(model) .messages(messages) .temperature(0.2) // 低随机性保证工具调用格式稳定 .build(); ChatCompletionResult result openAiService.createChatCompletion(request); ChatMessage assistantMessage result.getChoices().get(0).getMessage(); String content assistantMessage.getContent().trim(); log.debug(LLM 原始回复: {}, content); // 4. 解析LLM回复 ParsedResponse parsedResponse parseResponse(content); if (parsedResponse.isToolCall()) { // 5. 执行工具调用 String toolResult executeTool(parsedResponse.getToolName(), parsedResponse.getArguments()); log.info(工具 {} 执行结果: {}, parsedResponse.getToolName(), toolResult); // 将工具执行结果作为一条“系统”或“工具”消息加入历史供下一轮LLM参考 memory.addMessage(system, 工具 parsedResponse.getToolName() 返回结果: toolResult); // 重新准备消息进入下一轮循环 messages prepareChatMessages(); } else { // 6. 得到最终回复 memory.addMessage(assistant, content); return content; } } return 抱歉在处理您的问题时经过多轮尝试仍未完成。请简化您的问题或稍后再试。; } private ListChatMessage prepareChatMessages() { ListChatMessage messages new ArrayList(); // 系统提示词动态注入工具描述 String toolsDescription buildToolsDescription(); String systemPrompt String.format(SYSTEM_PROMPT_TEMPLATE, toolsDescription); messages.add(new ChatMessage(ChatMessageRole.SYSTEM.value(), systemPrompt)); // 从记忆中添加最近的对话历史例如最近10轮 ListMemory.Message history memory.getRecentMessages(10); for (Memory.Message msg : history) { messages.add(new ChatMessage(msg.getRole(), msg.getContent())); } return messages; } private String buildToolsDescription() { return toolManager.getAllTools().values().stream() .map(tool - String.format(- 工具名称: %s\n 描述: %s\n 参数格式: %s, tool.getName(), tool.getDescription(), tool.getParametersSchema().toString())) .collect(Collectors.joining(\n\n)); } private ParsedResponse parseResponse(String content) { // 简单解析JSON判断是否为工具调用。生产环境应用更健壮的JSON解析库。 try { if (content.startsWith({) content.contains(\action\:\tool_call\)) { // 使用Jackson解析此处简化实际需完整解析 com.fasterxml.jackson.databind.ObjectMapper mapper new com.fasterxml.jackson.databind.ObjectMapper(); Map?, ? map mapper.readValue(content, Map.class); if (tool_call.equals(map.get(action))) { String toolName (String) map.get(tool_name); String arguments mapper.writeValueAsString(map.get(arguments)); return ParsedResponse.toolCall(toolName, arguments); } } } catch (Exception e) { log.warn(解析LLM响应失败视为自然语言回复。内容: {}, content, e); } return ParsedResponse.textResponse(content); } private String executeTool(String toolName, String arguments) { Tool tool toolManager.getTool(toolName); if (tool null) { return 错误未知的工具 toolName 。; } try { return tool.execute(arguments); } catch (Exception e) { log.error(执行工具 {} 时发生异常参数: {}, toolName, arguments, e); return 工具执行过程中发生错误: e.getMessage(); } } // 内部类用于封装解析结果 lombok.Data private static class ParsedResponse { private final boolean toolCall; private final String toolName; private final String arguments; private final String text; static ParsedResponse toolCall(String toolName, String arguments) { return new ParsedResponse(true, toolName, arguments, null); } static ParsedResponse textResponse(String text) { return new ParsedResponse(false, null, null, text); } } }4. 完整实战构建一个数学助手Agent现在我们将所有组件串联起来创建一个简单的Web接口让用户能与我们的Agent交互。4.1 创建Web控制器Controller// 文件路径src/main/java/com/example/agent/controller/AgentController.java package com.example.agent.controller; import com.example.agent.core.engine.AgentEngine; import lombok.RequiredArgsConstructor; import org.springframework.web.bind.annotation.*; RestController RequestMapping(/api/agent) RequiredArgsConstructor public class AgentController { private final AgentEngine agentEngine; PostMapping(/chat) public String chat(RequestBody ChatRequest request) { if (request.getMessage() null || request.getMessage().trim().isEmpty()) { return 请输入有效消息。; } return agentEngine.process(request.getMessage()); } PostMapping(/reset) public String reset() { // 这里需要注入Memory Bean来清空为了简化我们假设AgentEngine提供了reset方法 // 实际应在AgentEngine中暴露memory.clear() return 对话历史已重置。; } lombok.Data public static class ChatRequest { private String message; } }4.2 应用配置文件# 文件路径src/main/resources/application.properties # OpenAI 配置 (务必替换成你自己的Key并确保网络可访问) openai.api.keysk-your-openai-api-key-here openai.modelgpt-3.5-turbo openai.api.timeout30 # 服务器端口 server.port8080 # 日志级别 logging.level.com.example.agentDEBUG4.3 运行与测试启动应用运行AgentDemoApplication的main方法。使用工具测试使用curl或 Postman 发送 POST 请求。curl -X POST http://localhost:8080/api/agent/chat \ -H Content-Type: application/json \ -d {message: 请计算一下 125 乘以 38 等于多少}预期过程Agent收到问题。LLM判断需要调用calculator工具。回复JSON{action: tool_call, tool_name: calculator, arguments: {operation: multiply, num1: 125, num2: 38}}AgentEngine解析并执行计算器工具。工具返回结果“计算结果4750.00”。该结果被加入记忆再次调用LLM。LLM根据工具结果组织最终回复“125乘以38等于4750。”你将收到这个最终回复。多轮对话测试# 第一轮 curl ... -d {message: 你好} # 回复你好有什么可以帮你的吗 # 第二轮 curl ... -d {message: 上面的结果再加上100} # 回复你指的是哪个结果呢如果你指的是之前的计算结果4750那么4750加上100等于4850。这展示了记忆模块的作用Agent能引用上下文。5. 常见问题与深度排查指南在开发和生产运行Agent时你会遇到各种问题。以下是一些典型问题及解决思路。5.1 LLM相关问题问题现象可能原因排查步骤与解决方案调用API超时或网络错误1. 网络不通或代理问题。2. API Key无效或额度不足。3. 服务端响应慢。1. 检查网络连接使用curl或ping测试API端点可达性。2. 在OpenAI Dashboard检查Key状态和余额。3. 增加openai.api.timeout配置并考虑实现重试机制。LLM回复格式不符合预期无法解析工具调用1. 系统提示词SYSTEM_PROMPT不够清晰。2. 温度temperature参数过高导致输出随机。3. 模型能力不足。1.优化提示词工程明确指令提供更严格的输出格式示例Few-Shot Prompting。2.降低temperature如设为0.1使输出更确定。3. 升级到更强大的模型如gpt-4或使用OpenAI的function calling特性替代自行解析。回复内容包含无关信息或“思考过程”提示词未要求LLM“只回复JSON”或“不要有其他文字”。在系统提示词中强调输出格式例如“你必须只输出指定的JSON格式不要输出任何其他解释、道歉或标记。”5.2 工具执行与集成问题问题现象可能原因排查步骤与解决方案ToolManager找不到工具1. Tool类未加Component注解。2. 工具名称getName()与LLM调用的名称不匹配。1. 检查Spring Boot启动日志确认工具Bean已被加载和注册。2. 在buildToolsDescription()方法中打印所有注册的工具列表进行核对。工具执行参数解析失败1. LLM生成的参数JSON格式错误。2. 参数类型或值与工具期望的不符。1. 在parseResponse和工具execute方法中增加更详细的日志和异常捕获。2. 在提示词中提供更精确的参数Schema示例甚至使用JSON Schema标准描述。工具执行慢或阻塞主线程工具涉及网络IO、复杂计算或数据库查询。将工具执行异步化。使用Async注解或CompletableFuture.supplyAsync()避免阻塞Agent的响应循环。5.3 内存与性能问题问题现象可能原因排查思路内存占用持续增长1. 记忆Memory未做容量限制。2. 聊天消息或工具结果过大。3. 内存泄漏如未正确管理LLM客户端连接。1. 像SimpleConversationMemory一样实现历史消息上限。2. 对长文本进行摘要Summarization后再存入记忆。3. 使用Profiling工具如VisualVM, JProfiler分析堆内存。Agent响应越来越慢1. 记忆历史过长导致每次请求的Prompt巨大LLM处理变慢且Token费用高。2. 工具调用链路过长ReAct循环次数多。1.实现记忆窗口或摘要只保留最近N轮对话或将更早的对话总结成一段摘要。2.设置最大迭代次数如代码中的maxIterations防止死循环。3.优化提示词引导LLM更高效地规划减少不必要的工具调用。5.4 生产环境部署问题API Key管理绝对不要将API Key硬编码在代码或配置文件中提交到代码仓库。使用环境变量、配置中心如Apollo或云厂商的密钥管理服务。容错与降级LLM服务可能不稳定。必须为LLM API调用和工具调用添加重试、熔断如Resilience4j和超时控制。监控与可观测性记录关键指标LLM调用耗时、Token使用量、工具调用成功率、Agent会话时长。集成Micrometer和Prometheus/Grafana。安全性工具权限控制不是所有用户都能调用所有工具。需要实现基于用户/角色的工具访问权限校验。输入输出过滤对用户输入和LLM输出进行必要的安全检查防止Prompt注入攻击。敏感信息确保工具不会泄露或处理未经授权的敏感数据。6. 进阶架构与最佳实践当你的Agent从Demo走向生产需要考虑更复杂的架构和工程实践。6.1 架构演进从单体到分布式工具服务化将复杂的工具拆分为独立的微服务。Agent核心通过RPC或消息队列调用这些服务实现解耦和独立扩缩容。专用记忆存储使用Redis存储短期会话记忆使用数据库如PostgreSQL存储长期记忆和知识库。这支持多实例部署和会话持久化。任务队列与异步处理对于耗时的Agent任务如生成报告不应阻塞HTTP请求。可以将用户请求放入消息队列如RabbitMQ, Kafka由后台Worker进程消费并处理通过WebSocket或轮询通知用户结果。Agent池与负载均衡高并发下可以部署多个Agent实例通过网关进行负载均衡。需要解决有状态如记忆的问题通常将会话ID与特定的Agent实例或共享存储关联。6.2 提示词工程优化提示词的质量直接决定Agent的性能。结构化输出强烈建议使用OpenAI的Function Calling或JSON Mode。这能保证LLM输出结构化的数据彻底解决解析问题。我们的示例中手动解析JSON是简化方案。少样本示例Few-Shot在系统提示词中提供几个“用户输入-理想输出”的配对示例能极大地提升LLM遵循指令的能力。思维链Chain-of-Thought对于复杂问题在提示词中鼓励LLM“逐步思考”可以提高其推理和工具调用的准确性。动态上下文管理根据对话长度和复杂度动态选择注入记忆的策略全量历史、最近N条、摘要等以平衡效果和Token成本。6.3 利用现有Java Agent框架当项目复杂度提升时可以考虑基于成熟的开源框架开发避免重复造轮子。LangChain4JJava版的LangChain提供了强大的Chain、Tool、Memory、Agent抽象和大量集成。这是目前Java生态中最活跃的Agent框架。Spring AISpring官方推出的AI应用开发框架提供了统一的API访问多种模型OpenAI, Azure OpenAI, Ollama等并集成了Prompt管理、向量数据库等能力与Spring Boot无缝集成。使用LangChain4J重构工具调用的优势// 示例使用LangChain4J定义工具 Tool(计算两个数字的和) public String addNumbers(P(第一个数字) double a, P(第二个数字) double b) { return String.valueOf(a b); } // LangChain4J会自动处理工具描述、JSON Schema生成以及与LLM的交互大大简化代码。6.4 测试策略Agent系统的测试更具挑战性因为涉及非确定性的LLM。单元测试隔离测试每个Tool的实现、Memory的操作、Response的解析逻辑。Mock掉LLM调用。集成测试使用一个固定的、简单的Mock LLM例如总是返回预定格式的工具调用来测试AgentEngine的完整流程。端到端测试针对关键用户旅程编写测试用例使用真实的LLM但可能是低成本模型如gpt-3.5-turbo进行测试主要验证功能是否贯通并对输出进行断言如是否包含某个关键词。评估Evaluation生产前需要一套评估体系来衡量Agent的质量例如任务完成率、工具调用准确率、用户满意度人工评估。这通常需要构建一个测试用例集和评估标准。从Java后端开发转向Agent智能体开发并非要抛弃原有的技术栈而是将Java在工程化、稳定性、系统集成方面的优势与AI的感知和决策能力相结合。这条路的核心在于理解Agent的架构范式感知-规划-执行循环并运用扎实的软件工程能力将其实现。本文带你从零构建了一个具备工具调用和记忆能力的Agent内核这只是一个起点。接下来你可以沿着这些方向深入集成更强大的框架深入研究LangChain4J或Spring AI利用其生态快速集成搜索引擎、数据库等工具。设计复杂的Agent工作流实现多个Agent协同Multi-Agent或设计支持复杂规划Planning的Agent。专注垂直领域将Agent能力与你的业务领域如金融、运维、客服深度结合打造真正创造价值的专家系统。Agent开发的世界刚刚开启充满了可能性。拿起你熟悉的Java工具开始构建属于你的智能体吧。在实践过程中多思考架构的扩展性、系统的稳定性和最终的用户价值这将是你在这一波技术浪潮中脱颖而出的关键。