阿里 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 Alibaba

1.1 Gradle 依赖配置（Kotlin DSL）

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

plugins {
    java
    id("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 {
    // 基础 Web
    implementation("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: demo

  ai:
    dashscope:
      api-key: ${DASHSCOPE_API_KEY:your-api-key-here}  # DashScope API Key
      chat:
        options:
          model: qwen-max        # 可选: qwen-turbo, qwen-plus, qwen-max
          temperature: 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 Alibaba
      url: 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: DEBUG
    org.springframework.ai: DEBUG

---

1.3 关键配置项说明

配置段	作用	注意事项
spring.ai.dashscope.api-key	阿里云 DashScope 身份凭证	务必走环境变量，勿提交到 Git
spring.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 日志	生产环境建议改为 INFO

---

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

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

DASHSCOPE_API_KEY=sk-your-key-here

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

export DASHSCOPE_API_KEY=sk-your-key-here
./gradlew bootRun

API Key 获取方式：

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

---

1.5 依赖作用速查表

依赖坐标	作用说明	是否必须
spring-boot-starter-web	提供 Spring MVC / Tomcat 基础 Web 能力	✅
spring-ai-alibaba-agent-framework	Spring AI Alibaba 的 Agent 核心框架，封装 Prompt、ChatClient、Memory 等	✅
spring-ai-alibaba-starter-dashscope	对接阿里云 DashScope（通义千问 Qwen 系列模型）的 Starter	✅
spring-ai-alibaba-starter-a2a-nacos	A2A (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.json5（JSON5 格式，支持注释），而非前端常见的 package.json。修改后需执行同步或安装命令才能生效。

2.2 安装依赖

方式 ：命令行（推荐）

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

cd entry
ohpm install @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 层正常工作：

package com.example.demo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RequestMapping;

@RestController
@RequestMapping("/")
public class TestController {

    @GetMapping("/test")
    public String test() {
        return "Hello World! AgenUI Server is running.";
    }
}

---

四、启动与验证

4.1 启动后端服务

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

./gradlew bootRun

4.2 验证接口

浏览器或终端访问：

curl http://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 预告）

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