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

Day 1 我们完成了三端工程初始化。今天同时推进后端与鸿蒙原生端：

• 后端：引入Spring AI Alibaba全家桶，配置通义千问 DashScope 与 A2A Nacos；
• 鸿蒙端：在 HarmonyOS 工程中引入AgenUI组件库，为 Day 3 搭建聊天界面做准备。

0. 今日目标

一、后端工程：集成 Spring AI Alibaba

1.1 Gradle 依赖配置（Kotlin DSL）

打开agen-ui-server/build.gradle.kts，替换为以下内容：

plugins{javaid("org.springframework.boot")version"3.5.14"id("io.spring.dependency-management")version"1.1.7"}group="com.Sophic_tech"version="0.0.1-SNAPSHOT"description="demo"java{toolchain{languageVersion=JavaLanguageVersion.of(17)}}repositories{mavenCentral()// Spring 与阿里云相关仓库，用于拉取里程碑/快照版本maven{url=uri("https://repo.spring.io/milestone")}maven{url=uri("https://repo.spring.io/snapshot")}maven{url=uri("https://oss.sonatype.org/content/repositories/snapshots")}}// 统一声明 Spring AI Alibaba 版本，方便后续全局升级extra["springAiAlibabaVersion"]="1.1.2.0"dependencyManagement{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.withType<Test>{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:DEBUG

1.3 关键配置项说明

1.4 本地环境变量设置（推荐）

在 IDEA 的Run/Debug Configurations→Environment variables中添加：

DASHSCOPE_API_KEY=sk-your-key-here

或在终端启动时临时导出：

exportDASHSCOPE_API_KEY=sk-your-key-here ./gradlew bootRun

API Key 获取方式：

1. 登录 阿里云 DashScope 控制台
2. 进入API-KEY管理页，创建新的 Key

1.5 依赖作用速查表

二、鸿蒙原生端：引入 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.json5（JSON5 格式，支持注释），而非前端常见的package.json。修改后需执行同步或安装命令才能生效。

2.2 安装依赖

方式 ：命令行（推荐）

在 entry 目录下打开终端，执行 ohpm 安装命令：

cdentry ohpminstall@agenui/agenui

安装完成后，DevEco Studio 会自动同步依赖，你可以在entry/oh_modules/.ohpm/@agenui+agenui@0.9.9目录下查看组件库源码。

2.3 验证安装

安装成功后，在任意 ArkTS 页面（如Index.ets）中尝试导入组件：

import{AgenUI}from'@agenui/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;@RestController@RequestMapping("/")publicclassTestController{@GetMapping("/test")publicStringtest(){return"Hello World! AgenUI Server is running.";}}

四、启动与验证

4.1 启动后端服务

在 IDEA 中点击运行，或执行：

./gradlew bootRun

4.2 验证接口

浏览器或终端访问：

curlhttp://localhost:8080/test

预期返回：

Hello World! AgenUI Server is running.

若返回正常，说明：

• ✅ Gradle 依赖无冲突
• ✅application.yml配置被正确加载（无解析报错）
• ✅ Spring Boot 启动成功
• ✅ 基础 Controller 层可正常响应

五、Day 2 小结

六、下一步（Day 3 预告）

1. 后端：编写第一个 AI Chat API，使用ChatClient调用通义千问实现流式对话（SSE）
2. 鸿蒙端：使用 AgenUI 组件库搭建聊天界面骨架，对接后端/chat接口
3. 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