# multi_agent_scaffold

**Repository Path**: hephec321/multi_agent_scaffold

## Basic Information

- **Project Name**: multi_agent_scaffold
- **Description**: 多智能体脚手架基于agentscope
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-12-10
- **Last Updated**: 2025-12-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 多智能体开发脚手架

一个基于AgentScope框架的多智能体开发脚手架，提供简单易用的API来创建和管理多智能体系统，支持OpenAI模型、MCP工具和记忆管理。

## 功能特性

- 🤖 **智能体管理**: 支持创建和管理多个智能体，包括ReAct智能体
- 🔧 **MCP工具集成**: 支持Model Context Protocol (MCP) 工具的注册和管理，支持StreamableHTTP和SSE传输类型，扩展智能体功能
- 🧠 **记忆管理**: 支持多种记忆类型，包括in_memory、mem0和reme_static
- 🔄 **协作框架**: 支持顺序执行和协作式多智能体交互，提供异步执行模式提高并发处理能力
- ⚙️ **配置管理**: 灵活的配置系统，支持YAML和JSON格式，提供丰富的模型和记忆配置选项
- 📚 **完整文档**: 提供详细的学习文档和示例代码，采用模块化设计便于扩展和维护

## 安装

```bash
pip install agentscope>=1.0.1
pip install -r requirements.txt
```

## 快速开始

### 1. 环境配置

创建 `.env` 文件并添加以下内容：

```env
# OpenAI API配置
OPENAI_API_KEY=your_openai_api_key

# DashScope API配置（可选）
DASHSCOPE_API_KEY=your_dashscope_api_key
```

### 2. 创建简单对话机器人

```python
import asyncio
from agentscope.message import Msg
from multi_agent_scaffold import (
    AgentConfig,
    OpenAIConfig,
    MemoryConfig,
    MultiAgentConfig,
    MultiAgentOrchestrator,
    Settings
)

async def main():
    # 创建模型配置
    model_config = OpenAIConfig(
        model_name="gpt-3.5-turbo",
        api_key="your-api-key",
        base_url="https://api.openai.com/v1",
        temperature=0.7
    )
    
    # 创建记忆配置
    memory_config = MemoryConfig(
        memory_type="in_memory",
        max_tokens=4000
    )
    
    # 创建智能体配置
    agent_config = AgentConfig(
        name="assistant",
        sys_prompt="你是一个友好的助手，请简洁回答用户的问题。",
        model_config=model_config,
        memory_config=memory_config
    )
    
    # 创建多智能体配置
    multi_agent_config = MultiAgentConfig(
        agents=[agent_config],
        mcp_tools=[],
        enable_auto_broadcast=True
    )
    
    # 创建编排器
    orchestrator = MultiAgentOrchestrator(multi_agent_config, Settings())
    
    # 创建消息
    message = Msg(
        name="user",
        content="你好！请介绍一下你自己。",
        role="user"
    )
    
    # 运行对话
    result = await orchestrator.run_sequential(
        message=message,
        agent_names=["assistant"]
    )
    
    # 打印结果
    print(f"助手回复: {result.content}")

if __name__ == "__main__":
    asyncio.run(main())
```

### 3. 创建带有MCP工具的智能体

```python
import asyncio
from agentscope.message import Msg
from multi_agent_scaffold import (
    AgentConfig,
    OpenAIConfig,
    MemoryConfig,
    MCPConfig,
    AgentFactory,
    Settings
)

async def main():
    # 创建模型配置
    model_config = OpenAIConfig(
        model_name="gpt-3.5-turbo",
        api_key="your-api-key",
        base_url="https://api.openai.com/v1",
        temperature=0.7
    )
    
    # 创建记忆配置
    memory_config = MemoryConfig(
        memory_type="in_memory",
        max_tokens=4000
    )
    
    # 创建MCP工具配置
    mcp_config = MCPConfig(
        name="filesystem",
        transport="stdio",
        command="npx -y @modelcontextprotocol/server-filesystem /path/to/directory"
    )
    
    # 创建智能体配置
    agent_config = AgentConfig(
        name="file_agent",
        sys_prompt="你是一个文件操作助手，可以帮助用户读取、写入和管理文件。",
        model_config=model_config,
        memory_config=memory_config,
        mcp_tools=["filesystem"]
    )
    
    # 创建智能体工厂
    agent_factory = AgentFactory()
    
    # 注册MCP工具
    await agent_factory.register_mcp_tool(mcp_config)
    
    # 创建带有MCP工具的智能体
    agent = agent_factory.create_react_agent_with_mcp_tools(
        config=agent_config,
        mcp_tool_names=["filesystem"]
    )
    
    # 创建初始消息
    initial_message = Msg(
        name="user",
        content="请读取当前目录下的README.md文件内容",
        role="user"
    )
    
    # 运行智能体
    result = await agent(initial_message)
    
    # 打印结果
    print(f"智能体回复: {result.content}")

if __name__ == "__main__":
    asyncio.run(main())
```

### 4. 创建多智能体协作系统

```python
import asyncio
from agentscope.message import Msg
from multi_agent_scaffold import (
    AgentConfig,
    OpenAIConfig,
    MemoryConfig,
    MultiAgentConfig,
    MultiAgentOrchestrator,
    Settings
)

async def main():
    # 创建模型配置
    model_config = OpenAIConfig(
        model_name="gpt-3.5-turbo",
        api_key="your-api-key",
        base_url="https://api.openai.com/v1",
        temperature=0.7
    )
    
    # 创建记忆配置
    memory_config = MemoryConfig(
        memory_type="in_memory",
        max_tokens=4000
    )
    
    # 创建智能体配置
    agent_configs = [
        AgentConfig(
            name="receptionist",
            sys_prompt="你是一个友好的客户接待员，负责初步了解客户需求。",
            model_config=model_config,
            memory_config=memory_config
        ),
        AgentConfig(
            name="technical_support",
            sys_prompt="你是一个技术支持专家，负责解决技术问题。",
            model_config=model_config,
            memory_config=memory_config
        )
    ]
    
    # 创建多智能体配置
    multi_agent_config = MultiAgentConfig(
        agents=agent_configs,
        mcp_tools=[],
        enable_auto_broadcast=True
    )
    
    # 创建编排器
    orchestrator = MultiAgentOrchestrator(multi_agent_config, Settings())
    
    # 创建初始消息
    initial_message = Msg(
        name="customer",
        content="你好，我想了解你们的产品。",
        role="user"
    )
    
    # 运行顺序执行流程
    result = await orchestrator.run_sequential(
        message=initial_message,
        agent_names=["receptionist", "technical_support"]
    )
    
    # 打印结果
    print(f"客服团队回复: {result.content}")

if __name__ == "__main__":
    asyncio.run(main())
```

## 核心组件

### 1. 配置管理

#### OpenAIConfig
OpenAI模型配置类：

```python
model_config = OpenAIConfig(
    model_name="gpt-3.5-turbo",
    api_key="your-api-key",
    base_url="https://api.openai.com/v1",
    temperature=0.7
)
```

#### MemoryConfig
记忆配置类：

```python
memory_config = MemoryConfig(
    memory_type="in_memory",  # 可选: in_memory, mem0, reme_personal等
    max_tokens=4000
)
```

#### AgentConfig
智能体配置类：

```python
agent_config = AgentConfig(
    name="agent_name",
    sys_prompt="智能体的系统提示",
    model_config=model_config,
    memory_config=memory_config
)
```

#### MCPConfig
MCP工具配置类：

```python
mcp_config = MCPConfig(
    name="filesystem",  # MCP工具名称
    transport="stdio",   # 传输方式，支持"stdio"、"streamable_http"、"sse"等
    command="npx -y @modelcontextprotocol/server-filesystem /path/to/directory",  # 启动MCP服务器的命令
    url=None,           # HTTP服务器的URL（当transport为"http"时使用）
    is_stateful=True,   # 是否为有状态客户端
    client_config={}    # 客户端配置
)
```

#### MultiAgentConfig
多智能体配置类：

```python
multi_agent_config = MultiAgentConfig(
    agents=[agent_config1, agent_config2],
    mcp_tools=[mcp_config],
    enable_auto_broadcast=True
)
```

### 2. 编排器

#### MultiAgentOrchestrator
多智能体编排器，负责管理智能体的协作：

```python
orchestrator = MultiAgentOrchestrator(multi_agent_config, Settings())

# 顺序执行
result = await orchestrator.run_sequential(
    message=message,
    agent_names=["agent1", "agent2"]
)

# 并行执行
results = orchestrator.run_fanout(
    message=message,
    agent_names=["agent1", "agent2"],
    enable_gather=True
)
```

### 3. MCP工具管理

#### MCPToolManager
MCP工具管理器，负责注册和管理MCP工具：

```python
from multi_agent_scaffold import MCPToolManager, MCPConfig

# 创建MCP工具管理器
mcp_manager = MCPToolManager()

# 配置MCP工具
mcp_config = MCPConfig(
    name="filesystem",
    transport="stdio",
    command="npx -y @modelcontextprotocol/server-filesystem /path/to/directory"
)

# 注册MCP工具
await mcp_manager.register_mcp_tool(mcp_config)

# 获取工具
tools = mcp_manager.get_tools("filesystem")

# 调用工具
result = await mcp_manager.call_tool("filesystem", "read_file", {"path": "/path/to/file.txt"})
```

### 4. 记忆管理

#### MemoryManager
记忆管理器，负责创建和管理记忆实例：

```python
from multi_agent_scaffold import MemoryManager

# 创建记忆管理器
memory_manager = MemoryManager()

# 创建记忆实例
memory_manager.create_memory(
    "memory_name",
    MemoryConfig(memory_type="in_memory", max_tokens=4000)
)

# 获取记忆实例
memory = memory_manager.get_memory("memory_name")
```

## 项目结构

```
multi_agent_scaffold/
├── core/                   # 核心模块
│   ├── __init__.py
│   ├── agent_factory.py    # 智能体工厂
│   ├── mcp_manager.py      # MCP工具管理器
│   └── orchestrator.py     # 编排器
├── memory/                 # 记忆管理
│   ├── __init__.py
│   └── memory_manager.py   # 记忆管理器
├── agents/                 # 智能体模块
│   └── __init__.py
├── tools/                  # 工具集成
│   └── __init__.py
├── config/                 # 配置管理
│   ├── __init__.py
│   ├── settings.py         # 设置
│   ├── env_loader.py       # 环境变量加载器
│   └── prompts/            # 提示词模板
├── examples/               # 示例代码
│   ├── __init__.py
│   ├── quick_start.py      # 快速开始示例
│   ├── customer_service_team.py  # 客服团队示例
│   ├── research_team.py     # 研究团队示例
│   ├── mcp_integration_example.py  # MCP工具集成示例
│   └── test_single_agent_mcp.py   # 单智能体MCP工具测试
├── docs/                   # 文档目录
│   ├── __init__.py
│   ├── 快速入门指南.md      # 快速入门
│   ├── 多智能体脚手架学习文档.md  # 详细学习文档
│   ├── AgentScope RAG与Chroma知识库集成方案.md  # RAG集成方案
│   └── README_MCP.md       # MCP工具集成文档
├── tests/                  # 测试目录
│   ├── __init__.py
│   ├── test_minimal_functionality.py  # 最小功能测试
│   ├── test_agent_dashscope.py  # 智能体测试
│   ├── test_dashscope_config.py  # 配置测试
│   └── test_prompts.py      # 提示词测试
├── examples.py             # 示例代码
├── README.md               # 项目说明
├── README_MCP.md           # MCP工具集成说明
└── requirements.txt        # 依赖列表
```

## 学习资源

- [快速入门指南](docs/快速入门指南.md) - 快速上手指南
- [详细学习文档](docs/多智能体脚手架学习文档.md) - 全面详细的学习文档
- [RAG与Chroma知识库集成方案](docs/AgentScope%20RAG与Chroma知识库集成方案.md) - RAG集成方案
- [MCP工具集成文档](README_MCP.md) - Model Context Protocol (MCP) 工具集成详细说明
- [示例代码](examples.py) - 各种用例的示例代码

## 测试

```bash
# 运行最小功能测试
python tests/test_minimal_functionality.py

# 运行智能体测试
python tests/test_agent_dashscope.py

# 运行配置测试
python tests/test_dashscope_config.py

# 运行提示词测试
python tests/test_prompts.py

# 运行示例代码
python examples.py

# 运行MCP工具集成测试
python examples/test_single_agent_mcp.py

# 运行MCP工具集成示例
python examples/mcp_integration_example.py
```

## 常见用例

### 1. 客服团队

创建一个包含接待员、技术支持和主管的客服团队：

```python
# 客服团队配置
customer_service_configs = [
    AgentConfig(
        name="receptionist",
        sys_prompt="你是客服接待员，负责初步了解客户问题。",
        model_config=model_config,
        memory_config=memory_config
    ),
    AgentConfig(
        name="technician",
        sys_prompt="你是技术支持，负责解决技术问题。",
        model_config=model_config,
        memory_config=memory_config
    ),
    AgentConfig(
        name="supervisor",
        sys_prompt="你是客服主管，负责监督服务质量并做出最终决定。",
        model_config=model_config,
        memory_config=memory_config
    )
]

# 创建客服团队
customer_service_config = MultiAgentConfig(
    agents=customer_service_configs,
    mcp_tools=[],
    enable_auto_broadcast=True
)

orchestrator = MultiAgentOrchestrator(customer_service_config, Settings())

# 处理客户请求
customer_request = Msg(
    name="customer",
    content="我的产品无法启动，显示错误代码500。",
    role="user"
)

# 顺序处理：接待员 -> 技术员 -> 主管
result = await orchestrator.run_sequential(
    message=customer_request,
    agent_names=["receptionist", "technician", "supervisor"]
)
```

### 2. 研究团队

创建一个包含研究员、分析师和撰稿人的研究团队：

```python
# 研究团队配置
research_team_configs = [
    AgentConfig(
        name="researcher",
        sys_prompt="你是研究员，负责收集和分析信息。",
        model_config=model_config,
        memory_config=memory_config
    ),
    AgentConfig(
        name="analyst",
        sys_prompt="你是分析师，负责深入分析数据并提取见解。",
        model_config=model_config,
        memory_config=memory_config
    ),
    AgentConfig(
        name="writer",
        sys_prompt="你是撰稿人，负责整理研究结果并撰写报告。",
        model_config=model_config,
        memory_config=memory_config
    )
]

# 创建研究团队
research_team_config = MultiAgentConfig(
    agents=research_team_configs,
    mcp_tools=[],
    enable_auto_broadcast=True
)

orchestrator = MultiAgentOrchestrator(research_team_config, Settings())

# 研究请求
research_request = Msg(
    name="user",
    content="请研究人工智能在医疗领域的最新进展，并撰写一份报告。",
    role="user"
)

# 并行研究，然后汇总
research_results = orchestrator.run_fanout(
    message=research_request,
    agent_names=["researcher", "analyst"],
    enable_gather=True
)

# 撰写最终报告
final_report = await orchestrator.run_sequential(
    message=research_results,
    agent_names=["writer"]
)
```

### 4. 带有MCP工具的智能体

创建一个带有文件系统MCP工具的智能体：

```python
# 创建MCP工具配置 - stdio传输类型
mcp_config_stdio = MCPConfig(
    name="filesystem",
    transport="stdio",
    command="npx -y @modelcontextprotocol/server-filesystem /path/to/directory"
)

# 创建MCP工具配置 - SSE传输类型
mcp_config_sse = MCPConfig(
    name="filesystem_sse",
    transport="sse",
    url="http://localhost:3000/sse",
    is_stateful=True
)

# 创建MCP工具配置 - StreamableHTTP传输类型
mcp_config_http = MCPConfig(
    name="filesystem_http",
    transport="streamable_http",
    url="http://localhost:3000/mcp",
    is_stateful=False
)

# 创建智能体配置
agent_config = AgentConfig(
    name="file_agent",
    sys_prompt="你是一个文件操作助手，可以帮助用户读取、写入和管理文件。",
    model_config=model_config,
    memory_config=memory_config,
    mcp_tools=["filesystem"]
)

# 创建智能体工厂
agent_factory = AgentFactory()

# 注册MCP工具
await agent_factory.register_mcp_tool(mcp_config_stdio)

# 创建带有MCP工具的智能体
agent = agent_factory.create_react_agent_with_mcp_tools(
    config=agent_config,
    mcp_tool_names=["filesystem"]
)

# 使用智能体进行文件操作
file_request = Msg(
    name="user",
    content="请读取当前目录下的README.md文件内容",
    role="user"
)

result = await agent(file_request)
```

### 5. 多智能体与MCP工具协作

创建一个包含多个智能体的团队，其中部分智能体使用MCP工具：

```python
# 创建智能体配置
agent_configs = [
    AgentConfig(
        name="file_reader",
        sys_prompt="你是文件读取助手，负责读取文件内容。",
        model_config=model_config,
        memory_config=memory_config,
        mcp_tools=["filesystem"]
    ),
    AgentConfig(
        name="data_analyzer",
        sys_prompt="你是数据分析助手，负责分析文件内容并提供见解。",
        model_config=model_config,
        memory_config=memory_config
    ),
    AgentConfig(
        name="reporter",
        sys_prompt="你是报告撰写助手，负责整理分析结果并撰写报告。",
        model_config=model_config,
        memory_config=memory_config
    )
]

# 创建MCP工具配置
mcp_configs = [
    MCPConfig(
        name="filesystem",
        transport="stdio",
        command="npx -y @modelcontextprotocol/server-filesystem /path/to/directory"
    ),
    MCPConfig(
        name="github",
        transport="sse",
        url="http://localhost:3001/sse",
        is_stateful=True
    ),
    MCPConfig(
        name="database",
        transport="streamable_http",
        url="http://localhost:3002/mcp",
        is_stateful=False
    )
]

# 创建多智能体配置
multi_agent_config = MultiAgentConfig(
    agents=agent_configs,
    mcp_tools=mcp_configs,
    enable_auto_broadcast=True
)

# 创建编排器
orchestrator = MultiAgentOrchestrator(multi_agent_config, Settings())

# 处理文件分析请求
analysis_request = Msg(
    name="user",
    content="请分析/data/sales.csv文件并提供销售报告。",
    role="user"
)

# 顺序处理：文件读取 -> 数据分析 -> 报告撰写
result = await orchestrator.run_sequential(
    message=analysis_request,
    agent_names=["file_reader", "analyzer", "reporter"]
)
```

## 最佳实践

1. **明确角色**：每个智能体应有明确的职责和角色
2. **简洁提示**：系统提示应简洁明了，避免过于复杂的指令
3. **适当的模型**：根据任务复杂度选择合适的模型
4. **合理选择记忆类型**：根据应用场景选择合适的记忆类型
5. **并行处理**：对于独立任务，使用并行处理提高效率
6. **MCP工具选择**：根据智能体功能需求选择合适的MCP工具
7. **工具权限管理**：为不同智能体分配适当的工具权限，避免安全风险
8. **错误处理**：在使用MCP工具时添加适当的错误处理机制

## 故障排除

### 常见问题

1. **模型初始化失败**：检查模型配置参数是否正确
2. **记忆管理错误**：确保记忆实例已正确创建
3. **工具调用失败**：检查工具配置是否正确
4. **编排器执行错误**：检查方法调用参数是否正确
5. **MCP工具注册失败**：检查MCP服务器是否正确安装和配置
6. **MCP工具调用超时**：检查网络连接和服务器状态
7. **MCP工具权限错误**：检查文件路径和访问权限

### 调试技巧

1. **启用详细日志**：
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

2. **单步执行**：
```python
# 逐个执行智能体，便于定位问题
result1 = await agent1.process(message)
result2 = await agent2.process(result1)
```

3. **MCP工具调试**：
```python
# 检查MCP工具是否正确注册
tools = mcp_manager.get_tools("tool_name")
print(f"Available tools: {tools}")

# 测试MCP工具调用
try:
    result = await mcp_manager.call_tool("tool_name", "method_name", {"param": "value"})
    print(f"Tool result: {result}")
except Exception as e:
    print(f"Tool call failed: {e}")
```

4. **检查MCP服务器状态**：
```bash
# 检查Node.js和MCP服务器是否正确安装
node --version
npm list -g @modelcontextprotocol/server-filesystem
```

## 贡献指南

欢迎提交问题和拉取请求！请确保：

1. 代码符合PEP 8规范
2. 添加适当的测试
3. 更新相关文档

## 许可证

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