# AerotopMultiAgents

**Repository Path**: starboot/aerotop-multi-agents

## Basic Information

- **Project Name**: AerotopMultiAgents
- **Description**: 🚀 AerotopMultiAgents - 企业级多智能体开发框架的模板项目
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-01-10
- **Last Updated**: 2026-02-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Agent, AI

## README

<div align="center">

# 🚀 AerotopMultiAgents - 企业级多智能体开发框架<span style="color:red">模板项目</span>

</div>
<div align="center">

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![AgentScope 1.0.10+](https://img.shields.io/badge/AgentScope-1.0.10+-green.svg)](https://github.com/modelscope/agentscope)
[![UV](https://img.shields.io/badge/uv-0.9.18-orange.svg)](https://github.com/astral-sh/uv)
[![Docker](https://img.shields.io/badge/docker-✓-blue.svg)](https://www.docker.com/)
[![Docker Compose](https://img.shields.io/badge/compose-✓-blue.svg)](https://docs.docker.com/compose/)

**基于AgentScope构建的下一代企业级多智能体开发框架的<span style="color:red">模板项目</span>**

[特性](#特性) • [快速开始](#快速开始) • [项目结构](#项目结构) • [部署指南](#部署指南) • [贡献指南](#贡献指南)

</div>

## 📖 项目简介

**AerotopMultiAgents** 是一个基于 [AgentScope](https://github.com/modelscope/agentscope) 框架构建的企业级多智能体开发框架的**模板项目**。针对当前**AgentScope多智能体开发框架**开源时间较短、社区资料不足的痛点，我提供了一套**完整、可扩展、生产就绪**的多智能体系统开发解决方案。

本项目不仅修复了原生 AgentScope 框架（v1.0.10）的已知问题，还提供了完整的开发范式、工程化最佳实践和容器化部署方案，帮助开发者快速构建和部署复杂的多智能体系统。

## ✨ 核心特性

### 🐛 框架增强
- **稳定性改进**：修复 AgentScope v1.0.10 的已知 BUG，提供更稳定的运行环境
- **性能优化**：优化智能体间通信机制，降低延迟，提高吞吐量

### 🏗️ 完整开发模板
- **即用型模板**：提供开箱即用的 MultiAgent 系统模板，支持快速启动和定制
- **模块化设计**：清晰的层次结构和代码规范，便于团队协作和维护

### 🌐 全场景覆盖
- **MCP 集成**：支持 Model Context Protocol，统一模型交互接口
- **RAG 增强**：内置检索增强生成流程，支持多种向量数据库
- **记忆系统**：短/长时记忆管理，支持对话历史和知识持久化
- **智能路由**：动态请求路由和负载均衡机制
- **技能库**：可扩展的技能插件系统，支持自定义功能扩展

### 👥 多用户管理
- **多租户支持**：完善的用户和会话隔离机制
- **会话持久化**：支持会话状态的保存和恢复
- **并发处理**：优化多用户并发访问性能

### 🐳 容器化部署
- **Dockerfile**：提供生产级容器镜像构建方案
- **Docker Compose**：一键式部署，集成记忆系统中间件（Neo4j、向量数据库等）
- **健康检查**：完善的健康检查和服务发现机制

### 🔌 开放兼容
- **OpenAI 兼容**：完整实现 OpenAI API 接口规范
- **流式响应**：支持 Server-Sent Events (SSE) 流式输出
- **通用客户端**：可接入任意 OpenAI 兼容的客户端和应用

### ⚙️ 配置管理
- **配置中心**：集中式配置管理，支持环境变量覆盖
- **数据类封装**：类型安全的配置对象，支持 IDE 智能提示
- **热重载**：支持运行时配置更新，无需重启服务

## 🚀 快速开始

### 前置要求

- Python 3.12 或更高版本
- [UV 包管理工具](https://github.com/astral-sh/uv)（推荐）
- 可选：Docker v2.39.4 和 Docker Compose 28.4.0
```bash
# docker compose version
Docker Compose version v2.39.4

# docker --version
Docker version 28.4.0, build d8eb465

# docker version
Client:
 Version:           28.4.0
 API version:       1.51
 Go version:        go1.24.7
<...>
```

### 方式一：使用 UV（推荐）

#### 1. 安装 UV

```bash
# 使用官方安装脚本
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或通过 pip 安装
pip install uv
```

#### 2. 克隆并安装项目

```bash
# 克隆项目
git clone https://github.com/*****/AerotopMultiAgents.git
cd AerotopMultiAgents

# 同步依赖（使用 uv）
uv sync

# 或使用传统方式
pip install -e .
```

#### 3. 配置环境

```bash
# 复制环境配置文件
cp .env.example .env

# 编辑配置文件，添加你的 API Keys 等配置
vim .env
```

#### 4. 运行示例

```bash
# 启动MCP Server服务
python ./mcp/mcp_add.py
python ./mcp/mcp_multiply.py

# 运行完整的多智能体系统
python main.py
```

### 方式二：Docker 启动

```bash
# 构建镜像
docker build -t aerotop-multiagents .

# 运行容器
docker run -p 10085:10085 \
  -e OPENAI_MODEL_THINKING=Qwen/Qwen3-32B \
  -e OPENAI_MODEL_INSTRUCTION=Qwen/Qwen2.5-32B-Instruct \
  -e OPENAI_MODEL_EMBEDDING=Qwen/Qwen3-Embedding-8B \
  -e OPENAI_MODEL_RERANK=BAAI/bge-reranker-v2-m3 \
  -e OPENAI_API_KEY=ms-ac180211-50aa-4a0e-99fc-**** \
  -e OPENAI_API_BASE_URL=https://api-inference.modelscope.cn/v1/ \
  -e DATA_FOR_SESSION=./data/session/session.db \
  -e DATA_FOR_LONG_MEMORY_PATH=./data/memory/qdrant_data \
  -e LOG_LEVEL=info \
  -e NEO4J_URI=bolt://neo4j:7687 \
  -e NEO4J_USER=neo4j \
  -e NEO4J_PASSWORD=aerotop \
  -e NEO4J_DATABASE=aerotop \
  -e MILVUS_HOST=milvus \
  -e MILVUS_PORT=19530 \
  -e MILVUS_COLLECTION_NAME=embeddings \
  -e MILVUS_VECTOR_DIMENSION=1536 \
  -v $(pwd)/data:/app/data \
  aerotop-multiagents
```

### 方式三：Docker Compose 启动（推荐生产使用）

```bash
# 一键启动所有服务（包括记忆系统中间件）
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f app

# 停止服务
docker-compose down
```

## 📁 项目结构

```
AerotopMultiAgents/                          # 主源码目录
├── agents/                                  # 智能体定义
│   ├── worker/                              # 智能体定义
│   │   ├── chat_agent.py                    # 通用智能体类
│   │   └── code_agent.py                    # 编程智能体
│   └── master_agent.py/                     # 主智能体
├── config/                                  # 系统配置
│   └── setting.py                           # 系统环境变量配置类
├── conversion/                              # 消息块转换目录
│   └── convert_to_text_block.py             # 工具使用转文本
├── data/                                    # 系统数据持久化存储
│   ├── memory/                              # 记忆系统持久化目录
│   ├── milvus/                              # 向量库数据持久化
│   ├── session/                             # 会话持久化
│   ├── get-docker.sh                        # docker安装脚本
│   └── neo4j.sh                             # 知识图谱安装脚本
├── doc/                                     # 系统技术白皮书（暂未编写）
├── docker/                                  # 系统依赖容器镜像
├── formatter/                               # 格式化目录
│   └── custom_openai_formatter.py           # 自定义格式化工具
├── hooks/                                   # 钩子目录
│   ├── agent/                               # 智能体钩子回调函数
│   │   └── pre_print.py                     # 格式化输出
│   └── tool/                                # 工具钩子回调函数
│       └── search_tool_post_func.py         # 工具钩子回调实例
├── knowledge/                               # 智能体知识系统目录
│   ├── chat_knowledge.py                    # 通用智能体知识系统
│   ├── coder_knowledge.py                   # 编程智能体知识系统
│   └──master_knowledge.py                   # 主智能体知识系统
├── mcp/                                     # MCP Server目录
│   ├──mcp_add.py                            # SSE MCP Server服务
│   └──mcp_multiply.py                       # streamable-http MCP Server服务
├── memory/                                  # 记忆系统
│   ├── long_term_memory/                    # 长时记忆系统
│   └── short_term_memory/                   # 短时记忆系统
├── models/                                  # 结构体模型目录
│   ├── chat_agent/                          # 通用智能体结构体模型目录
│   │   └── model.py                         # 通用智能体结构体模型
│   └── RoutingChoiceModel.py/               # 路由结构体模型
├── plans/                                   # 任务规划目录
│   └── main_manual_plan.py                  # 主智能体任务规划
├── prompts/                                 # 系统提示词目录
│   └── constants.py                         # 系统提示词枚举类
├── runtime/                                 # 系统运行时目录
│   └── runtime.py                           # 系统运行时类
├── session/                                 # 系统会话管理目录
│   └── sqlite_session.py                    # 会话持久化方案实现类
├── skill/                                   # 智能体技能目录
├── spi/                                     # 系统程序接口目录
│   └── aerotop_openai_token_counter.py      # 自定义token计数器
├── tools/                                   # 智能体工具目录
│   └── search_tool.py                       # 搜索工具
├── .env.example                             # 环境变量示例
├── .gitignore                               # git忽略文件
├── .python-version                          # 项目Python版本
├── docker-compose.yml                       # 完整编排配置
├── docker-healthcheck.sh                    # 健康状态监测脚本
├── Dockerfile                               # 生产环境 Dockerfile
├── LICENSE                                  # 开源协议
├── main.py                                  # 主程序入口
├── pyproject.toml                           # 项目配置和依赖
├── README.md                                # 项目说明
├── start.sh                                 # 系统启动脚本
└──  uv.lock                                 # UV 锁定文件
```

## 🐳 部署指南

### Docker Compose 详细配置

AerotopMiltiAgent项目的 `docker-compose.yml` 包含以下服务：

```yaml
version: '3.8'

# 定义网络，确保服务间可以相互通信
networks:
  app-network:
    driver: bridge

# 定义所有服务
services:
  # Neo4j 图数据库服务
  neo4j:
    image: neo4j:5.26.19-community
    container_name: neo4j-db
    restart: unless-stopped
    environment:
      # 设置 Neo4j 认证信息
      - NEO4J_AUTH=neo4j/aerotop
      # 允许从容器外部访问
      - NEO4J_ACCEPT_LICENSE_AGREEMENT=yes
      # 性能优化配置
      - NEO4J_server_memory_heap_initial__size=1G
      - NEO4J_server_memory_heap_max__size=2G
      - NEO4J_server_memory_pagecache_size=1G
      # 允许使用 APOC 插件
      - NEO4J_PLUGINS=apoc
    ports:
      # Bolt 协议端口（应用程序使用）
      - "7687:7687"
      # HTTP 端口（浏览器访问）
      - "7474:7474"
      # HTTPS 端口
      - "7473:7473"
    volumes:
      # 持久化数据存储
      - neo4j_data:/data
      # 持久化日志
      - neo4j_logs:/logs
      # 导入数据目录
      - neo4j_import:/var/lib/neo4j/import
      # 插件目录
      - neo4j_plugins:/plugins
    healthcheck:
      test: ["CMD", "cypher-shell", "-u", "neo4j", "-p", "aerotop", "RETURN 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    networks:
      - app-network
    # 资源限制
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          memory: 2G

  # Milvus 向量数据库服务
  milvus:
    image: milvusdb/milvus:v2.6.8
    container_name: milvus-db
    restart: unless-stopped
    environment:
      # 启用身份验证
      - MILVUS_AUTHORIZATION_ENABLED=false
      # 开启审计日志
      - MILVUS_AUDIT_LOG_ENABLE=true
      # 时区设置
      - TZ=Asia/Shanghai
      - ETCD_ENDPOINTS=etcd:2379
      - MINIO_ADDRESS=minio:9000
      - MQ_TYPE=woodpecker
    ports:
      # gRPC 端口
      - "19530:19530"
      # HTTP 端口
      - "9091:9091"
    volumes:
      # 持久化数据存储
      - milvus_data:/var/lib/milvus
      # 配置文件（可选）
      # - ./milvus/config.yaml:/milvus/configs/config.yaml
    depends_on:
      # Milvus 依赖 etcd 和 minio
      etcd:
        condition: service_healthy
      minio:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9091/healthz"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 90s
    networks:
      - app-network
    # 资源限制
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8G
        reservations:
          memory: 4G

  # Milvus 依赖服务：etcd（元数据存储）
  etcd:
    image: quay.io/coreos/etcd:v3.5.25
    container_name: milvus-etcd
    environment:
      - ETCD_AUTO_COMPACTION_MODE=revision
      - ETCD_AUTO_COMPACTION_RETENTION=1000
      - ETCD_QUOTA_BACKEND_BYTES=4294967296
      - ETCD_SNAPSHOT_COUNT=50000
    volumes:
      - etcd_data:/etcd
    command: etcd -advertise-client-urls=http://127.0.0.1:2379 -listen-client-urls http://0.0.0.0:2379 --data-dir /etcd
    healthcheck:
      test: ["CMD", "etcdctl", "endpoint", "health"]
      interval: 30s
      timeout: 20s
      retries: 3
    networks:
      - app-network

  # Milvus 依赖服务：minio（对象存储）
  minio:
    image: minio/minio:RELEASE.2024-12-18T13-15-44Z
    container_name: milvus-minio
    environment:
      - MINIO_ACCESS_KEY=minioadmin
      - MINIO_SECRET_KEY=minioadmin
    volumes:
      - minio_data:/minio_data
    command: minio server /minio_data --console-address ":9001"
    ports:
      # web 端口
      - "9001:9001"
      # app 端口
      - "9000:9000"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 20s
      retries: 3
    networks:
      - app-network

  # AerotopMultiAgents系统
  app:
    build:
      context: .
      dockerfile: Dockerfile
      # 可选：使用目标构建阶段（如果 Dockerfile 是多阶段构建）
      # target: production
    container_name: aerotop-app
    restart: unless-stopped
    environment:
      # 应用环境配置
      - OPENAI_MODEL_THINKING=Qwen/Qwen3-32B
      - OPENAI_MODEL_INSTRUCTION=Qwen/Qwen2.5-32B-Instruct
      - OPENAI_MODEL_EMBEDDING=Qwen/Qwen3-Embedding-8B
      - OPENAI_MODEL_RERANK=BAAI/bge-reranker-v2-m3
      - OPENAI_API_KEY=ms-ac180211-50aa-4a0e-99fc-****
      - OPENAI_API_BASE_URL=https://api-inference.modelscope.cn/v1/
      - DATA_FOR_SESSION=./data/session/session.db
      - DATA_FOR_LONG_MEMORY_PATH=./data/memory/qdrant_data
      - LOG_LEVEL=info

      # Neo4j 连接配置（使用 Docker Compose 服务名作为主机名）
      - NEO4J_URI=bolt://neo4j:7687
      - NEO4J_USER=neo4j
      - NEO4J_PASSWORD=aerotop
      - NEO4J_DATABASE=aerotop

      # Milvus 连接配置
      - MILVUS_HOST=milvus
      - MILVUS_PORT=19530
      - MILVUS_COLLECTION_NAME=embeddings
      - MILVUS_VECTOR_DIMENSION=1536

      # 时区设置
      - TZ=Asia/Shanghai
    ports:
      # 应用服务端口
      - "10085:10085"
    volumes:
      # 挂载数据目录
      - ./data:/app/data
    depends_on:
      neo4j:
        condition: service_healthy
      milvus:
        condition: service_healthy
    # 开发环境使用 stdin 保持容器运行
    stdin_open: true
    tty: true
    networks:
      - app-network
    # 资源限制
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          memory: 1G
    # 健康检查
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:10085/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

# 定义数据卷，确保数据持久化
volumes:
  neo4j_data:
    driver: local
  neo4j_logs:
    driver: local
  neo4j_import:
    driver: local
  neo4j_plugins:
    driver: local
  milvus_data:
    driver: local
  etcd_data:
    driver: local
  minio_data:
    driver: local
```

### 生产环境部署

1. **环境准备**：
```bash
# 复制生产环境配置
cp .env.example .env.production

# 或设置必要的环境变量
export OPENAI_MODEL_THINKING=Qwen/Qwen3-32B
export OPENAI_MODEL_INSTRUCTION=Qwen/Qwen2.5-32B-Instruct
export OPENAI_MODEL_EMBEDDING=Qwen/Qwen3-Embedding-8B
export OPENAI_MODEL_RERANK=BAAI/bge-reranker-v2-m3
export OPENAI_API_KEY=ms-ac180211-50aa-4a0e-99fc-****
export OPENAI_API_BASE_URL=https://api-inference.modelscope.cn/v1/
export DATA_FOR_SESSION=./data/session/session.db
export DATA_FOR_LONG_MEMORY_PATH=./data/memory/qdrant_data
export LOG_LEVEL=info
export NEO4J_URI=bolt://neo4j:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=aerotop
export NEO4J_DATABASE=aerotop
export MILVUS_HOST=milvus
export MILVUS_PORT=19530
export MILVUS_COLLECTION_NAME=embeddings
export MILVUS_VECTOR_DIMENSION=1536
```

2. **启动服务**：
```bash
# 使用生产配置启动
docker-compose -f docker-compose.yml --env-file .env.production up -d

# 或使用生产专用编排文件
docker-compose -f docker-compose.prod.yml up -d
```

3. **监控与维护**：
```bash
# 查看实时日志
docker-compose logs -f --tail=100
```

## 🔧 配置系统

项目采用配置中心模式，支持多种配置源：

```python
# 示例配置使用
from config.setting import config

# 访问配置
api_key = config.OPENAI_API_KEY
api_model_thinking = config.OPENAI_MODEL_THINKING
api_model_instruction = config.OPENAI_MODEL_INSTRUCTION
api_model_embedding = config.OPENAI_MODEL_EMBEDDING
api_model_rerank = config.OPENAI_MODEL_RERANK
api_model_base_url = config.OPENAI_API_BASE_URL

# 动态更新配置
config.update_from_env()  # 从环境变量更新
```

配置文件支持：
- 环境变量覆盖
- 配置文件分级（开发/测试/生产）
- 类型验证和默认值
- 热重载支持

## 📚 API 文档

### OpenAI 兼容接口

项目实现了完整的 OpenAI API 兼容接口：

```bash
# 流式访问
curl -N -X POST http://localhost:10085/v1/chat/completions \
  -H "Authorization: Bearer sk-mixiaodong" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
        "user_id": "user_123",
        "session_id": "session_123",
        "messages": "我的喜好是吃红龙果，本次任务是请以聊天的形式帮我计算6*8等于多少？"
      }'
```

### 自定义端点

```
GET    /health                    # 健康检查
GET    /v1/models                 # 可用模型列表
POST   /v1/chat/completions       # 聊天补全
```


## 🤝 贡献指南

我欢迎各种形式的贡献！

### 开发流程

1. **Fork 项目**
2. **创建功能分支**
   ```bash
   git checkout -b feature/amazing-feature
   ```
3. **提交更改**
   ```bash
   git commit -m 'Add some amazing feature'
   ```
4. **推送到分支**
   ```bash
   git push origin feature/amazing-feature
   ```
5. **开启 Pull Request**

### 代码规范

- 遵循 PEP 8 编码规范
- 使用类型注解
- 编写单元测试
- 更新相关文档
- 提交信息遵循 Conventional Commits

### 测试要求

```bash
# 确保所有测试通过
pytest

# 确保代码风格符合要求
ruff check AerotopMiltiAgent/

# 确保类型检查通过
mypy AerotopMiltiAgent/
```

## 📄 许可证

本项目基于 MIT 许可证开源 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- [AgentScope](https://github.com/modelscope/agentscope) - 基础多智能体框架
- [UV](https://github.com/astral-sh/uv) - 极速 Python 包管理器
- 所有贡献者和用户

## 📞 支持与联系

- 📧 邮箱：mixiaodong1998@163.com
- 💬 讨论区：微信（mixiaodong1998）
- 🐛 问题反馈：电话（19261019984）

## ⭐ 如果这个项目对你有帮助...

请给我一个 Star！⭐

这是对我最大的鼓励，也帮助更多开发者发现这个项目。

---

<div align="center">
<sub>Built with ❤️ by the AerotopMultiAgents contributors</sub>
</div>