最近在几个项目里我反复被问到同一个问题“我们想用Java把大模型能力接进来但不想只是做个简单的问答接口而是希望它能像‘智能员工’一样根据我们的指令去调用工具、查询数据、完成一个完整的任务链。有没有现成的、能快速上手的框架”如果你也面临类似的场景比如想用Java构建一个能自动处理工单、分析报表、生成代码或进行复杂决策的AI应用那么你很可能已经接触到了“AI Agent”这个概念。但概念归概念从“知道Agent”到“用Java写出一个稳定、可维护的Agent应用”中间隔着一道巨大的工程鸿沟。你需要处理模型调用、工具编排、记忆管理、流程控制等一系列问题而不仅仅是发个HTTP请求。这时Spring AI Alibaba Agent Framework后文简称Alibaba Agent就进入了视野。它不是一个独立的全新发明而是构建在Spring AI这个官方项目之上由阿里云贡献的一套针对Agent场景的增强框架。它的核心价值在我看来不是提供了某个惊天动地的独家功能而是把构建生产级Java AI Agent的“最佳实践”和“常见模式”进行了框架化封装让你能在一个熟悉、规范的Spring生态里快速搭建起一个职责清晰、易于扩展的智能体系统。很多人一上来就研究各种炫酷的ReAct、Plan-and-Execute模式却忽略了最基础的工程问题代码怎么组织工具Skill怎么定义和管理上下文Context如何在不同步骤间传递和持久化异常怎么处理这些才是决定一个Agent项目能否从Demo走向生产的关键。本文不会只停留在介绍Alibaba Agent有哪些注解和接口。我会结合一个具体的“多模态RAG检索增强生成Agent”场景带你走完从零搭建、定义技能、集成外部工具、到最终部署上线的完整路径。你会看到如何用Java思维而不仅仅是Prompt工程思维来构建一个真正可用的AI应用。1. 为什么是“Spring AI Alibaba Agent Framework”在深入代码之前我们需要先达成一个共识选择任何一个技术栈首先要看它解决的核心痛点是什么以及它是否与你现有的技术体系平滑融合。1.1 从“大模型调用”到“智能体系统”的跃迁最初我们接入大模型的方式很简单封装一个HTTP客户端向OpenAI或通义千问的API发送Prompt然后解析返回的文本。这解决了“有无”的问题。但随着需求复杂化问题接踵而至任务分解用户说“帮我分析一下上季度的销售数据并写一份总结报告”。这包含了“查询数据”、“分析趋势”、“生成文本”等多个子任务。一个简单的问答接口无法处理。工具调用查询数据需要连接数据库生成图表需要调用绘图库。大模型本身不会这些操作它需要“手”工具。状态管理一个多轮对话中Agent需要记住之前的对话历史、已经执行过的操作结果作为后续决策的依据。流程控制是先查数据还是先确认时间范围某个工具调用失败了是重试还是换种方式这需要可编程的流程逻辑。这就是从“大模型调用”升级到“智能体系统”需要跨越的鸿沟。你需要一个框架来帮你管理这些复杂度而不是把所有逻辑都堆在一个Controller里。1.2 Spring AI 的定位与 Alibaba Agent 的补充Spring AI 项目旨在为Spring生态提供一套统一的大模型抽象。它定义了ChatClient、EmbeddingClient、ImageClient等核心接口让开发者可以像切换数据库驱动一样在OpenAI、Azure、Ollama本地模型、通义千问等不同模型提供商间切换而业务代码几乎不变。这是其最大的价值——标准化和可移植性。然而Spring AI 初期更侧重于“客户端”层面的抽象对于更高阶的“Agent”模式虽然提供了基础支持如ChatClient调用但缺乏一套开箱即用的、面向生产的最佳实践框架。这正是 Alibaba Agent Framework 要填补的空白。Alibaba Agent 做了什么它基于Spring AI提供了一套更上层的、面向Agent开发的编程模型和基础设施声明式的Skill定义通过注解如Tool,Action将你的Java方法暴露为Agent可调用的工具框架负责参数的序列化、反序列化以及与大模型的自然语言理解进行桥接。统一的上下文Context管理提供了AgentContext等对象用于在Agent执行的不同阶段规划、执行、观察之间传递数据管理对话历史和工具调用结果。内置的Agent执行器Executor封装了ReAct等经典Agent执行循环你只需要关注定义Skill和提供Prompt框架负责驱动“思考-行动-观察”的迭代过程。与Spring生态无缝集成它本身就是一个Spring Boot Starter。这意味着你可以天然地使用Spring的依赖注入、AOP、事务管理、配置外部化等所有特性来构建你的Agent。你的Agent可以方便地注入Repository来访问数据库注入RestTemplate来调用外部API。简单说Spring AI 让你能方便地“问”模型而 Alibaba Agent Framework 让你能方便地“使唤”模型去干活。1.3 技术选型对比为什么是Java你可能会问现在Agent开发不是Python的天下吗LangChain, LlamaIndex 如火如荼。没错Python在原型验证、学术研究上速度更快。但当我们谈论企业级、生产环境的AI应用时Java的优势就凸显出来工程化与稳定性Java强大的类型系统、成熟的工程实践设计模式、单元测试、以及JVM的健壮性对于构建需要7x24小时运行、逻辑复杂的商业系统至关重要。现有资产整合大量企业的核心业务系统ERP, CRM, 金融交易系统都是用Java写的。用Java开发Agent可以最低成本地复用这些系统的业务逻辑和数据访问层直接将其“工具化”。团队与运维很多企业拥有庞大的Java开发团队和成熟的Spring Cloud微服务运维体系。引入一个Java技术栈的AI框架学习成本和运维风险远低于引入一套全新的Python技术栈。性能与并发对于高并发场景下的Agent服务如客服机器人Java成熟的线程池、NIO等机制能提供更可靠的服务能力。因此如果你的团队背景是Java你的系统主体是Java那么选择Spring AI Alibaba Agent Framework是一个顺理成章、降低总拥有成本TCO的决策。它让你在享受AI能力的同时不必离开你熟悉的、可靠的主场。2. 实战构建一个多模态RAG智能体概念讲得再多不如一行代码。我们一起来构建一个具体的智能体“多模态技术文档分析助手”。场景公司内部有一个知识库里面不仅有Markdown/PDF格式的技术文档还有大量的架构图、流程图截图PNG/JPG。新员工或开发者遇到问题时可以向这个助手提问例如“我们系统的支付模块在异常情况下是如何降级的把相关的流程图也找出来给我看。”这个助手需要完成理解问题文本。检索相关文档和图片多模态检索。综合文本和图片信息生成答案多模态生成。在答案中可能需要描述或引用图片内容。我们将这个任务拆解给Agent执行它会自主决定何时调用“检索工具”何时调用“图片理解工具”。2.1 环境搭建与基础配置首先创建一个标准的Spring Boot 3.x项目。1. 添加依赖 (pom.xml):核心是spring-ai-alibaba-spring-boot-starter。为了演示多模态我们还需要通义千问的VL视觉语言模型依赖以及向量数据库这里用内存型的SimpleVectorStore做演示。dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-spring-boot-starter/artifactId version最新版本/version !-- 请查看官方仓库获取最新版本 -- /dependency !-- 通义千问VL模型支持 -- dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-tongyi-vl-spring-boot-starter/artifactId version最新版本/version /dependency !-- Spring AI 向量存储抽象内存实现 -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-simple-vector-store/artifactId /dependency !-- 文本嵌入模型用于将文本转为向量 -- dependency groupIdcom.alibaba.cloud.ai/groupId artifactIdspring-ai-alibaba-tongyi-embedding-spring-boot-starter/artifactId version最新版本/version /dependency2. 配置文件 (application.yml):配置通义千问的API密钥和基础URL。切记密钥不要提交到代码仓库spring: ai: alibaba: tongyi: chat: api-key: ${TONGYI_API_KEY:your-api-key-here} base-url: https://dashscope.aliyuncs.com/compatible-mode/v1 embedding: api-key: ${TONGYI_API_KEY} vl: # 多模态模型配置 api-key: ${TONGYI_API_KEY} # 可以配置Agent执行的一些默认参数如最大迭代次数 alibaba: ai: agent: max-iterations: 103. 初始化向量数据库一次性脚本:我们需要一个地方存储文档和图片的“向量索引”。在实际生产中你会用Milvus、Elasticsearch等这里我们用内存存储演示原理。Component public class VectorStoreInitializer { Autowired private VectorStore vectorStore; // 由Spring AI自动注入SimpleVectorStore Autowired private EmbeddingClient embeddingClient; // 文本嵌入客户端 PostConstruct public void init() { // 1. 准备文本文档模拟从文件系统或数据库读取 ListDocument textDocs List.of( new Document(支付模块降级方案当第三方支付接口超时系统自动切换至备用通道A并记录日志。, Map.of(source, payment_guide.md, type, text)), new Document(用户登录流程图描述了从前端发起请求到后端验证的完整过程。, Map.of(source, login_flow.md, type, text)) ); // 2. 为文本生成向量并存储 vectorStore.add(textDocs); // 3. 准备图片文档这里存储的是图片的路径或Base64描述实际生产需用VL模型生成图片向量 // 注意SimpleVectorStore 和标准EmbeddingClient通常只处理文本。 // 真正的多模态检索需要专门的“多模态嵌入模型”将图片和文本映射到同一向量空间。 // 此处为简化我们用文本描述代替图片向量。 ListDocument imageDocs List.of( new Document(这是一张支付系统降级流程的架构图展示了主备切换的逻辑。, Map.of(source, /images/payment_fallback.png, type, image)), new Document(这是一张用户登录的序列图包含了前端、网关、认证服务的交互。, Map.of(source, /images/login_sequence.png, type, image)) ); vectorStore.add(imageDocs); System.out.println(向量数据库初始化完成共加载 (textDocs.size() imageDocs.size()) 个文档。); } }关键点真正的多模态RAG需要像qwen-vl-plus这样的模型既能理解图片内容生成文本描述用于检索也能根据图片回答问题。上述代码的图片处理是简化版。生产环境中你需要用VL模型的嵌入接口来处理图片。2.2 定义Agent的“技能”SkillSkill是Agent能力的基石。我们将定义两个核心技能RetrievalSkill检索技能和ImageAnalysisSkill图片分析技能。1. 检索技能 (RetrievalSkill.java):这个技能负责根据用户问题从向量库中查找最相关的文本和图片描述。Component AgentSkill // 关键注解声明这是一个Agent可用的技能 public class RetrievalSkill { Autowired private VectorStore vectorStore; /** * 根据查询语句检索相关文档。 * Tool 注解将方法暴露为工具name和description很重要大模型靠它来决定是否以及如何调用。 */ Tool(name retrieve_documents, description 根据用户问题检索相关的技术文档和图片描述。输入是一个查询字符串。) public ListDocument retrieve(ToolParam(description 用于检索的查询语句) String query) { // 设置返回最相关的5条记录 int topK 5; ListDocument results vectorStore.similaritySearch(query, topK); // 格式化结果方便Agent阅读 if (results.isEmpty()) { return List.of(new Document(未找到相关文档。)); } return results; } }2. 图片分析技能 (ImageAnalysisSkill.java):这个技能在Agent决定需要深入理解某张图片时被调用。它调用通义千问VL模型。Component AgentSkill public class ImageAnalysisSkill { Autowired private TongYiVlChatClient vlChatClient; // 注入多模态聊天客户端 Tool(name analyze_image, description 深入分析一张图片的内容。输入是图片的URL或本地路径以及一个具体的问题。) public String analyzeImage( ToolParam(description 图片的路径或URL) String imageUrl, ToolParam(description 关于这张图片的具体问题) String question) { // 构建多模态消息 UserMessage userMessage new UserMessage(question, List.of(new ImageUrl(imageUrl))); ChatResponse response vlChatClient.call(new Prompt(List.of(userMessage))); if (response ! null response.getResults() ! null !response.getResults().isEmpty()) { return response.getResult().getOutput().getContent(); } return 无法分析该图片。; } }Skill设计的核心思想单一职责每个Skill只做一件事并且做好。retrieve只负责检索analyzeImage只负责读图。描述清晰Tool的description和ToolParam的description是给大模型看的“说明书”必须准确、清晰这直接决定了Agent能否正确调用它。强类型接口用Java方法定义参数和返回值类型明确框架会处理与LLM之间的类型转换。2.3 组装并运行你的第一个Agent有了Skill我们需要一个“大脑”来协调它们。我们将创建一个PlanAndExecuteAgent这是一种经典模式先规划步骤再执行。Service public class MultimodalRagAgentService { Autowired private AgentExecutor agentExecutor; // Alibaba Agent 的核心执行器 Autowired private RetrievalSkill retrievalSkill; Autowired private ImageAnalysisSkill imageAnalysisSkill; // 这里不直接注入Skill而是通过Executor自动发现。注入是为了演示。 public String chat(String userMessage) { // 1. 构建系统提示词定义Agent的角色和能力 String systemPrompt 你是一个专业的技术文档分析助手。你的目标是准确、全面地回答用户关于技术系统的问题。 你可以使用以下工具 1. retrieve_documents: 当你需要从知识库中查找相关的技术文档和图片信息时使用。 2. analyze_image: 当用户问题涉及图片内容或者检索结果中提到图片你需要深入理解图片时使用。 请遵循以下步骤思考 - 首先理解用户的问题。 - 其次使用retrieve_documents工具查找相关知识。 - 查阅检索结果如果结果中包含图片type为image且对回答问题关键使用analyze_image工具分析它。 - 最后综合所有文本和图片信息组织成一个清晰、完整的答案回复给用户。 如果检索结果为空或与问题无关请如实告知用户。 ; // 2. 构建消息链 ListMessage messages new ArrayList(); messages.add(new SystemMessage(systemPrompt)); messages.add(new UserMessage(userMessage)); // 3. 创建Prompt并执行Agent Prompt prompt new Prompt(messages); // AgentExecutor会自动发现所有AgentSkill注解的Bean并根据Prompt驱动模型进行思考-行动循环 ChatResponse response agentExecutor.execute(prompt); // 4. 返回最终结果 return response.getResult().getOutput().getContent(); } }最后创建一个简单的REST端点来暴露服务RestController RequestMapping(/api/agent) public class AgentController { Autowired private MultimodalRagAgentService agentService; PostMapping(/chat) public String chat(RequestBody ChatRequest request) { return agentService.chat(request.getMessage()); } public record ChatRequest(String message) {} }现在启动你的Spring Boot应用。向POST /api/agent/chat发送一个请求{message: 支付模块异常降级的流程是怎样的相关的架构图能说明什么}你的Agent将会开始工作模型如Qwen看到提示词和问题决定调用retrieve_documents。RetrievalSkill.retrieve(支付模块异常降级的流程是怎样的相关的架构图能说明什么)被调用返回包含文本和图片描述的文档列表。模型收到检索结果发现其中有图片type: image决定调用analyze_image传入图片路径和具体问题。ImageAnalysisSkill.analyzeImage被调用VL模型分析图片并返回描述。模型综合文本检索结果和图片分析结果生成最终答案返回给用户。整个过程你只需要在Skill中写好业务逻辑在Prompt中定义好规则框架会自动完成复杂的工具调用编排和上下文管理。3. 超越Demo生产环境的关键考量让一个Agent在本地跑起来只完成了10%的工作。剩下的90%是让它稳定、可靠、高效地运行在真实环境中。以下是几个必须面对的关键问题。3.1 性能、成本与稳定性Token消耗与成本控制Agent的ReAct模式会产生大量的中间思考过程这些都会消耗Token。你需要设置最大迭代次数在配置中alibaba.ai.agent.max-iterations防止Agent陷入死循环。优化Prompt清晰的指令可以减少模型的“迷惑”和无效思考。让系统提示词尽可能简洁、精准。上下文管理Alibaba Agent的AgentContext可以帮助你管理历史。对于长对话需要设计摘要策略只将最相关的历史信息放入上下文而不是无脑拼接全部历史。选择合适模型对于工具调用、规划等任务不一定需要最强大、最贵的模型。可以尝试较小、较快的模型将文本生成等任务交给大模型。超时与重试网络调用、模型服务都可能不稳定。为工具调用设置超时在调用外部API如数据库、第三方服务的Skill中务必使用Timeout注解或配置RestTemplate的超时参数。实现重试机制对于可重试的失败如网络抖动可以在Skill方法上使用Spring Retry等机制。注意对于非幂等操作如创建订单慎用重试。Agent执行超时整个Agent的执行也需要设置全局超时避免一个用户请求长时间占用资源。流式输出与用户体验最终答案可能很长让用户等待十几秒体验很差。考虑使用Spring AI支持的流式响应Streaming将模型生成的内容逐步推送到前端。3.2 可观测性与调试Agent系统的“黑盒”特性比普通服务更强可观测性至关重要。结构化日志在Skill方法、Agent执行器的关键节点打入详细的日志。记录请求ID、用户输入、模型思考过程、工具调用详情输入/输出、最终响应。使用MDCMapped Diagnostic Context来串联一个请求的所有日志。监控与告警监控关键指标Token消耗速率与费用。Agent请求量、平均响应时间、错误率。各Skill调用次数、成功/失败率、平均耗时。模型API的延迟和错误率。“思考过程”持久化将Agent执行过程中的完整链条包括模型的中间推理、工具调用记录存储到数据库。这在排查错误、优化Prompt、分析用户意图时是无价之宝。Alibaba Agent框架的事件机制可能为此提供钩子。3.3 安全与权限将企业内部能力暴露给AI调用安全是底线。Skill的权限控制不是所有登录用户都能调用所有Skill。例如“执行数据库删除”的Skill只能给管理员使用。可以在Skill方法上结合Spring Security的PreAuthorize注解进行方法级权限校验。输入验证与净化对所有从用户输入传递到Skill参数的数据进行严格的验证和净化防止注入攻击。输出审查与过滤对模型生成的最终答案可以考虑增加一层安全审查例如调用内容安全API防止生成不当内容。访问限流对Agent端点进行限流防止恶意刷接口消耗Token和计算资源。3.4 架构演进从单体到智能体服务网格当你的智能体越来越多能力越来越复杂一个单体应用会变得难以维护。可以考虑的演进方向Skill即服务将复杂的、独立的Skill拆分成独立的微服务例如“数据查询Skill”背后是一个专门的数据服务。Agent通过RPC或HTTP调用这些服务。这提高了Skill的复用性和可维护性。专用Agent不要试图打造一个“全能Agent”。根据业务域拆分客服答疑Agent、代码生成Agent、报表分析Agent。每个Agent有自己专用的Skill和优化过的Prompt。编排层在最上层可以有一个“路由Agent”或基于规则的网关根据用户意图将请求分发给最合适的专用Agent处理。4. 思维框架如何设计一个好的Java AI Agent通过上面的实践我们可以沉淀出一个设计Java AI Agent的通用思维框架。它不止适用于Alibaba Agent Framework也适用于任何类似的Agent构建场景。4.1 设计四层模型我将一个生产级Agent系统的构建分为四个层次| 表现层 (Presentation) | - REST API, WebSocket, 消息队列接入点 | 智能层 (Intelligence) | - Agent Executor, Prompt工程 流程编排 | 能力层 (Capability) | - AgentSkill, 工具方法 业务逻辑封装 | 资源层 (Resource) | - 数据库 外部API 文件系统 向量库 模型服务资源层这是你的数据和服务基础。包括数据库连接、外部系统API、文件存储、向量数据库以及大模型服务本身。这一层要保证稳定、高效。能力层这是最核心的编码层。你的主要工作就是设计Skill。每个Skill应该对应一个原子能力如“查询用户订单”、“发送邮件”、“生成图表”。有清晰的输入输出契约用Java方法签名和ToolParam描述来定义。包含完整的错误处理资源层可能出错Skill要能捕获异常并返回结构化的错误信息供Agent理解。可独立测试无需启动整个Agent就能对Skill进行单元测试。智能层这是“大脑”所在。你通过编写系统提示词来定义Agent的角色、目标、行为规范和可用工具列表。你还可以选择不同的Agent Executor如ReAct, Plan-and-Execute来调整推理模式。这一层的核心是Prompt工程和流程设计。表现层如何暴露你的Agent。可以是同步的HTTP API也可以是异步的消息队列消费者或者集成到聊天界面中。这一层要处理协议转换、认证鉴权、限流熔断。开发时应该自底向上先确保资源层和能力层的Skill稳定可靠再设计智能层的Prompt最后暴露表现层接口。4.2 Skill设计的“三要三不要”要“单一职责”一个Skill只做一件事。getUserProfile和updateUserProfile应该分成两个Skill。这能让模型更准确地理解何时调用它。要“描述精准”Tool的description是给模型看的API文档。避免模糊词汇。对比差“处理用户数据”。好“根据用户ID从‘users’表中查询并返回用户的姓名、邮箱和注册日期。”要“防御性编程”假设模型的输入可能是奇怪的、不完整的。在Skill方法内部做好参数校验、空值处理、异常捕获并返回对模型友好的错误信息例如“错误未找到用户ID为‘abc’的记录”。不要“过于复杂”避免在一个Skill里实现冗长的业务流程。如果流程复杂应该拆分成多个Skill让Agent来协调调用。不要“依赖隐式上下文”Skill方法参数应尽可能明确。如果需要会话状态应通过ToolParam显式传递或从AgentContext中获取。不要“忽略成本”如果Skill内部需要调用昂贵的操作如全表扫描、调用高额API要在设计时考虑缓存、限流或异步化。4.3 Prompt工程的核心为确定性而设计在Agent开发中Prompt的目标是降低模型行为的不确定性引导它按照你设定的可靠路径执行。明确指令清晰告诉Agent“你是谁”、“你的目标是什么”、“你可以用什么工具”、“步骤是什么”。使用编号列表、示例Few-shot来强化理解。输出格式约束要求模型以特定格式如JSON返回工具调用的思考过程这能极大简化框架的解析逻辑。Alibaba Agent框架通常已经处理了这部分。设定边界明确告诉Agent“什么不能做”。例如“你只能使用我提供的工具不能编造工具。”“你不能执行任何删除数据的操作除非用户明确确认。”迭代优化将Agent在实际对话中犯的错如错误调用工具、忽略关键信息作为负面样本补充到系统提示词中进行修正。这是一个持续的过程。4.4 测试策略从单元到集成Skill单元测试像测试普通Service一样测试每个SkillMock掉外部依赖数据库、API。确保在各种正常和异常输入下Skill都能返回预期结果。Agent集成测试模拟完整的用户输入启动一个轻量级的测试上下文使用内存向量库、Mock模型客户端验证Agent能否正确调用Skill并生成合理输出。重点测试流程是否通畅。端到端测试在接近生产的环境中进行测试使用真实的模型但可能是较低成本的模型验证整个链路的性能和效果。这类测试成本高主要用于关键场景。“对抗性”测试故意输入模糊、矛盾、有歧义的问题观察Agent的行为用于发现Prompt和Skill设计的盲区。回到我们最初的问题。Spring AI Alibaba Agent Framework 的价值在于它提供了一条用Java工程化思维构建AI Agent的清晰路径。它没有消除AI应用固有的不确定性而是通过框架的约束和引导将这种不确定性控制在一个可管理、可调试、可迭代的范围内。它可能不是最快上手的框架但很可能是最适合在既有Java体系中构建严肃AI应用的那个选择。你的重点不应该再是纠结于如何解析模型的JSON响应而是如何设计好一个个职责清晰的Skill如何编写能稳定引导模型的Prompt以及如何让这个智能体系统融入你现有的运维、监控和安全体系。开始行动的最佳方式就是从定义一个最小的、有价值的Skill开始。比如先让你的Agent学会查询公司内部的知识库。当它跑通的那一刻你会对“智能体”有完全不同的、更实在的理解。