# SpringAiAlibabaBase

**Repository Path**: jiawy401/spring-ai-alibaba-base

## Basic Information

- **Project Name**: SpringAiAlibabaBase
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-10
- **Last Updated**: 2026-01-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring AI Alibaba 多智能体协作平台

## 📋 项目简介

这是一个基于Spring AI Alibaba构建的多智能体协作平台，支持Agent自动注册、MCP Server集成、公有记忆管理等功能。该平台提供了完整的框架和工具，用于构建复杂的多Agent系统。

## ✨ 核心特性

- 🤖 **Agent框架**: 完整的Agent生命周期管理和异步执行
- 🔗 **Nacos集成**: Agent和MCP Server自动注册与发现
- 🛠️ **MCP支持**: MCP Tool适配器和Resource管理
- 📊 **工作流编排**: 支持多Agent协作工作流
- 💬 **消息通信**: Agent间异步消息通信
- 🧠 **记忆系统**: 基于Mem0的公有记忆（开发中）

## 🚀 快速开始

### 前置要求

- Java 17+
- Maven 3.8+
- Docker (用于运行Nacos)

### 1. 启动Nacos

```bash
docker run -d --name nacos -p 8848:8848 -p 9848:9848 \
  -e MODE=standalone \
  -e PREFER_HOST_NAME=localhost \
  nacos/nacos-server:v2.2.0
```

### 2. 构建项目

```bash
cd spring-ai-alibaba-base
mvn clean install
```

### 3. 运行示例应用

```bash
cd spring-ai-alibaba-examples
mvn spring-boot:run
```

应用将在 `http://localhost:8081` 启动

### 4. 验证安装

访问Nacos控制台: `http://localhost:8848/nacos`
- 用户名: nacos
- 密码: nacos

在服务列表中应该能看到:
- `agent-agent-1`
- `agent-agent-2`

## 📁 项目结构

```
spring-ai-alibaba-base/
├── md/                                  # 文档目录
│   ├── plans.md                        # 总体规划
│   ├── Phase1.md                       # Phase 1详解
│   ├── Phase2.md                       # Phase 2详解
│   ├── API_REFERENCE.md                # API参考
│   ├── PROGRESS.md                     # 进度总结
│   └── SUMMARY.md                      # 完成总结
├── spring-ai-alibaba-core/             # 核心框架模块
│   ├── src/main/java/com/alibaba/ai/
│   │   ├── agent/                      # Agent框架
│   │   ├── registry/                   # Nacos集成
│   │   ├── mcp/                        # MCP支持
│   │   ├── memory/                     # 记忆系统
│   │   ├── orchestration/              # 工作流编排
│   │   ├── communication/              # 消息通信
│   │   └── config/                     # 配置类
│   └── pom.xml
├── spring-ai-alibaba-agents/           # Agent工厂模块
│   ├── md/
│   │   └── description.md              # 模块描述文档
│   ├── src/main/java/com/alibaba/ai/agents/
│   │   ├── AgentFactory.java           # Agent工厂类
│   │   ├── GeneralAgent.java           # 通用Agent
│   │   ├── MCPToolAgent.java           # MCP工具Agent
│   │   ├── CoordinatorAgent.java       # 协调Agent
│   │   ├── DataProcessingAgent.java    # 数据处理Agent
│   │   └── DecisionAgent.java          # 决策Agent
│   └── pom.xml
├── spring-ai-alibaba-examples/         # 示例应用模块
│   ├── src/main/java/com/alibaba/ai/examples/
│   │   ├── agent/                      # 示例Agent
│   │   └── Application.java            # 启动类
│   └── pom.xml
├── pom.xml                             # 父项目配置
├── SETUP.md                            # 快速开始指南
└── README_CN.md                        # 本文档
```

## 📚 文档导航

| 文档 | 描述 |
|------|------|
| [plans.md](md/plans.md) | 项目总体规划和架构设计 |
| [Phase1.md](md/Phase1.md) | 基础框架详细说明 |
| [Phase2.md](md/Phase2.md) | MCP集成详细说明 |
| [API_REFERENCE.md](md/API_REFERENCE.md) | 完整API文档 |
| [PROGRESS.md](md/PROGRESS.md) | 项目进度跟踪 |
| [SUMMARY.md](md/SUMMARY.md) | 完成总结 |
| [SETUP.md](SETUP.md) | 快速开始指南 |

## 🎯 核心概念

### Agent
Agent是系统中的基本执行单元，代表一个具有特定功能的智能体。每个Agent可以：
- 接收和处理消息
- 执行特定的业务逻辑
- 与其他Agent通信
- 使用MCP Tool

### MCP Tool
MCP (Model Context Protocol) Tool是可复用的功能模块，可以被Agent调用。支持：
- 动态注册和卸载
- 参数验证
- 异步执行
- 错误处理

### Workflow
工作流定义了多个Agent的协作流程，支持：
- 步骤依赖关系
- 参数传递
- 并行执行
- 结果聚合

### Memory
公有记忆系统允许Agent间共享知识和信息，支持：
- 记忆存储和检索
- 记忆搜索
- 版本管理
- 权限控制

## 💻 使用示例

### 使用Agent工厂创建Agent

```java
import com.alibaba.ai.agents.AgentFactory;
import com.alibaba.ai.agent.Agent;

// 创建通用Agent
Agent generalAgent = AgentFactory.createGeneralAgent(
    "general-agent-1",
    "General Agent",
    "A general purpose agent"
);

// 创建数据处理Agent
Agent dataAgent = AgentFactory.createDataProcessingAgent(
    "data-agent-1",
    "Data Processing Agent",
    "Agent for data processing"
);

// 创建决策Agent
Agent decisionAgent = AgentFactory.createDecisionAgent(
    "decision-agent-1",
    "Decision Agent",
    "Agent for making decisions"
);
```

### 创建自定义Agent

```java
public class CustomAgent extends Agent {
    public CustomAgent(String id, String name, String description) {
        super(id, name, description);
    }

    @Override
    public CompletableFuture<AgentMessage> execute(AgentMessage message) {
        return CompletableFuture.supplyAsync(() -> {
            // 处理消息
            String result = processMessage(message.getContent());
            
            return AgentMessage.builder()
                .id(UUID.randomUUID().toString())
                .fromAgent(this.getId())
                .toAgent(message.getFromAgent())
                .content(result)
                .type(AgentMessage.MessageType.RESPONSE)
                .timestamp(LocalDateTime.now())
                .build();
        });
    }

    private String processMessage(String content) {
        // 业务逻辑
        return "Processed: " + content;
    }
}
```

### 注册MCP Tool

```java
MCPToolAdapter toolAdapter = context.getBean(MCPToolAdapter.class);

MCPTool tool = MCPTool.builder()
    .id("my-tool")
    .name("My Tool")
    .description("A custom tool")
    .serverId("mcp-server-1")
    .build();

MCPTool.ToolExecutor executor = params -> {
    // Tool实现
    return "Tool result";
};

toolAdapter.registerTool(tool, executor);
```

### 创建工作流

```java
Workflow workflow = Workflow.builder()
    .id("my-workflow")
    .name("My Workflow")
    .steps(List.of(
        Workflow.WorkflowStep.builder()
            .id("step-1")
            .agentId("agent-1")
            .action("action-1")
            .dependencies(List.of())
            .build(),
        Workflow.WorkflowStep.builder()
            .id("step-2")
            .agentId("agent-2")
            .action("action-2")
            .dependencies(List.of("step-1"))
            .build()
    ))
    .build();

WorkflowExecutor executor = context.getBean(WorkflowExecutor.class);
CompletableFuture<WorkflowResult> result = executor.execute(workflow);
```

## 🔧 配置

### application.yml

```yaml
spring:
  application:
    name: spring-ai-alibaba-core
  cloud:
    nacos:
      discovery:
        server-addr: localhost:8848
        namespace: ai-agents
      config:
        server-addr: localhost:8848
        namespace: ai-agents

server:
  port: 8080

logging:
  level:
    root: INFO
    com.alibaba.ai: DEBUG
```

## 📊 项目进度

| Phase | 名称 | 状态 | 完成度 |
|-------|------|------|--------|
| 1 | 基础框架与Nacos集成 | ✅ 完成 | 100% |
| 2 | MCP Server集成与Tool适配 | ✅ 完成 | 100% |
| 3 | 记忆系统 | ⏳ 进行中 | 0% |
| 4 | 协作编排 | ⏳ 待开始 | 0% |
| 5 | 通信与事件 | ⏳ 待开始 | 0% |
| 6 | 监控与优化 | ⏳ 待开始 | 0% |
| 7 | 示例与文档 | ⏳ 待开始 | 0% |

**总体完成度**: 28.6% (2/7 Phases)

## 🛠️ 技术栈

| 组件 | 版本 |
|------|------|
| Spring Boot | 3.2.0 |
| Spring Cloud | 2023.0.0 |
| Spring AI | 0.8.1 |
| Nacos | 2023.0.0.0 |
| Java | 17+ |
| Maven | 3.8+ |

## 📈 性能指标

| 操作 | 平均时间 |
|------|---------|
| Agent注册 | < 100ms |
| Agent执行 | 取决于业务 |
| Tool执行 | < 50ms |
| 工作流执行 | O(n) |
| 消息发布 | < 10ms |

## 🐛 常见问题

### Q: Nacos连接失败怎么办？
A: 确保Nacos服务正在运行，检查配置文件中的 `server-addr`

### Q: Agent未注册到Nacos？
A: 检查日志中是否有注册错误，确保Nacos命名空间 `ai-agents` 存在

### Q: 如何创建自定义Agent？
A: 继承Agent类并实现execute方法

### Q: 如何在Agent中使用MCP Tool？
A: 注入MCPToolAdapter并调用executeTool方法

## 🤝 贡献指南

欢迎提交Issue和Pull Request！

### 代码规范
- 使用Lombok简化代码
- 添加适当的日志记录
- 遵循最小化原则
- 编写清晰的注释

### 提交规范
- 每个Phase完成后更新文档
- 更新plans.md中的完成状态
- 创建Phase文档记录详细信息

## 📝 许可证

MIT License

## 📞 联系方式

如有问题或建议，请提交Issue或Pull Request。

## 🎓 学习资源

- [Spring Boot官方文档](https://spring.io/projects/spring-boot)
- [Spring Cloud官方文档](https://spring.io/projects/spring-cloud)
- [Spring AI官方文档](https://spring.io/projects/spring-ai)
- [Nacos官方文档](https://nacos.io/zh-cn/)

## 🚀 下一步

1. 阅读 [SETUP.md](SETUP.md) 快速开始
2. 查看 [API_REFERENCE.md](md/API_REFERENCE.md) 了解API
3. 学习 [Phase1.md](md/Phase1.md) 和 [Phase2.md](md/Phase2.md)
4. 创建自己的Agent和Tool
5. 构建复杂的工作流

---

**项目状态**: 进行中 ✅
**最后更新**: 2024年
**维护者**: Spring AI Alibaba Team