你有没有遇到过这样的场景一个HR同事每天要处理几十份简历筛选、分类、初步沟通、安排面试、跟进反馈……这些重复性工作不仅耗时还容易因为疲劳而错过优秀人才。或者你作为一个开发者看到AI Agent的概念很火但一上手就发现从“跑通一个Demo”到“做出一个能在真实业务里稳定工作的智能体”中间隔着一道巨大的鸿沟。最近Spring AI Alibaba Graph 的出现让很多Java开发者看到了一个机会用自己熟悉的Spring生态去搭建一个真正能处理复杂工作流的AI Agent。但问题也随之而来——网上的教程要么停留在“Hello World”级别的API调用要么直接跳到“企业级架构”这种抽象概念中间那部分“怎么从玩具变成工具”的实操经验几乎没人细说。今天我们就以“HR自动化AI Agent”这个跨行业通用的实战案例为线索拆解如何用Spring AI Alibaba Graph搭建一个能理解任务、拆解步骤、调用工具并完成闭环的智能体。这不仅仅是一个技术实现更是一次关于如何将大模型能力“工程化”的深度探索。你会发现真正的难点从来不是调用哪个API而是如何设计一个可靠、可维护、可扩展的智能工作流。1. 为什么是“HR自动化”一个理解AI Agent价值的绝佳切口在开始写代码之前我们必须先回答一个问题为什么选择HR场景作为案例它真的能体现AI Agent的核心价值吗我的判断是HR的日常工作流程是检验一个AI Agent框架是否具备“业务理解”和“流程编排”能力的试金石。它不像聊天机器人那样简单的一问一答也不像单次文本生成那样独立。一个HR Agent需要串联起多个环节理解需求从“帮我找一下Java后端工程师”这样模糊的指令拆解出具体的技能要求、经验年限、薪资范围。执行动作它可能需要去简历库搜索、去招聘网站爬取模拟、给候选人发送初步沟通邮件、甚至预约面试时间。决策与判断根据简历内容进行初步筛选判断与岗位的匹配度。状态管理与回溯记住已经联系过哪些人、面试进展到哪一步并在后续对话中能回溯上下文。这个过程天然就是一个“图”Graph。Spring AI Alibaba Graph 中的“Graph”指的就是这种有向无环的工作流。每个节点代表一个处理单元可以是LLM调用、工具函数、条件判断节点之间的边代表执行路径和数据的流动。所以搭建HR Agent的过程本质上是在用代码定义一套“招聘专家”的思维和工作流程。这比单纯演示“请写一首诗”要有价值得多因为它触及了AI Agent落地的核心将不确定的自然语言指令转化为确定性的、可重复执行的业务步骤。2. 超越“Hello World”用Spring AI Alibaba Graph构建智能体的核心骨架很多教程止步于配置一个ChatClient然后调用chat()方法。这离一个真正的Agent还差得很远。Spring AI Alibaba Graph 提供了一套更高级的抽象让我们能以“编排工作流”的思维来构建应用。2.1 环境搭建与依赖避开第一个坑首先确保你的项目是基于Spring Boot 3.x推荐3.2和Java 17。在pom.xml中核心依赖不仅仅是spring-ai-alibaba-spring-boot-starter。dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-alibaba-spring-boot-starter/artifactId version最新版本/version !-- 请替换为官方最新版本 -- /dependency !-- 图形化工作流定义通常需要 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-core/artifactId /dependency !-- 如果你需要连接自己的数据源如简历库数据库驱动也是必须的 -- dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency第一个关键点模型配置。在application.yml中你需要明确指定使用的模型。这里以阿里云灵积平台为例spring: ai: alibaba: chat: options: # 模型名称例如 qwen-max, qwen-plus model: qwen-max # 阿里云API密钥 api-key: ${ALIBABA_API_KEY} # 通常base-url是固定的 base-url: https://dashscope.aliyuncs.com/compatible-mode/v1注意api-key务必通过环境变量${ALIBABA_API_KEY}注入不要硬编码在配置文件里。这是安全实践的第一步。2.2 定义“工具”Tool让Agent拥有“手和脚”Agent的强大之处在于它能调用外部工具。在HR场景中工具可能就是ResumeSearchTool: 根据条件从数据库查询简历。EmailSenderTool: 发送面试邀请或感谢信。CalendarCheckTool: 检查面试官的空闲时间。在Spring AI中定义一个工具非常简单就是一个普通的Spring Bean方法上标注Tool注解。import org.springframework.ai.tool.annotation.Tool; import org.springframework.stereotype.Component; Component public class ResumeSearchTool { Tool(description 根据技能关键词、工作年限和地点搜索简历返回匹配的简历列表。) public ListResume searchResumes( ToolParam(description 技能关键词如Java, Spring Cloud) String skills, ToolParam(description 最低工作年限) int minYearsOfExperience, ToolParam(description 工作地点) String location) { // 这里实现你的数据库查询逻辑 // 示例return resumeRepository.findBySkillsContainingAndExperienceGreaterThanEqualAndLocation(skills, minYearsOfExperience, location); return new ArrayList(); // 返回示例 } }关键理解Tool注解和描述description至关重要。大模型LLM正是根据这些描述来决定在什么情况下调用哪个工具以及如何传递参数。描述要清晰、准确就像你在给一个实习生写工作说明书。2.3 构建工作流Graph从线性思维到图状思维这是最核心的部分。传统的代码是线性的A - B - C。而Graph允许我们定义更复杂的关系根据A的结果决定走B分支还是C分支甚至并行执行D和E。Spring AI Alibaba Graph 支持通过Java DSL领域特定语言或YAML来定义Graph。对于复杂流程DSL更灵活。import org.springframework.ai.graph.Graph; import org.springframework.ai.graph.builder.GraphBuilder; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class HrAgentGraphConfig { Bean public Graph hrRecruitmentGraph(GraphBuilder graphBuilder) { return graphBuilder .start(parse_requirement) // 节点1解析需求 .function(llmFunction) // 使用LLM解析用户输入 .to(decide_action) // 流向决策节点 .node(decide_action) // 节点2决策下一步行动 .function(llmFunction) // LLM判断该搜索、发邮件还是其他 .to(search_resumes, send_email, schedule_interview) // 三个可能的分支 .node(search_resumes) .tool(resumeSearchTool) // 调用我们定义的工具 .to(format_results) .node(format_results) .function(llmFunction) // 将搜索结果格式化为友好回复 .end() // 结束 .node(send_email) .tool(emailSenderTool) .end() .node(schedule_interview) .tool(calendarCheckTool) .to(send_invitation) .node(send_invitation) .tool(emailSenderTool) .end() .build(); } }这个Graph定义了以下流程开始 - 解析用户需求LLM。根据解析结果决定走哪条分支搜索简历、发送邮件或安排面试。每条分支调用相应的工具执行具体任务。任务完成后可能经过格式化LLM最终结束。为什么这比直接写Service类更好因为它的声明式和可视化。整个工作流的逻辑一目了然修改执行顺序或增加新节点就像修改流程图一样简单而不需要深入业务代码逻辑中去寻找调用链。3. 实战演练拆解一个完整的“筛选并联系候选人”流程让我们把上面的骨架填充上血肉实现一个具体的场景HR说“帮我找3个在北京有5年以上Java经验的工程师并发送初步沟通邮件”。3.1 步骤一设计提示词Prompt—— 告诉LLM如何思考LLM需要明确的指令。我们将为Graph中的llmFunction节点设计专用的提示词模板。import org.springframework.ai.prompt.PromptTemplate; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class PromptConfig { Bean(name requirementParserPrompt) public PromptTemplate requirementParserPrompt() { return new PromptTemplate( 你是一个专业的HR助手。请从用户的以下请求中精确提取出招聘需求信息。 用户请求{userInput} 请以JSON格式输出且只输出JSON不要有任何其他解释。 JSON结构 { position: 职位名称, skills: [技能1, 技能2, ...], minExperience: 最低工作年限数字, location: 工作地点, action: 需要执行的主要动作如search_resumes, send_email } ); } Bean(name actionDeciderPrompt) public PromptTemplate actionDeciderPrompt() { return new PromptTemplate( 你是一个工作流决策器。根据当前的招聘需求上下文决定下一步应该做什么。 当前需求{requirementJson} 历史动作{history} 请从以下选项中选择一个且仅一个动作 - search_resumes: 如果还需要搜索或筛选简历。 - send_email: 如果已经确定了候选人需要发送邮件。 - schedule_interview: 如果需要安排面试。 - complete: 如果所有任务已完成。 只输出动作名称例如search_resumes ); } }提示词设计的核心结构化输出和严格约束。通过要求LLM输出特定格式的JSON或限定选项我们才能在后继的代码中可靠地解析其结果驱动工作流走向不同的分支。这是Agent稳定性的基石。3.2 步骤二实现工具类与数据层ResumeSearchTool需要真实的查询。这里假设使用Spring Data JPA。Component public class ResumeSearchTool { Autowired private ResumeRepository resumeRepository; Tool(description 根据技能、最小工作年限、地点和需要的数量搜索简历返回匹配的简历列表。) public ListResume searchResumes( ToolParam(description 技能列表) ListString skills, ToolParam(description 最低工作年限) int minYearsOfExperience, ToolParam(description 工作地点) String location, ToolParam(description 需要返回的最大简历数量) int limit) { // 一个简单的多技能匹配查询示例实际可能更复杂 return resumeRepository .findByLocationAndYearsOfExperienceGreaterThanEqual(location, minYearsOfExperience) .stream() .filter(resume - skills.stream().anyMatch(skill - resume.getSkills().contains(skill))) .limit(limit) .collect(Collectors.toList()); } }EmailSenderTool则集成邮件发送服务如JavaMailSender。3.3 步骤三组装与执行Graph在Service中我们注入定义好的Graph并执行它。Service public class HrAgentService { Autowired private Graph hrRecruitmentGraph; Autowired private GraphExecutor graphExecutor; public String processHrRequest(String userInput) { // 1. 准备初始输入 MapString, Object initialInput new HashMap(); initialInput.put(userInput, userInput); initialInput.put(history, []); // 初始无历史 // 2. 执行Graph GraphResponse response graphExecutor.execute(hrRecruitmentGraph, initialInput); // 3. 从最终节点获取结果 // 假设我们的Graph结束在名为“format_results”或“send_email”的节点 // 需要根据Graph设计来获取具体结果 MapString, Object finalOutput response.getOutput(); return (String) finalOutput.get(finalReply); // 返回给用户的最终消息 } }3.4 步骤四暴露为API最后通过一个简单的REST控制器提供服务。RestController RequestMapping(/api/hr-agent) public class HrAgentController { Autowired private HrAgentService hrAgentService; PostMapping(/process) public ResponseEntityAgentResponse processRequest(RequestBody UserRequest request) { String reply hrAgentService.processHrRequest(request.getQuery()); return ResponseEntity.ok(new AgentResponse(reply)); } }至此一个具备基本能力的HR自动化Agent后端就搭建完成了。用户通过API发送自然语言请求后端通过Graph工作流协调LLM和工具完成从理解到执行的闭环。4. 从“跑通”到“用好”20个必须关注的工程化核心点Demo跑起来只是第一步。要让这个Agent能在实际环境中可靠工作以下20个核心点是你必须逐一检查和思考的。这不仅是技术点更是面试中展现你工程深度的关键。4.1 性能与成本管控Token消耗统计与优化Spring AI Alibaba 提供了TokenUsage类来统计每次调用的消耗。在application.yml中开启spring.ai.alibaba.chat.options.log-requests: true也能看到详情。优化策略在提示词中严格要求输出格式避免冗余对长文本简历进行智能摘要后再喂给LLM。请求超时与重试网络和模型服务都不稳定。务必配置合理的超时spring.ai.alibaba.chat.options.request-timeout和重试机制可结合Spring Retry。速率限制Rate Limiting模型服务商有QPS限制。在客户端必须实现限流避免突发流量导致请求失败。异步与非阻塞Graph的执行特别是涉及多个LLM调用和工具调用时可能是耗时的。考虑使用Async或WebFlux进行异步处理避免阻塞HTTP线程。4.2 稳定性与可靠性工具的健壮性ResumeSearchTool里数据库查询可能慢或失败EmailSenderTool可能遇到SMTP服务器问题。每个工具都必须有完善的异常处理和日志记录并考虑设计降级方案如查询失败时返回缓存结果。Graph的状态管理与持久化复杂的多轮交互Agent其Graph执行状态可能需要保存到数据库或Redis中以便中断后恢复。Spring AI Graph 本身支持GraphExecution状态持久化需要你配置GraphExecutionRepository。LLM输出的不确定性处理尽管我们要求LLM输出JSON但它偶尔仍可能“胡说八道”。必须在代码中添加解析校验逻辑一旦解析失败触发重试或转入人工处理流程。循环与深度控制Graph要避免设计成无限循环。确保每个执行路径都有明确的终止条件end()节点。4.3 可观测性与调试结构化日志记录每个Graph节点的输入、输出、耗时和Token使用情况。使用MDCMapped Diagnostic Context为每次请求分配唯一ID方便链路追踪。Graph可视化Spring AI 部分版本支持将Graph导出为Mermaid.js或DOT格式的图表。将其集成到管理后台直观查看工作流和实时执行状态。输入输出快照在开发测试阶段保存每次重要LLM调用和工具调用的输入输出便于复现和调试诡异问题。4.4 架构与扩展性工具的动态注册与发现随着业务增长工具类会越来越多。可以设计一个工具注册中心让Graph能动态发现可用的工具而不是硬编码在配置里。多模型路由与降级不要绑定死一个模型。可以设计一个ModelRouter根据任务类型创意性 vs 逻辑性、成本、当前负载等因素动态选择不同的模型如Qwen-Max用于复杂决策Qwen-Turbo用于简单分类。并在主模型不可用时自动切换到备用模型。向量数据库集成对于简历搜索简单的关键词匹配不够。使用Spring AI的向量存储抽象将简历技能描述向量化进行语义搜索匹配效果更佳。Agent的“记忆”能力为Agent添加长期记忆如使用Redis存储对话历史摘要和短期记忆当前会话上下文使其能在多轮对话中保持一致性。4.5 安全与合规输入输出过滤与审查对用户输入和LLM输出进行必要的敏感词过滤、防注入攻击检查。特别是涉及发送邮件、访问数据库的工具。数据隐私简历信息是高度敏感的个人数据。确保工具在查询、处理和日志记录时都进行了脱敏。LLM调用是否涉及数据出境需合规评估。权限控制不同的HR用户可能只能操作自己部门的简历或职位。需要在Graph执行入口或具体工具中注入并校验用户权限上下文。4.6 开发与部署配置外部化所有模型API Key、端点、超时时间、提示词模板等必须全部放在配置中心如Nacos、Apollo或环境变量中杜绝硬编码。版本管理与回滚Graph的定义、提示词、工具逻辑都可能频繁迭代。需要像管理代码一样管理它们的版本并具备快速回滚能力。5. 面试少走弯路如何向面试官阐述你的AI Agent项目如果你在简历中写了这样一个项目面试官想听的绝不仅仅是“我用Spring AI调了通义千问”。他们想考察的是你面对新技术时的工程化思维和解决真实问题的能力。你可以按这个框架来组织你的回答“我构建了一个用于HR场景的自动化AI Agent核心是解决从模糊需求到确定性执行的流程自动化问题。我选用Spring AI Alibaba Graph是因为它提供了基于工作流编排的声明式编程模型非常适合处理HR招聘这类多步骤、有分支的任务。”“在实现上我重点解决了三个层面的问题”交互层LLM调用通过设计结构化的提示词约束LLM的输出使其成为可靠的工作流决策节点而不是黑盒聊天。执行层工具集成将简历查询、邮件发送等能力封装成Tool让Agent具备了操作真实业务系统的“手”。流程层Graph编排用DSL清晰定义了“解析需求-决策-执行-反馈”的流程使得业务逻辑可视化、可维护。“在项目深入阶段我特别关注了工程化落地”性能与成本通过Token统计和提示词优化控制成本通过异步化和缓存提升响应速度。稳定性为每个工具和LLM调用设置了超时、重试和降级策略。可观测性实现了全链路的结构化日志和Graph执行状态追踪便于调试。安全加入了输入校验、数据脱敏和基于角色的权限控制。“这个项目的价值在于它不是一个玩具而是一个展示了如何将大模型能力以可控、可靠、可扩展的方式嵌入到现有Java技术栈和业务系统中的原型。它让我深入思考了AI Native应用开发与传统业务系统开发在架构模式上的异同。”这样的阐述表明你不仅会使用框架更理解其背后的设计理念并具备了将前沿技术落地到复杂生产环境所需的全面思考。这才是面试官真正想听到的“干货”。回到开头的问题用Spring AI Alibaba Graph搭建AI Agent技术上的入门并不难。真正的挑战和乐趣在于如何用软件工程的严谨思维去驾驭大模型的不确定性设计出既智能又鲁棒的业务流程。HR自动化只是一个起点这套方法论可以平移到客服、运维、内容审核、智能导购等无数场景。当你开始用“图”的视角去拆解业务用“工具”的思维去扩展能力用“工程化”的标准去要求每一个细节时你就已经走在了AI Agent实战开发的正道上。