尧图网站开发 
最近在尝试将大模型能力集成到企业应用中发现很多开发者卡在“如何让AI不只是聊天而是能按流程执行任务”这一步。Spring AI Alibaba Graph 提供了一种优雅的解决方案它允许你将复杂的业务逻辑编排成图Graph让AI Agent按图索骥自动完成多步骤任务。本文将以一个HR自动化AI Agent为例从零开始手把手带你搭建一个能自动处理员工请假、查询政策、生成报告的智能体。无论你是想快速上手Spring AI还是为面试准备AI Agent的实战项目这套包含20个核心技术点的完整方案都能让你少走弯路。1. 背景与核心概念为什么需要AI Agent在深入代码之前我们先理清几个关键概念这能帮你更好地理解我们正在构建什么。1.1 什么是AI Agent简单来说AI Agent智能体是一个能感知环境、自主决策并执行行动以实现目标的程序。它不同于简单的聊天机器人仅完成一轮问答。一个典型的AI Agent工作流程是接收目标用户说“我想请三天年假”。规划与决策Agent理解这是一个“请假”任务需要先查询年假余额、再检查审批流程、最后提交申请。执行与工具调用Agent依次调用“查询余额API”、“读取请假政策文档”、“调用HR系统提交接口”。观察与调整如果余额不足它会调整策略建议用户请事假或告知原因。输出结果最终给用户一个明确的答复“您的年假余额为2天不足3天。已为您提交2天年假1天事假的混合申请流程已启动。”核心区别聊天机器人是“问答机”AI Agent是“执行者”。1.2 Spring AI 与 Alibaba Graph 是什么Spring AISpring官方项目旨在简化Java应用中集成AI功能如OpenAI、Azure OpenAI、Ollama等的过程。它提供了统一的模板和客户端让你像操作数据库JdbcTemplate一样操作大模型。Spring AI Alibaba阿里云对Spring AI的扩展提供了对阿里云百炼、灵积等平台模型的深度集成以及一些特有的高级功能。Graph这是Spring AI Alibaba及Spring AI核心中用于构建AI Agent的核心模块。它允许你将一个复杂的任务分解成多个步骤节点并定义步骤之间的执行顺序和条件跳转边形成一个“执行图”。AI模型LLM作为图中的决策大脑指挥整个流程。1.3 HR自动化AI Agent的应用场景我们本次构建的Agent将演示以下能力这些能力可以轻松迁移到客服、运维、财务等场景意图识别判断用户是想请假、查政策还是问薪资。信息抽取从用户自然语言中提取结构化数据如请假类型、起止时间。条件路由根据业务规则如余额、职级决定流程走向。工具调用执行真实的业务操作如查询数据库、调用REST API、生成文件。记忆与上下文在多轮对话中记住关键信息如员工ID。2. 环境准备与版本说明在开始编码前请确保你的开发环境已就绪。基础环境要求操作系统Windows 10/11, macOS, 或 Linux (Ubuntu 20.04)JavaJDK 17 或更高版本 (本文使用 JDK 17)构建工具Apache Maven 3.6 或 Gradle 7.xIDEIntelliJ IDEA (推荐), VS Code, 或 Eclipse核心依赖版本这是项目成功构建和运行的关键。在pom.xml中我们主要依赖以下库!-- Spring Boot 基础 -- parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version !-- 确保使用3.x版本 -- relativePath/ /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Spring AI 核心 (必选) -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-core/artifactId version0.8.1/version !-- 请查看官方更新使用最新稳定版 -- /dependency !-- Spring AI Alibaba Graph (核心) -- dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-graph/artifactId version2023.0.1.0/version !-- 版本可能与Spring AI核心有对应关系请查阅官方文档 -- /dependency !-- 连接器这里以阿里云灵积为例 -- dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-qwen/artifactId version2023.0.1.0/version /dependency !-- 工具类 -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependencies重要提示Spring AI 及其生态版本迭代较快上述版本号在您实践时可能已有更新。最可靠的方式是访问 Spring AI 官方文档 和 阿里云Spring AI 仓库 获取最新依赖配置。大模型接入准备本文示例使用阿里云通义千问Qwen你需要前往 阿里云百炼 或 灵积平台 注册账号。创建API-KEY。通常可以在“模型服务”-“API-KEY管理”中找到。确保账号有足够的额度。3. 核心概念与Graph模型拆解理解Graph的组成是构建Agent的关键。一个Graph由以下几种核心节点类型构成3.1 节点Node类型工具节点ToolNode封装一个可执行的方法如查询数据库、调用外部API。Agent通过调用工具来影响外部世界。LLM节点LLMNode与大模型交互的节点。它可以处理用户输入、做出决策、生成文本。通常作为流程的“大脑”。条件节点ConditionalNode根据上一步的执行结果布尔值决定下一步走向哪个分支。输入/输出节点Input/OutputNode定义Graph的入口参数和最终返回值。3.2 边Edge与流程控制边连接节点定义了执行流。除了简单的顺序流还有条件边与ConditionalNode配合实现if-else逻辑。所有边等待所有前置节点完成后再执行下一个节点并行概念的基础。3.3 状态State与上下文Graph在执行过程中会维护一个State对象它是一个MapString, Object。每个节点都可以从State中读取输入并将输出写入State供后续节点使用。这是节点间传递数据的桥梁。4. 实战构建HR自动化AI Agent现在我们开始构建核心功能。项目结构如下src/main/java/com/example/hragent/ ├── HrAgentApplication.java // 启动类 ├── config/ │ ├── GraphConfig.java // Graph定义配置 │ └── QwenConfig.java // 大模型客户端配置 ├── node/ │ ├── tool/ │ │ ├── LeaveBalanceTool.java // 工具查询假期余额 │ │ ├── PolicyQueryTool.java // 工具查询政策 │ │ └── SubmitRequestTool.java // 工具提交申请 │ └── llm/ │ └── IntentClassificationNode.java // LLM节点意图分类 ├── controller/ │ └── AgentController.java // 提供HTTP接口 └── dto/ ├── AgentRequest.java // 请求体 └── AgentResponse.java // 响应体4.1 第一步配置大模型客户端首先配置通义千问的客户端。将你的API-KEY和模型信息放在application.yml中。# application.yml spring: application: name: hr-ai-agent # 阿里云灵积配置 alibaba: ai: qwen: api-key: ${QWEN_API_KEY:your-api-key-here} # 建议使用环境变量 chat: options: model: qwen-max # 或 qwen-plus, qwen-turbo等 temperature: 0.2 # 较低的温度使输出更确定然后创建一个配置类来初始化ChatClient。// 文件路径src/main/java/com/example/hragent/config/QwenConfig.java package com.example.hragent.config; import org.springframework.ai.alibaba.qwen.AlibabaQwenChatModel; import org.springframework.ai.alibaba.qwen.api.AlibabaQwenApi; import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class QwenConfig { Value(${alibaba.ai.qwen.api-key}) private String apiKey; Bean public AlibabaQwenApi alibabaQwenApi() { // 基础URL通常是固定的除非你用自定义端点 return new AlibabaQwenApi(apiKey); } Bean public AlibabaQwenChatModel chatModel(AlibabaQwenApi api) { return new AlibabaQwenChatModel(api); } }4.2 第二步定义工具Tools工具是Agent的“手”和“脚”。每个工具都是一个普通的Spring Bean方法上标注Tool注解。工具1查询假期余额工具// 文件路径src/main/java/com/example/hragent/node/tool/LeaveBalanceTool.java package com.example.hragent.node.tool; import org.springframework.ai.alibaba.qwen.api.Tool; import org.springframework.stereotype.Component; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; Component public class LeaveBalanceTool { // 模拟一个员工假期余额表 (员工ID - {年假 病假 调休}) private final MapString, MapString, Integer balanceMockDB new ConcurrentHashMap(); public LeaveBalanceTool() { // 初始化一些测试数据 MapString, Integer emp1 Map.of(annual, 10, sick, 5, compensatory, 8); MapString, Integer emp2 Map.of(annual, 5, sick, 3, compensatory, 2); balanceMockDB.put(EMP001, emp1); balanceMockDB.put(EMP002, emp2); } Tool(description 根据员工ID和假期类型查询该员工的剩余假期天数。) public int queryLeaveBalance( Tool.Param(description 员工唯一标识符例如 EMP001) String employeeId, Tool.Param(description 假期类型如 annual(年假), sick(病假), compensatory(调休)) String leaveType) { System.out.println([Tool调用] queryLeaveBalance: employeeId employeeId , leaveType leaveType); MapString, Integer balances balanceMockDB.get(employeeId); if (balances null || !balances.containsKey(leaveType)) { return 0; // 或抛出异常 } return balances.get(leaveType); } }工具2查询请假政策工具// 文件路径src/main/java/com/example/hragent/node/tool/PolicyQueryTool.java package com.example.hragent.node.tool; import org.springframework.ai.alibaba.qwen.api.Tool; import org.springframework.stereotype.Component; Component public class PolicyQueryTool { Tool(description 根据政策关键词查询公司的请假相关政策条款。) public String queryPolicy( Tool.Param(description 政策关键词如 年假申请流程、病假证明要求、婚假天数) String keyword) { System.out.println([Tool调用] queryPolicy: keyword keyword); // 模拟从知识库或文档中查询 MapString, String policyDB Map.of( 年假申请流程, 员工需提前3个工作日于HR系统中提交申请经直属领导和部门总监审批。, 病假证明要求, 请假超过3天需提供二级甲等以上医院开具的病假证明。, 婚假天数, 符合国家婚姻法规定的员工可享受15天婚假需在登记后一年内使用。 ); return policyDB.getOrDefault(keyword, 未找到相关政策条款。); } }工具3提交请假申请工具// 文件路径src/main/java/com/example/hragent/node/tool/SubmitRequestTool.java package com.example.hragent.node.tool; import org.springframework.ai.alibaba.qwen.api.Tool; import org.springframework.stereotype.Component; import java.time.LocalDateTime; Component public class SubmitRequestTool { Tool(description 向HR系统提交一个请假申请并返回申请单号。) public String submitLeaveRequest( Tool.Param(description 员工ID) String employeeId, Tool.Param(description 请假类型) String leaveType, Tool.Param(description 开始时间 (yyyy-MM-dd)) String startDate, Tool.Param(description 结束时间 (yyyy-MM-dd)) String endDate, Tool.Param(description 请假事由) String reason) { System.out.println([Tool调用] submitLeaveRequest: employeeId 申请 leaveType 从 startDate 到 endDate); // 模拟调用HR系统接口 String requestId REQ_ System.currentTimeMillis(); // 这里可以集成真实的HTTP客户端调用 System.out.println(模拟申请已提交单号: requestId); return requestId; } }4.3 第三步构建Graph执行图这是最核心的部分。我们将使用Graph.BuilderAPI来定义HR Agent的完整流程。// 文件路径src/main/java/com/example/hragent/config/GraphConfig.java package com.example.hragent.config; import com.example.hragent.node.llm.IntentClassificationNode; import com.example.hragent.node.tool.LeaveBalanceTool; import com.example.hragent.node.tool.PolicyQueryTool; import com.example.hragent.node.tool.SubmitRequestTool; import org.springframework.ai.alibaba.qwen.AlibabaQwenChatModel; import org.springframework.ai.graph.Graph; import org.springframework.ai.graph.Node; import org.springframework.ai.graph.node.ToolNode; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import java.util.Map; Configuration public class GraphConfig { Bean public Graph hrAgentGraph( AlibabaQwenChatModel chatModel, LeaveBalanceTool leaveBalanceTool, PolicyQueryTool policyQueryTool, SubmitRequestTool submitRequestTool, IntentClassificationNode intentNode) { // 1. 定义节点 // 输入节点接收用户问题 NodeString inputNode Node.fromInput(input, 用户输入的原始问题); // LLM节点意图分类 (自定义节点见下一步) NodeMapString, Object intentClassificationNode intentNode.getNode(); // 工具节点查询余额 ToolNode queryBalanceNode new ToolNode(queryBalance, leaveBalanceTool, queryLeaveBalance); // 工具节点查询政策 ToolNode queryPolicyNode new ToolNode(queryPolicy, policyQueryTool, queryPolicy); // 工具节点提交申请 ToolNode submitRequestNode new ToolNode(submitRequest, submitRequestTool, submitLeaveRequest); // LLM节点生成最终回复 NodeString finalResponseNode Node.fromSupplier(finalResponse, state - { // 从状态中获取所有信息组装成最终回复 String intent (String) state.get(intent); String answer (String) state.get(answer); String requestId (String) state.get(requestId); StringBuilder response new StringBuilder(); response.append(【HR助手】\n); response.append(识别到您的意图是).append(intent).append(\n\n); if (leave_application.equals(intent) requestId ! null) { response.append(✅ 您的请假申请已成功提交\n); response.append(申请单号).append(requestId).append(\n); response.append(流程说明).append(answer); } else if (policy_query.equals(intent)) { response.append( 相关政策查询结果\n).append(answer); } else if (balance_query.equals(intent)) { response.append( 您的假期余额\n).append(answer); } else { response.append( 我暂时无法处理您的请求。).append(answer); } return response.toString(); }); // 输出节点 NodeString outputNode Node.fromOutput(output, 最终给用户的回复); // 2. 构建图并连接节点 return Graph.builder() // 流程开始 .addNode(inputNode) .addNode(intentClassificationNode) .link(inputNode, intentClassificationNode) // 输入 - 意图识别 // 根据意图分支 .addNode(queryBalanceNode) .addNode(queryPolicyNode) .addNode(submitRequestNode) // 条件路由根据识别出的intent字段决定下一步 .addConditionalLink(intentClassificationNode, state - balance_query.equals(state.get(intent)), queryBalanceNode) .addConditionalLink(intentClassificationNode, state - policy_query.equals(state.get(intent)), queryPolicyNode) .addConditionalLink(intentClassificationNode, state - leave_application.equals(state.get(intent)), submitRequestNode) // 各分支汇聚到最终回复节点 .link(queryBalanceNode, finalResponseNode) .link(queryPolicyNode, finalResponseNode) .link(submitRequestNode, finalResponseNode) // 结束 .link(finalResponseNode, outputNode) .build(); } }4.4 第四步实现自定义LLM节点意图识别这个节点负责理解用户想干什么。它调用大模型并返回结构化的结果如意图、提取的参数。// 文件路径src/main/java/com/example/hragent/node/llm/IntentClassificationNode.java package com.example.hragent.node.llm; import org.springframework.ai.alibaba.qwen.AlibabaQwenChatModel; import org.springframework.ai.graph.Node; import org.springframework.ai.model.ModelOptionsUtils; import org.springframework.ai.parser.BeanOutputParser; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Component; import java.util.Map; Component public class IntentClassificationNode { Autowired private AlibabaQwenChatModel chatModel; public NodeMapString, Object getNode() { // 1. 定义我们希望LLM返回的结构 class IntentResult { public String intent; // 意图: balance_query, policy_query, leave_application, other public MapString, String entities; // 提取的实体如 employeeId, leaveType, keyword等 public String reasoning; // LLM的推理过程便于调试 } BeanOutputParserIntentResult parser new BeanOutputParser(IntentResult.class); // 2. 构建提示词Prompt String systemPrompt 你是一个专业的HR助手负责分析用户的请求意图并提取关键信息。 请严格按照以下JSON格式回复不要添加任何其他内容。 {format} 意图说明 - balance_query: 当用户询问假期余额时。 - policy_query: 当用户询问请假政策、流程、规定时。 - leave_application: 当用户明确表示要请假、申请休假时。 - other: 其他无法归类的请求。 实体字段说明 - 如果意图是balance_query请提取 employeeId (员工ID) 和 leaveType (假期类型如annual, sick)。 - 如果意图是policy_query请提取 keyword (政策关键词)。 - 如果意图是leave_application请提取 employeeId, leaveType, startDate, endDate, reason。 - 其他意图entities可以为空。 .replace({format}, parser.getFormat()); // 3. 创建并返回Node return Node.fromSupplier(intentClassification, state - { String userInput (String) state.get(input); if (userInput null) { throw new IllegalArgumentException(输入不能为空); } String prompt systemPrompt \n\n用户请求 userInput; String llmResponse chatModel.call(prompt); // 调用大模型 // 4. 解析LLM的回复 IntentResult result; try { result parser.parse(llmResponse); } catch (Exception e) { // 解析失败返回默认结果 result new IntentResult(); result.intent other; result.reasoning LLM回复格式解析失败: e.getMessage(); } // 5. 将结果放入State供后续节点使用 // 这里将对象转为Map方便Graph中条件判断和工具节点参数绑定 // 注意Graph State中存储的应该是简单类型或Map/List复杂对象可能需要序列化 MapString, Object resultMap ModelOptionsUtils.toMap(result); // 将提取的实体也平铺到State中方便工具节点直接通过参数名获取 if (result.entities ! null) { resultMap.putAll(result.entities); } return resultMap; }); } }4.5 第五步创建控制器与启动应用最后我们提供一个HTTP接口来触发这个Agent。// 文件路径src/main/java/com/example/hragent/controller/AgentController.java package com.example.hragent.controller; import org.springframework.ai.graph.Graph; import org.springframework.ai.graph.GraphResponse; import org.springframework.beans.factory.annotation.Qualifier; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RestController; import java.util.Map; RestController public class AgentController { private final Graph hrAgentGraph; // 通过Qualifier指定注入我们定义的Graph Bean public AgentController(Qualifier(hrAgentGraph) Graph hrAgentGraph) { this.hrAgentGraph hrAgentGraph; } PostMapping(/ask) public MapString, Object askHrAgent(RequestBody MapString, String request) { String question request.get(question); String employeeId request.get(employeeId); // 可以从会话或登录信息中获取 // 1. 准备初始状态 MapString, Object initialState Map.of( input, question, employeeId, employeeId ! null ? employeeId : EMP001 // 示例默认ID ); // 2. 执行Graph GraphResponse response hrAgentGraph.call(initialState); // 3. 获取输出 String finalOutput (String) response.getOutput().get(output); MapString, Object executionSteps response.getSteps(); // 可以返回执行步骤用于调试 // 4. 返回结果 return Map.of( answer, finalOutput, steps, executionSteps.keySet(), // 展示了哪些节点被执行了 success, true ); } }// 文件路径src/main/java/com/example/hragent/HrAgentApplication.java package com.example.hragent; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class HrAgentApplication { public static void main(String[] args) { SpringApplication.run(HrAgentApplication.class, args); System.out.println(HR AI Agent 服务已启动); } }4.6 运行与验证启动应用运行HrAgentApplication的main方法。使用工具测试使用Postman、curl或任何HTTP客户端发送POST请求。curl -X POST http://localhost:8080/ask \ -H Content-Type: application/json \ -d { question: 我的年假还剩多少天, employeeId: EMP001 }预期结果你会收到一个JSON响应其中answer字段包含类似“【HR助手】...您的年假余额10天”的内容。同时控制台会打印工具调用的日志。测试其他意图question: 请问婚假有多少天question: 我想从下周一请三天年假出去旅游。5. 20个核心技术点与面试要点解析通过以上实战我们覆盖了以下关键知识点掌握这些足以应对大部分AI Agent相关的面试和开发场景Spring AI 核心概念ChatClient,ChatModel,Prompt,Message。Alibaba Graph 核心组件Graph,Node,ToolNode,ConditionalNode。工具定义与注册Tool注解的使用参数描述的重要性。Graph构建APIGraph.builder(),addNode(),link(),addConditionalLink()。状态State管理节点间如何通过MapString, Object传递数据。条件路由使用addConditionalLink实现if-else逻辑。自定义节点如何包装LLM调用或复杂业务逻辑为一个Node。输出解析使用BeanOutputParser让LLM返回结构化数据。提示词工程设计System Prompt引导LLM完成特定任务意图识别、信息抽取。大模型集成配置阿里云Qwen客户端的配置与API-KEY管理。执行流程可视化通过GraphResponse.getSteps()调试执行路径。异常处理在节点中处理LLM调用失败、解析失败等异常。并行执行Graph支持addAllLink实现并行节点本文未展开。循环与递归通过条件节点和状态控制可以实现简单循环如重试。与Spring生态集成工具节点本身就是Spring Bean可轻松注入Repository,RestTemplate等。Agent的输入/输出设计如何设计Controller接口与前端交互。上下文管理如何在多轮对话中保持State需要额外设计会话存储。Token消耗与优化在ToolNode中执行实际调用减少不必要的LLM交互以节省Token。测试策略如何对单个Node和整个Graph进行单元测试和集成测试。生产部署考量配置管理、监控、日志、Graph定义的版本管理。6. 常见问题与排查思路在开发过程中你可能会遇到以下问题问题现象可能原因排查思路与解决方案启动报错No qualifying bean of type Graph1.GraphConfig中未定义Bean。2.Qualifier名称不匹配。3. 依赖版本冲突。1. 检查GraphConfig类是否有Configuration和Bean注解。2. 确认Controller中Qualifier(“hrAgentGraph”)与Bean方法名一致。3. 运行mvn dependency:tree检查Spring AI相关依赖是否存在多个版本。调用接口返回错误提示无法识别意图1. LLM API-KEY无效或额度不足。2. 模型名称配置错误。3. Prompt设计不佳LLM未按格式回复。1. 检查application.yml中的api-key建议用环境变量QWEN_API_KEY。2. 确认模型名称qwen-max等在当前区域可用。3. 在IntentClassificationNode中打印llmResponse查看原始回复优化Prompt。工具Tool未被调用1. 意图识别结果intent字段值不符合条件边的判断。2. 工具节点参数无法从State中获取。1. 在IntentClassificationNode结束后打印State确认intent值是balance_query等预期值。2. 确保工具方法参数名如employeeId与State中存储的键名一致。Graph会尝试按名称自动绑定。Graph执行卡住或无输出1. 图中存在环状依赖或死循环。2. 某个节点抛出未处理的异常。3. 未正确定义OutputNode。1. 检查Graph的连接逻辑确保是DAG有向无环图。2. 在每个节点中加入日志或异常捕获。3. 确保最终有一个节点连接到标记为OutputNode的节点。性能问题响应慢1. LLM调用耗时。2. 工具调用如网络IO慢。3. Graph串行步骤过多。1. 考虑使用更快的模型如qwen-turbo或流式响应。2. 对工具调用设置超时、使用缓存。3. 分析流程将无依赖的节点改为并行执行addAllLink。7. 最佳实践与进阶建议要将这个Demo转化为生产可用的系统还需要考虑以下几点提示词工程优化少样本学习在System Prompt中提供几个例子Few-Shot能极大提高意图识别和信息抽取的准确性。结构化输出约束使用BeanOutputParser或JsonOutputParser严格约束输出格式这是Agent稳定性的关键。分步思考对于复杂任务可以设计多个LLM节点让Agent先“思考”再“行动”。状态管理与会话当前的State是单次请求有效的。要实现多轮对话需要引入Session概念将每次的State变化持久化如存入Redis并在下次请求时恢复。可以在State中维护一个conversationHistory列表存储对话记录并在每次调用LLM时将其作为上下文传入。工具设计的健壮性参数校验在工具方法内部对输入参数进行有效性校验。异常处理工具应抛出明确的业务异常并在Graph中通过ErrorHandler节点进行统一处理如告知用户“系统繁忙请稍后再试”。幂等性对于提交类工具如submitLeaveRequest要设计幂等逻辑防止重复提交。可观测性与监控日志记录详细记录每个节点的输入、输出、耗时特别是LLM的请求和响应注意脱敏API-KEY。链路追踪为每个用户请求生成唯一的traceId贯穿整个Graph执行过程便于问题排查。指标监控监控Graph的执行成功率、各节点平均耗时、Token消耗量、工具调用失败率等。安全与权限输入过滤对用户输入进行必要的清洗防止Prompt注入攻击。工具权限在调用工具前根据当前用户身份从State中获取校验其是否有权限执行该操作。例如queryLeaveBalance工具只能查询自己的余额。输出审查对LLM生成的最终回复进行内容安全审核。配置化与动态Graph对于复杂的业务硬编码Graph可能难以维护。可以考虑将Graph的结构节点、边配置在数据库或配置中心运行时动态构建。Spring AI的GraphAPI支持以编程方式灵活构建为动态化提供了基础。构建一个成熟的企业级AI Agent是一个系统工程但通过Spring AI Alibaba Graph我们获得了强大的编排能力和与Spring生态的无缝集成。从这个小而美的HR自动化案例出发你可以将其模式复制到智能客服、运维排障、数据查询等任何需要多步骤、有条件判断的自动化场景中。 
最近在尝试将大模型能力集成到企业应用中发现很多开发者卡在“如何让AI不只是聊天而是能按流程执行任务”这一步。Spring AI Alibaba Graph 提供了一种优雅的解决方案它允许你将复杂的业务逻辑编排成图Graph让AI Agent按图索骥自动完成多步骤任务。本文将以一个HR自动化AI Agent为例从零开始手把手带你搭建一个能自动处理员工请假、查询政策、生成报告的智能体。无论你是想快速上手Spring AI还是为面试准备AI Agent的实战项目这套包含20个核心技术点的完整方案都能让你少走弯路。1. 背景与核心概念为什么需要AI Agent在深入代码之前我们先理清几个关键概念这能帮你更好地理解我们正在构建什么。1.1 什么是AI Agent简单来说AI Agent智能体是一个能感知环境、自主决策并执行行动以实现目标的程序。它不同于简单的聊天机器人仅完成一轮问答。一个典型的AI Agent工作流程是接收目标用户说“我想请三天年假”。规划与决策Agent理解这是一个“请假”任务需要先查询年假余额、再检查审批流程、最后提交申请。执行与工具调用Agent依次调用“查询余额API”、“读取请假政策文档”、“调用HR系统提交接口”。观察与调整如果余额不足它会调整策略建议用户请事假或告知原因。输出结果最终给用户一个明确的答复“您的年假余额为2天不足3天。已为您提交2天年假1天事假的混合申请流程已启动。”核心区别聊天机器人是“问答机”AI Agent是“执行者”。1.2 Spring AI 与 Alibaba Graph 是什么Spring AISpring官方项目旨在简化Java应用中集成AI功能如OpenAI、Azure OpenAI、Ollama等的过程。它提供了统一的模板和客户端让你像操作数据库JdbcTemplate一样操作大模型。Spring AI Alibaba阿里云对Spring AI的扩展提供了对阿里云百炼、灵积等平台模型的深度集成以及一些特有的高级功能。Graph这是Spring AI Alibaba及Spring AI核心中用于构建AI Agent的核心模块。它允许你将一个复杂的任务分解成多个步骤节点并定义步骤之间的执行顺序和条件跳转边形成一个“执行图”。AI模型LLM作为图中的决策大脑指挥整个流程。1.3 HR自动化AI Agent的应用场景我们本次构建的Agent将演示以下能力这些能力可以轻松迁移到客服、运维、财务等场景意图识别判断用户是想请假、查政策还是问薪资。信息抽取从用户自然语言中提取结构化数据如请假类型、起止时间。条件路由根据业务规则如余额、职级决定流程走向。工具调用执行真实的业务操作如查询数据库、调用REST API、生成文件。记忆与上下文在多轮对话中记住关键信息如员工ID。2. 环境准备与版本说明在开始编码前请确保你的开发环境已就绪。基础环境要求操作系统Windows 10/11, macOS, 或 Linux (Ubuntu 20.04)JavaJDK 17 或更高版本 (本文使用 JDK 17)构建工具Apache Maven 3.6 或 Gradle 7.xIDEIntelliJ IDEA (推荐), VS Code, 或 Eclipse核心依赖版本这是项目成功构建和运行的关键。在pom.xml中我们主要依赖以下库!-- Spring Boot 基础 -- parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version !-- 确保使用3.x版本 -- relativePath/ /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency !-- Spring AI 核心 (必选) -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-core/artifactId version0.8.1/version !-- 请查看官方更新使用最新稳定版 -- /dependency !-- Spring AI Alibaba Graph (核心) -- dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-graph/artifactId version2023.0.1.0/version !-- 版本可能与Spring AI核心有对应关系请查阅官方文档 -- /dependency !-- 连接器这里以阿里云灵积为例 -- dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-qwen/artifactId version2023.0.1.0/version /dependency !-- 工具类 -- dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency /dependencies重要提示Spring AI 及其生态版本迭代较快上述版本号在您实践时可能已有更新。最可靠的方式是访问 Spring AI 官方文档 和 阿里云Spring AI 仓库 获取最新依赖配置。大模型接入准备本文示例使用阿里云通义千问Qwen你需要前往 阿里云百炼 或 灵积平台 注册账号。创建API-KEY。通常可以在“模型服务”-“API-KEY管理”中找到。确保账号有足够的额度。3. 核心概念与Graph模型拆解理解Graph的组成是构建Agent的关键。一个Graph由以下几种核心节点类型构成3.1 节点Node类型工具节点ToolNode封装一个可执行的方法如查询数据库、调用外部API。Agent通过调用工具来影响外部世界。LLM节点LLMNode与大模型交互的节点。它可以处理用户输入、做出决策、生成文本。通常作为流程的“大脑”。条件节点ConditionalNode根据上一步的执行结果布尔值决定下一步走向哪个分支。输入/输出节点Input/OutputNode定义Graph的入口参数和最终返回值。3.2 边Edge与流程控制边连接节点定义了执行流。除了简单的顺序流还有条件边与ConditionalNode配合实现if-else逻辑。所有边等待所有前置节点完成后再执行下一个节点并行概念的基础。3.3 状态State与上下文Graph在执行过程中会维护一个State对象它是一个MapString, Object。每个节点都可以从State中读取输入并将输出写入State供后续节点使用。这是节点间传递数据的桥梁。4. 实战构建HR自动化AI Agent现在我们开始构建核心功能。项目结构如下src/main/java/com/example/hragent/ ├── HrAgentApplication.java // 启动类 ├── config/ │ ├── GraphConfig.java // Graph定义配置 │ └── QwenConfig.java // 大模型客户端配置 ├── node/ │ ├── tool/ │ │ ├── LeaveBalanceTool.java // 工具查询假期余额 │ │ ├── PolicyQueryTool.java // 工具查询政策 │ │ └── SubmitRequestTool.java // 工具提交申请 │ └── llm/ │ └── IntentClassificationNode.java // LLM节点意图分类 ├── controller/ │ └── AgentController.java // 提供HTTP接口 └── dto/ ├── AgentRequest.java // 请求体 └── AgentResponse.java // 响应体4.1 第一步配置大模型客户端首先配置通义千问的客户端。将你的API-KEY和模型信息放在application.yml中。# application.yml spring: application: name: hr-ai-agent # 阿里云灵积配置 alibaba: ai: qwen: api-key: ${QWEN_API_KEY:your-api-key-here} # 建议使用环境变量 chat: options: model: qwen-max # 或 qwen-plus, qwen-turbo等 temperature: 0.2 # 较低的温度使输出更确定然后创建一个配置类来初始化ChatClient。// 文件路径src/main/java/com/example/hragent/config/QwenConfig.java package com.example.hragent.config; import org.springframework.ai.alibaba.qwen.AlibabaQwenChatModel; import org.springframework.ai.alibaba.qwen.api.AlibabaQwenApi; import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class QwenConfig { Value(${alibaba.ai.qwen.api-key}) private String apiKey; Bean public AlibabaQwenApi alibabaQwenApi() { // 基础URL通常是固定的除非你用自定义端点 return new AlibabaQwenApi(apiKey); } Bean public AlibabaQwenChatModel chatModel(AlibabaQwenApi api) { return new AlibabaQwenChatModel(api); } }4.2 第二步定义工具Tools工具是Agent的“手”和“脚”。每个工具都是一个普通的Spring Bean方法上标注Tool注解。工具1查询假期余额工具// 文件路径src/main/java/com/example/hragent/node/tool/LeaveBalanceTool.java package com.example.hragent.node.tool; import org.springframework.ai.alibaba.qwen.api.Tool; import org.springframework.stereotype.Component; import java.util.Map; import java.util.concurrent.ConcurrentHashMap; Component public class LeaveBalanceTool { // 模拟一个员工假期余额表 (员工ID - {年假 病假 调休}) private final MapString, MapString, Integer balanceMockDB new ConcurrentHashMap(); public LeaveBalanceTool() { // 初始化一些测试数据 MapString, Integer emp1 Map.of(annual, 10, sick, 5, compensatory, 8); MapString, Integer emp2 Map.of(annual, 5, sick, 3, compensatory, 2); balanceMockDB.put(EMP001, emp1); balanceMockDB.put(EMP002, emp2); } Tool(description 根据员工ID和假期类型查询该员工的剩余假期天数。) public int queryLeaveBalance( Tool.Param(description 员工唯一标识符例如 EMP001) String employeeId, Tool.Param(description 假期类型如 annual(年假), sick(病假), compensatory(调休)) String leaveType) { System.out.println([Tool调用] queryLeaveBalance: employeeId employeeId , leaveType leaveType); MapString, Integer balances balanceMockDB.get(employeeId); if (balances null || !balances.containsKey(leaveType)) { return 0; // 或抛出异常 } return balances.get(leaveType); } }工具2查询请假政策工具// 文件路径src/main/java/com/example/hragent/node/tool/PolicyQueryTool.java package com.example.hragent.node.tool; import org.springframework.ai.alibaba.qwen.api.Tool; import org.springframework.stereotype.Component; Component public class PolicyQueryTool { Tool(description 根据政策关键词查询公司的请假相关政策条款。) public String queryPolicy( Tool.Param(description 政策关键词如 年假申请流程、病假证明要求、婚假天数) String keyword) { System.out.println([Tool调用] queryPolicy: keyword keyword); // 模拟从知识库或文档中查询 MapString, String policyDB Map.of( 年假申请流程, 员工需提前3个工作日于HR系统中提交申请经直属领导和部门总监审批。, 病假证明要求, 请假超过3天需提供二级甲等以上医院开具的病假证明。, 婚假天数, 符合国家婚姻法规定的员工可享受15天婚假需在登记后一年内使用。 ); return policyDB.getOrDefault(keyword, 未找到相关政策条款。); } }工具3提交请假申请工具// 文件路径src/main/java/com/example/hragent/node/tool/SubmitRequestTool.java package com.example.hragent.node.tool; import org.springframework.ai.alibaba.qwen.api.Tool; import org.springframework.stereotype.Component; import java.time.LocalDateTime; Component public class SubmitRequestTool { Tool(description 向HR系统提交一个请假申请并返回申请单号。) public String submitLeaveRequest( Tool.Param(description 员工ID) String employeeId, Tool.Param(description 请假类型) String leaveType, Tool.Param(description 开始时间 (yyyy-MM-dd)) String startDate, Tool.Param(description 结束时间 (yyyy-MM-dd)) String endDate, Tool.Param(description 请假事由) String reason) { System.out.println([Tool调用] submitLeaveRequest: employeeId 申请 leaveType 从 startDate 到 endDate); // 模拟调用HR系统接口 String requestId REQ_ System.currentTimeMillis(); // 这里可以集成真实的HTTP客户端调用 System.out.println(模拟申请已提交单号: requestId); return requestId; } }4.3 第三步构建Graph执行图这是最核心的部分。我们将使用Graph.BuilderAPI来定义HR Agent的完整流程。// 文件路径src/main/java/com/example/hragent/config/GraphConfig.java package com.example.hragent.config; import com.example.hragent.node.llm.IntentClassificationNode; import com.example.hragent.node.tool.LeaveBalanceTool; import com.example.hragent.node.tool.PolicyQueryTool; import com.example.hragent.node.tool.SubmitRequestTool; import org.springframework.ai.alibaba.qwen.AlibabaQwenChatModel; import org.springframework.ai.graph.Graph; import org.springframework.ai.graph.Node; import org.springframework.ai.graph.node.ToolNode; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import java.util.Map; Configuration public class GraphConfig { Bean public Graph hrAgentGraph( AlibabaQwenChatModel chatModel, LeaveBalanceTool leaveBalanceTool, PolicyQueryTool policyQueryTool, SubmitRequestTool submitRequestTool, IntentClassificationNode intentNode) { // 1. 定义节点 // 输入节点接收用户问题 NodeString inputNode Node.fromInput(input, 用户输入的原始问题); // LLM节点意图分类 (自定义节点见下一步) NodeMapString, Object intentClassificationNode intentNode.getNode(); // 工具节点查询余额 ToolNode queryBalanceNode new ToolNode(queryBalance, leaveBalanceTool, queryLeaveBalance); // 工具节点查询政策 ToolNode queryPolicyNode new ToolNode(queryPolicy, policyQueryTool, queryPolicy); // 工具节点提交申请 ToolNode submitRequestNode new ToolNode(submitRequest, submitRequestTool, submitLeaveRequest); // LLM节点生成最终回复 NodeString finalResponseNode Node.fromSupplier(finalResponse, state - { // 从状态中获取所有信息组装成最终回复 String intent (String) state.get(intent); String answer (String) state.get(answer); String requestId (String) state.get(requestId); StringBuilder response new StringBuilder(); response.append(【HR助手】\n); response.append(识别到您的意图是).append(intent).append(\n\n); if (leave_application.equals(intent) requestId ! null) { response.append(✅ 您的请假申请已成功提交\n); response.append(申请单号).append(requestId).append(\n); response.append(流程说明).append(answer); } else if (policy_query.equals(intent)) { response.append( 相关政策查询结果\n).append(answer); } else if (balance_query.equals(intent)) { response.append( 您的假期余额\n).append(answer); } else { response.append( 我暂时无法处理您的请求。).append(answer); } return response.toString(); }); // 输出节点 NodeString outputNode Node.fromOutput(output, 最终给用户的回复); // 2. 构建图并连接节点 return Graph.builder() // 流程开始 .addNode(inputNode) .addNode(intentClassificationNode) .link(inputNode, intentClassificationNode) // 输入 - 意图识别 // 根据意图分支 .addNode(queryBalanceNode) .addNode(queryPolicyNode) .addNode(submitRequestNode) // 条件路由根据识别出的intent字段决定下一步 .addConditionalLink(intentClassificationNode, state - balance_query.equals(state.get(intent)), queryBalanceNode) .addConditionalLink(intentClassificationNode, state - policy_query.equals(state.get(intent)), queryPolicyNode) .addConditionalLink(intentClassificationNode, state - leave_application.equals(state.get(intent)), submitRequestNode) // 各分支汇聚到最终回复节点 .link(queryBalanceNode, finalResponseNode) .link(queryPolicyNode, finalResponseNode) .link(submitRequestNode, finalResponseNode) // 结束 .link(finalResponseNode, outputNode) .build(); } }4.4 第四步实现自定义LLM节点意图识别这个节点负责理解用户想干什么。它调用大模型并返回结构化的结果如意图、提取的参数。// 文件路径src/main/java/com/example/hragent/node/llm/IntentClassificationNode.java package com.example.hragent.node.llm; import org.springframework.ai.alibaba.qwen.AlibabaQwenChatModel; import org.springframework.ai.graph.Node; import org.springframework.ai.model.ModelOptionsUtils; import org.springframework.ai.parser.BeanOutputParser; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Component; import java.util.Map; Component public class IntentClassificationNode { Autowired private AlibabaQwenChatModel chatModel; public NodeMapString, Object getNode() { // 1. 定义我们希望LLM返回的结构 class IntentResult { public String intent; // 意图: balance_query, policy_query, leave_application, other public MapString, String entities; // 提取的实体如 employeeId, leaveType, keyword等 public String reasoning; // LLM的推理过程便于调试 } BeanOutputParserIntentResult parser new BeanOutputParser(IntentResult.class); // 2. 构建提示词Prompt String systemPrompt 你是一个专业的HR助手负责分析用户的请求意图并提取关键信息。 请严格按照以下JSON格式回复不要添加任何其他内容。 {format} 意图说明 - balance_query: 当用户询问假期余额时。 - policy_query: 当用户询问请假政策、流程、规定时。 - leave_application: 当用户明确表示要请假、申请休假时。 - other: 其他无法归类的请求。 实体字段说明 - 如果意图是balance_query请提取 employeeId (员工ID) 和 leaveType (假期类型如annual, sick)。 - 如果意图是policy_query请提取 keyword (政策关键词)。 - 如果意图是leave_application请提取 employeeId, leaveType, startDate, endDate, reason。 - 其他意图entities可以为空。 .replace({format}, parser.getFormat()); // 3. 创建并返回Node return Node.fromSupplier(intentClassification, state - { String userInput (String) state.get(input); if (userInput null) { throw new IllegalArgumentException(输入不能为空); } String prompt systemPrompt \n\n用户请求 userInput; String llmResponse chatModel.call(prompt); // 调用大模型 // 4. 解析LLM的回复 IntentResult result; try { result parser.parse(llmResponse); } catch (Exception e) { // 解析失败返回默认结果 result new IntentResult(); result.intent other; result.reasoning LLM回复格式解析失败: e.getMessage(); } // 5. 将结果放入State供后续节点使用 // 这里将对象转为Map方便Graph中条件判断和工具节点参数绑定 // 注意Graph State中存储的应该是简单类型或Map/List复杂对象可能需要序列化 MapString, Object resultMap ModelOptionsUtils.toMap(result); // 将提取的实体也平铺到State中方便工具节点直接通过参数名获取 if (result.entities ! null) { resultMap.putAll(result.entities); } return resultMap; }); } }4.5 第五步创建控制器与启动应用最后我们提供一个HTTP接口来触发这个Agent。// 文件路径src/main/java/com/example/hragent/controller/AgentController.java package com.example.hragent.controller; import org.springframework.ai.graph.Graph; import org.springframework.ai.graph.GraphResponse; import org.springframework.beans.factory.annotation.Qualifier; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RestController; import java.util.Map; RestController public class AgentController { private final Graph hrAgentGraph; // 通过Qualifier指定注入我们定义的Graph Bean public AgentController(Qualifier(hrAgentGraph) Graph hrAgentGraph) { this.hrAgentGraph hrAgentGraph; } PostMapping(/ask) public MapString, Object askHrAgent(RequestBody MapString, String request) { String question request.get(question); String employeeId request.get(employeeId); // 可以从会话或登录信息中获取 // 1. 准备初始状态 MapString, Object initialState Map.of( input, question, employeeId, employeeId ! null ? employeeId : EMP001 // 示例默认ID ); // 2. 执行Graph GraphResponse response hrAgentGraph.call(initialState); // 3. 获取输出 String finalOutput (String) response.getOutput().get(output); MapString, Object executionSteps response.getSteps(); // 可以返回执行步骤用于调试 // 4. 返回结果 return Map.of( answer, finalOutput, steps, executionSteps.keySet(), // 展示了哪些节点被执行了 success, true ); } }// 文件路径src/main/java/com/example/hragent/HrAgentApplication.java package com.example.hragent; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class HrAgentApplication { public static void main(String[] args) { SpringApplication.run(HrAgentApplication.class, args); System.out.println(HR AI Agent 服务已启动); } }4.6 运行与验证启动应用运行HrAgentApplication的main方法。使用工具测试使用Postman、curl或任何HTTP客户端发送POST请求。curl -X POST http://localhost:8080/ask \ -H Content-Type: application/json \ -d { question: 我的年假还剩多少天, employeeId: EMP001 }预期结果你会收到一个JSON响应其中answer字段包含类似“【HR助手】...您的年假余额10天”的内容。同时控制台会打印工具调用的日志。测试其他意图question: 请问婚假有多少天question: 我想从下周一请三天年假出去旅游。5. 20个核心技术点与面试要点解析通过以上实战我们覆盖了以下关键知识点掌握这些足以应对大部分AI Agent相关的面试和开发场景Spring AI 核心概念ChatClient,ChatModel,Prompt,Message。Alibaba Graph 核心组件Graph,Node,ToolNode,ConditionalNode。工具定义与注册Tool注解的使用参数描述的重要性。Graph构建APIGraph.builder(),addNode(),link(),addConditionalLink()。状态State管理节点间如何通过MapString, Object传递数据。条件路由使用addConditionalLink实现if-else逻辑。自定义节点如何包装LLM调用或复杂业务逻辑为一个Node。输出解析使用BeanOutputParser让LLM返回结构化数据。提示词工程设计System Prompt引导LLM完成特定任务意图识别、信息抽取。大模型集成配置阿里云Qwen客户端的配置与API-KEY管理。执行流程可视化通过GraphResponse.getSteps()调试执行路径。异常处理在节点中处理LLM调用失败、解析失败等异常。并行执行Graph支持addAllLink实现并行节点本文未展开。循环与递归通过条件节点和状态控制可以实现简单循环如重试。与Spring生态集成工具节点本身就是Spring Bean可轻松注入Repository,RestTemplate等。Agent的输入/输出设计如何设计Controller接口与前端交互。上下文管理如何在多轮对话中保持State需要额外设计会话存储。Token消耗与优化在ToolNode中执行实际调用减少不必要的LLM交互以节省Token。测试策略如何对单个Node和整个Graph进行单元测试和集成测试。生产部署考量配置管理、监控、日志、Graph定义的版本管理。6. 常见问题与排查思路在开发过程中你可能会遇到以下问题问题现象可能原因排查思路与解决方案启动报错No qualifying bean of type Graph1.GraphConfig中未定义Bean。2.Qualifier名称不匹配。3. 依赖版本冲突。1. 检查GraphConfig类是否有Configuration和Bean注解。2. 确认Controller中Qualifier(“hrAgentGraph”)与Bean方法名一致。3. 运行mvn dependency:tree检查Spring AI相关依赖是否存在多个版本。调用接口返回错误提示无法识别意图1. LLM API-KEY无效或额度不足。2. 模型名称配置错误。3. Prompt设计不佳LLM未按格式回复。1. 检查application.yml中的api-key建议用环境变量QWEN_API_KEY。2. 确认模型名称qwen-max等在当前区域可用。3. 在IntentClassificationNode中打印llmResponse查看原始回复优化Prompt。工具Tool未被调用1. 意图识别结果intent字段值不符合条件边的判断。2. 工具节点参数无法从State中获取。1. 在IntentClassificationNode结束后打印State确认intent值是balance_query等预期值。2. 确保工具方法参数名如employeeId与State中存储的键名一致。Graph会尝试按名称自动绑定。Graph执行卡住或无输出1. 图中存在环状依赖或死循环。2. 某个节点抛出未处理的异常。3. 未正确定义OutputNode。1. 检查Graph的连接逻辑确保是DAG有向无环图。2. 在每个节点中加入日志或异常捕获。3. 确保最终有一个节点连接到标记为OutputNode的节点。性能问题响应慢1. LLM调用耗时。2. 工具调用如网络IO慢。3. Graph串行步骤过多。1. 考虑使用更快的模型如qwen-turbo或流式响应。2. 对工具调用设置超时、使用缓存。3. 分析流程将无依赖的节点改为并行执行addAllLink。7. 最佳实践与进阶建议要将这个Demo转化为生产可用的系统还需要考虑以下几点提示词工程优化少样本学习在System Prompt中提供几个例子Few-Shot能极大提高意图识别和信息抽取的准确性。结构化输出约束使用BeanOutputParser或JsonOutputParser严格约束输出格式这是Agent稳定性的关键。分步思考对于复杂任务可以设计多个LLM节点让Agent先“思考”再“行动”。状态管理与会话当前的State是单次请求有效的。要实现多轮对话需要引入Session概念将每次的State变化持久化如存入Redis并在下次请求时恢复。可以在State中维护一个conversationHistory列表存储对话记录并在每次调用LLM时将其作为上下文传入。工具设计的健壮性参数校验在工具方法内部对输入参数进行有效性校验。异常处理工具应抛出明确的业务异常并在Graph中通过ErrorHandler节点进行统一处理如告知用户“系统繁忙请稍后再试”。幂等性对于提交类工具如submitLeaveRequest要设计幂等逻辑防止重复提交。可观测性与监控日志记录详细记录每个节点的输入、输出、耗时特别是LLM的请求和响应注意脱敏API-KEY。链路追踪为每个用户请求生成唯一的traceId贯穿整个Graph执行过程便于问题排查。指标监控监控Graph的执行成功率、各节点平均耗时、Token消耗量、工具调用失败率等。安全与权限输入过滤对用户输入进行必要的清洗防止Prompt注入攻击。工具权限在调用工具前根据当前用户身份从State中获取校验其是否有权限执行该操作。例如queryLeaveBalance工具只能查询自己的余额。输出审查对LLM生成的最终回复进行内容安全审核。配置化与动态Graph对于复杂的业务硬编码Graph可能难以维护。可以考虑将Graph的结构节点、边配置在数据库或配置中心运行时动态构建。Spring AI的GraphAPI支持以编程方式灵活构建为动态化提供了基础。构建一个成熟的企业级AI Agent是一个系统工程但通过Spring AI Alibaba Graph我们获得了强大的编排能力和与Spring生态的无缝集成。从这个小而美的HR自动化案例出发你可以将其模式复制到智能客服、运维排障、数据查询等任何需要多步骤、有条件判断的自动化场景中。