# spring-ai-alibaba-example

**Repository Path**: longrenbang_mark/spring-ai-alibaba-example

## Basic Information

- **Project Name**: spring-ai-alibaba-example
- **Description**: Spring ai alibaba的示例
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: JAVA-AI

## README

# Spring AI Alibaba Example

基于 Spring AI Alibaba 的分布式 AI 代理通信示例项目，展示了 Agent-to-Agent (A2A) 通信和 Model Context Protocol (MCP) 的实现。

## 项目架构

### 模块结构

```
spring-ai-alibaba-example/
├── spring-ai-alibaba-common/          # 公共配置模块
├── spring-ai-alibaba-agent/           # AI 代理模块
│   ├── agent-nacos-register/          # 标准 A2A 代理注册服务
│   ├── agent-nacos-a2a-discovery/     # 标准 A2A 代理发现服务
│   ├── agent-nacos-agentcard-register/# AgentCard 注册服务
│   └── agent-nacos-agentcard-discovery/# AgentCard 发现服务
├── spring-ai-alibaba-graph/           # AI 图计算模块
│   ├── human-node/                    # 人机交互节点
│   ├── mcp-node/                      # MCP 协议节点
│   └── parallel-node/                 # 并行处理节点
├── spring-ai-alibaba-nacos-prompt/    # 基于 Nacos 的 Prompt 模板热更新示例
├── spring-ai-alibaba-chat-memory/     # 会话记忆示例（JDBC/Redis 等）
├── spring-ai-alibaba-vectorstore/     # 向量存储示例
└── spring-ai-alibaba-mcp/             # MCP 协议模块
    ├── mcp-nacos-register/            # MCP 服务注册
    └── mcp-nacos-discovery/           # MCP 服务发现
```

### 核心组件

- **Common Module**: 统一配置管理，包含 Nacos 和 Agent 配置属性
- **Agent Module**: 实现 A2A 协议的代理注册、发现和通信
- **Graph Module**: 实现基于图计算的 AI 处理流程，支持多种节点类型和并行处理
- **MCP Module**: 实现 Model Context Protocol 的服务注册和发现
- **Nacos Prompt Module**: 通过 Nacos 动态管理 Prompt 模板，运行时热更新
- **Chat Memory/VectorStore**: 演示记忆能力与向量检索的集成

### 模块详细说明

#### 1. Common 模块 (spring-ai-alibaba-common)

Common 模块提供了项目的公共配置和工具类，确保各模块间的配置一致性。

- **配置管理**: 统一的 Nacos 连接配置和 Agent 属性配置
- **工具类**: 公共的工具方法和常量定义

#### 2. Agent 模块 (spring-ai-alibaba-agent)

Agent 模块实现了完整的 A2A (Agent-to-Agent) 通信协议，支持代理间的服务注册、发现和通信。

- **agent-nacos-register**: 标准 A2A 代理注册服务，提供基础的代理注册功能
- **agent-nacos-a2a-discovery**: 标准 A2A 代理发现服务，实现代理间的服务发现
- **agent-nacos-agentcard-register**: AgentCard 注册服务，提供增强的代理卡片注册功能
- **agent-nacos-agentcard-discovery**: AgentCard 发现服务，支持代理卡片的发现和管理

#### 3. Graph 模块 (spring-ai-alibaba-graph)

Graph 模块实现了基于图计算的 AI 处理流程，支持多种节点类型和并行处理。

- **human-node**: 人机交互节点，处理用户输入和对话管理
- **mcp-node**: MCP 协议节点，集成 MCP 客户端进行工具调用
- **parallel-node**: 并行处理节点，支持多线程并行扩展处理

#### 4. MCP 模块 (spring-ai-alibaba-mcp)

MCP (Model Context Protocol) 模块实现了模型上下文协议，提供了标准化的模型通信接口。

- **mcp-nacos-register**: MCP 服务注册中心，负责 MCP 服务的注册和管理
- **mcp-nacos-discovery**: MCP 服务发现，提供 MCP 服务的发现和负载均衡

#### 5. Nacos Prompt 模块 (spring-ai-alibaba-nacos-prompt)

该模块通过 Nacos 托管 Prompt 模板，实现模板的动态下发与监听，结合 DashScope 模型生成流式响应。

- **配置来源**: `spring.config.import: "optional:nacos:prompt-config.json"`
- **Nacos 连接**: 使用 `spring.cloud.nacos.config.*` 参数连接到 `${TENCENT_CLOUD_IP}:8848`
- **Prompt 监听**: 通过 `spring.ai.alibaba.nacos.prompt.template.enabled: true` 启用监听
- **示例接口**: `GET /prompt/instruduce?personName=周杰伦`

接口位置：`spring-ai-alibaba-nacos-prompt/src/main/java/com/bruce/ai/alibaba/nacos/prompt/controller/PromptController.java:45`

返回内容为模型的流式输出，可通过浏览器或 curl 查看。

## 项目逻辑

### A2A (Agent-to-Agent) 通信流程

1. **代理注册**: Agent 通过 Nacos 注册中心注册自身信息和能力
2. **服务发现**: 其他 Agent 通过 Nacos 发现可用的代理服务
3. **直接通信**: Agent 之间建立直接的 HTTP 通信连接
4. **能力调用**: 通过标准化的 A2A 协议进行能力调用和数据交换

### MCP (Model Context Protocol) 流程

1. **MCP 服务注册**: MCP 服务器在 Nacos 中注册工具和资源
2. **客户端发现**: MCP 客户端发现并连接到可用的 MCP 服务
3. **工具调用**: 通过 MCP 协议调用远程工具和访问资源
4. **AI 集成**: 与大语言模型集成，提供增强的 AI 能力

### 关键特性

- **服务注册与发现**: 基于 Nacos 的分布式服务管理
- **负载均衡**: 支持多实例部署和负载均衡
- **熔断机制**: 内置熔断器模式，提高系统稳定性
- **重试机制**: 指数退避重试策略
- **多种认证**: 支持 JWT、OAuth2、API Key 等认证方式
- **异步通信**: 支持同步和异步调用模式

## 环境要求

### 基础环境

- **Java**: JDK 21+
- **Maven**: 3.6+
- **Spring Boot**: 3.4.0
- **Spring AI**: 1.0.0
- **Spring AI Alibaba**: 1.0.0.4

### 外部依赖

- **Nacos Server**: 2.0+ (服务注册与发现)
- **通义千问 API**: 阿里云大模型服务 (需要 API Key)

### 环境变量配置

| 变量名 | 描述 | 示例值 |
|--------|------|--------|
| `TENCENT_CLOUD_IP` | Nacos 服务器地址 | `127.0.0.1` 或 `139.199.227.184` |
| `NACOS_NAMESPACE` | Nacos 命名空间 | `dev` |
| `NACOS_USERNAME` | Nacos 用户名 | `nacos` |
| `NACOS_PASSWORD` | Nacos 密码 | `nacos` |
| `TONGYI_AI_KEY` | 通义千问 API Key | `sk-xxx` |
| `AGENT_NAME` | 代理名称 | `asurada-agent-test-9375` |
| `TARGET_AGENT_NAME` | 目标代理名称 | `asurada-agent-test-9375` |

## 快速开始

### 1. 环境准备

```bash
# 启动 Nacos Server (Docker)
docker run --name nacos -d \
  -p 8848:8848 \
  -p 9848:9848 \
  -e MODE=standalone \
  nacos/nacos-server:v2.3.0

# 设置环境变量
export TENCENT_CLOUD_IP=127.0.0.1
export NACOS_NAMESPACE=dev
export NACOS_USERNAME=nacos
export NACOS_PASSWORD=nacos
export TONGYI_AI_KEY=your-api-key
```

### 2. 编译项目

```bash
# 编译公共模块
cd spring-ai-alibaba-common
mvn clean install -DskipTests

# 编译整个项目
cd ..
mvn clean compile
```

### 3. 启动服务

```bash
# 启动 AgentCard 注册服务
cd spring-ai-alibaba-agent/agent-nacos-agentcard-register
AGENT_NAME=asurada-agent-test-9375 mvn spring-boot:run

# 启动 AgentCard 发现服务
cd ../agent-nacos-agentcard-discovery
TARGET_AGENT_NAME=asurada-agent-test-9375 mvn spring-boot:run

# 启动 MCP 注册服务
cd ../../spring-ai-alibaba-mcp/mcp-nacos-register
mvn spring-boot:run

# 启动 MCP 发现服务
cd ../mcp-nacos-discovery
mvn spring-boot:run

# 启动 Nacos Prompt 模板服务
cd ../../spring-ai-alibaba-nacos-prompt
mvn spring-boot:run
```

### 4. 验证服务

- **Nacos 控制台**: http://localhost:8848/nacos (nacos/nacos)
- **AgentCard 注册服务**: http://localhost:9093/health
- **AgentCard 发现服务**: http://localhost:9098
- **MCP 注册服务**: http://localhost:8081
- **MCP 发现服务**: http://localhost:8085
- **Nacos Prompt 服务**: http://localhost:10010
  - 示例接口: http://localhost:10010/prompt/instruduce?personName=周杰伦

## 服务端口

| 服务 | 端口 | 描述 |
|------|------|------|
| agent-nacos-register | 9999 | 标准 A2A 代理注册 |
| agent-nacos-a2a-discovery | - | 标准 A2A 代理发现 |
| agent-nacos-agentcard-register | 9093 | AgentCard 注册服务 |
| agent-nacos-agentcard-discovery | 9098 | AgentCard 发现服务 |
| mcp-nacos-register | 8081 | MCP 服务注册 |
| mcp-nacos-discovery | 8085 | MCP 服务发现 |
| nacos-prompt | 10010 | 动态 Prompt 模板服务 |
| human-node | 8087 | 人机交互节点服务 |
| mcp-node | 8088 | MCP 协议节点服务 |
| parallel-node | 8089 | 并行处理节点服务 |

## 配置说明（Nacos Prompt）

- 在 `spring-ai-alibaba-nacos-prompt/src/main/resources/application.yml` 中，`spring.config.import` 使用 Nacos 的 `prompt-config.json`：
  - 连接参数通过 `spring.cloud.nacos.config.server-addr=${TENCENT_CLOUD_IP}:8848` 与 `namespace=dev` 指定
  - 监听开关通过 `spring.ai.alibaba.nacos.prompt.template.enabled=true` 启用
- 在 Nacos 控制台 `dev` 命名空间下创建 `dataId=prompt-config.json`，示例：
  ```json
  {
    "templates": [
      {
        "name": "instruduce",
        "description": "人物简介",
        "template": "请简单介绍一下{{personName}}，100字以内。"
      }
    ]
  }
  ```

## 故障排除

- `config[dataId=prompt-config.json] is empty`：Nacos 中未创建或内容为空，按上文示例创建后重试
- `Port 10010 was already in use`：释放占用端口后重启
- BeanPostProcessor 警告：Spring Cloud Alibaba 在初始化阶段的提示，属正常现象，不影响功能

## 技术栈

- **框架**: Spring Boot 3.4.0, Spring AI 1.0.0
- **服务发现**: Nacos 3.1.0+
- **AI 模型**: 阿里云通义千问 (DashScope)
- **通信协议**: HTTP/HTTPS, A2A Protocol, MCP Protocol
- **序列化**: Jackson JSON
- **HTTP 客户端**: OkHttp 4.12.0
- **构建工具**: Maven 3.6+

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。