阿里 AgenUI 开源库前后端实战教程 —— Day 2：后端接入 Spring AI Alibaba 鸿蒙端引入 AgenUI

Day 1 我们完成了三端工程初始化。今天同时推进后端与鸿蒙原生端后端引入Spring AI Alibaba全家桶配置通义千问 DashScope 与 A2A Nacos鸿蒙端在 HarmonyOS 工程中引入AgenUI组件库为 Day 3 搭建聊天界面做准备。0. 今日目标端事项内容后端依赖集成Spring AI Alibaba BOM DashScope A2A Nacos AgentScope后端配置补全application.yml中配置 DashScope API Key 与模型参数后端接口验证启动服务访问/test确认基础 Web 层无异常鸿蒙组件库引入通过 ohpm 安装agenui/agenui完成依赖同步一、后端工程集成 Spring AI Alibaba1.1 Gradle 依赖配置Kotlin DSL打开agen-ui-server/build.gradle.kts替换为以下内容plugins{javaid(org.springframework.boot)version3.5.14id(io.spring.dependency-management)version1.1.7}groupcom.Sophic_techversion0.0.1-SNAPSHOTdescriptiondemojava{toolchain{languageVersionJavaLanguageVersion.of(17)}}repositories{mavenCentral()// Spring 与阿里云相关仓库用于拉取里程碑/快照版本maven{urluri(https://repo.spring.io/milestone)}maven{urluri(https://repo.spring.io/snapshot)}maven{urluri(https://oss.sonatype.org/content/repositories/snapshots)}}// 统一声明 Spring AI Alibaba 版本方便后续全局升级extra[springAiAlibabaVersion]1.1.2.0dependencyManagement{imports{// 通过 BOM 统一管理 Spring AI Alibaba 全家桶版本mavenBom(com.alibaba.cloud.ai:spring-ai-alibaba-bom:${property(springAiAlibabaVersion)})}}dependencies{// 基础 Webimplementation(org.springframework.boot:spring-boot-starter-web)// Spring AI Alibaba 核心Agent 框架implementation(com.alibaba.cloud.ai:spring-ai-alibaba-agent-framework)// 通义千问 DashScope 接入由 BOM 管理版本无需硬编码implementation(com.alibaba.cloud.ai:spring-ai-alibaba-starter-dashscope)// A2A (Agent-to-Agent) Nacos 服务注册与发现implementation(com.alibaba.cloud.ai:spring-ai-alibaba-starter-a2a-nacos)// AgentScope 多 Agent 协作框架implementation(io.agentscope:agentscope:1.0.11)// 测试testImplementation(org.springframework.boot:spring-boot-starter-test)testRuntimeOnly(org.junit.platform:junit-platform-launcher)}tasks.withTypeTest{useJUnitPlatform()}工程化提示spring-ai-alibaba-starter-dashscope已由 BOM 锁定版本建议移除后缀的:1.1.2.0避免版本漂移。若后续需升级只需修改extra[springAiAlibabaVersion]一处即可。1.2 完整配置文件application.yml在src/main/resources/application.yml中写入以下内容。所有敏感信息API Key、Nacos 密码均通过环境变量注入避免硬编码入库spring:application:name:demoai:dashscope:api-key:${DASHSCOPE_API_KEY:your-api-key-here}# DashScope API Keychat:options:model:qwen-max# 可选: qwen-turbo, qwen-plus, qwen-maxtemperature:0.7# 温度参数控制生成随机性 (0~1)max-tokens:2000# 单次最大输出 token 数# Spring AI Alibaba A2A 配置spring-ai-alibaba:a2a:enabled:true# A2A Agent Card 配置用于服务发现与自描述agent-card:name:${spring.application.name}description:AI Agent powered by Spring AI Alibabaurl:http://localhost:${server.port:8080}# Nacos 服务注册配置 (A2A 多 Agent 通信依赖)nacos:server-addr:${NACOS_SERVER_ADDR:127.0.0.1:8848}namespace:${NACOS_NAMESPACE:}username:${NACOS_USERNAME:nacos}password:${NACOS_PASSWORD:nacos}server:port:8080# 日志配置开发阶段开启 DEBUG方便排查 Spring AI 调用链logging:level:com.alibaba.cloud.ai:DEBUGorg.springframework.ai:DEBUG1.3 关键配置项说明配置段作用注意事项spring.ai.dashscope.api-key阿里云 DashScope 身份凭证务必走环境变量勿提交到 Gitspring.ai.dashscope.chat.options.model通义千问模型版本qwen-max能力最强qwen-turbo性价比最高spring-ai-alibaba.a2a.enabled开启 A2A (Agent-to-Agent) 能力单机开发可设为false跳过 Nacos 依赖spring-ai-alibaba.a2a.nacos.*Nacos 服务注册与发现地址若未部署 Nacos可注释掉此段不影响单 Agent 运行logging.level.*开启 DEBUG 日志生产环境建议改为INFO1.4 本地环境变量设置推荐在 IDEA 的Run/Debug Configurations→Environment variables中添加DASHSCOPE_API_KEYsk-your-key-here或在终端启动时临时导出exportDASHSCOPE_API_KEYsk-your-key-here ./gradlew bootRunAPI Key 获取方式登录 阿里云 DashScope 控制台进入API-KEY管理页创建新的 Key1.5 依赖作用速查表依赖坐标作用说明是否必须spring-boot-starter-web提供 Spring MVC / Tomcat 基础 Web 能力✅spring-ai-alibaba-agent-frameworkSpring AI Alibaba 的 Agent 核心框架封装 Prompt、ChatClient、Memory 等✅spring-ai-alibaba-starter-dashscope对接阿里云 DashScope通义千问 Qwen 系列模型的 Starter✅spring-ai-alibaba-starter-a2a-nacosA2A (Agent-to-Agent) 协议 Nacos 服务发现用于多 Agent 分布式协作按需agentscope:1.0.11阿里开源的多 Agent 编排框架支持 Role-Play、Workflow 等高级协作模式按需二、鸿蒙原生端引入 AgenUI 组件库2.1 修改 oh-package.json5在鸿蒙项目的entry 模块下找到oh-package.json5添加agenui/agenui依赖{ name: entry, version: 1.0.0, description: Please describe the basic information., main: , author: , license: , dependencies: { agenui/agenui: 0.9.9 } }注意鸿蒙工程使用oh-package.json5JSON5 格式支持注释而非前端常见的package.json。修改后需执行同步或安装命令才能生效。2.2 安装依赖方式 命令行推荐在 entry 目录下打开终端执行 ohpm 安装命令cdentry ohpminstallagenui/agenui安装完成后DevEco Studio 会自动同步依赖你可以在entry/oh_modules/.ohpm/agenuiagenui0.9.9目录下查看组件库源码。2.3 验证安装安装成功后在任意 ArkTS 页面如Index.ets中尝试导入组件import{AgenUI}fromagenui/agenui;若 IDE 无红色报错提示即表示组件库引入成功。具体 UI 组件的使用将在 Day 3 展开。ohpm 仓库地址https://ohpm.openharmony.cn/#/cn/detail/agenui%2Fagenui三、后端首接口验证TestController在src/main/java/com/example/demo/下创建测试控制器确认 Spring Web 层正常工作packagecom.example.demo;importorg.springframework.web.bind.annotation.GetMapping;importorg.springframework.web.bind.annotation.RestController;importorg.springframework.web.bind.annotation.RequestMapping;RestControllerRequestMapping(/)publicclassTestController{GetMapping(/test)publicStringtest(){returnHello World! AgenUI Server is running.;}}四、启动与验证4.1 启动后端服务在 IDEA 中点击运行或执行./gradlew bootRun4.2 验证接口浏览器或终端访问curlhttp://localhost:8080/test预期返回Hello World! AgenUI Server is running.若返回正常说明✅ Gradle 依赖无冲突✅application.yml配置被正确加载无解析报错✅ Spring Boot 启动成功✅ 基础 Controller 层可正常响应五、Day 2 小结端完成项状态后端Spring AI Alibaba BOM 引入✅后端DashScope / A2A Nacos / AgentScope 依赖就位✅后端application.yml完整配置含模型参数、A2A、Nacos、日志✅后端环境变量注入规范API Key 不走硬编码✅后端/test接口验证通过✅鸿蒙entry 模块引入agenui/agenui:0.9.9✅鸿蒙ohpm 依赖同步完成IDE 无报错✅六、下一步Day 3 预告后端编写第一个 AI Chat API使用ChatClient调用通义千问实现流式对话SSE鸿蒙端使用 AgenUI 组件库搭建聊天界面骨架对接后端/chat接口Flutter 端引入 AgenUI Flutter 组件库配置 Dart HTTP 客户端与后端对接提示若 Gradle 同步时提示spring-ai-alibaba-starter-a2a-nacos或agentscope无法解析请检查网络是否可访问阿里云 Maven 仓库或尝试切换至阿里云国内镜像源。若本地未部署 Nacos可临时将spring-ai-alibaba.a2a.enabled设为false不影响单服务启动。鸿蒙端 ohpm 安装失败时请检查 DevEco Studio 的Settings → OHPM → Registry是否指向https://ohpm.openharmony.cn。AGenUI代码仓库https://github.com/AGenUI/AGenUI