# multi-agent-mcp

**Repository Path**: ymnlwyy0821/multi-agent-mcp

## Basic Information

- **Project Name**: multi-agent-mcp
- **Description**: 多Agent协同工作框架 - Cursor MCP集成，支持自动任务分解、动态创建专家Agent、三层质量保障
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-14
- **Last Updated**: 2026-04-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Multi-Agent Collaborative Framework

一个多 Agent 协同工作框架：给出一个任务，框架自动创建多个专家 Agent 协同完成工作。

## 核心特性

- **自动任务分解** — Planner Agent 分析任务，决定需要哪些专家、如何分工
- **动态 Agent 创建** — 按需创建架构师、开发者、测试工程师等角色
- **三层质量保障** — 结构验证 + LLM 规划审查 + 执行结果评估，不合格自动迭代
- **DAG 调度** — 支持串行、并行、带依赖的任务执行，含死锁检测
- **Agent 间通信** — 内置消息总线，上下游 Agent 自动传递上下文
- **灵活模型** — 基于 litellm，支持 OpenAI / Anthropic / Ollama / 100+ 模型
- **Cursor 集成** — MCP Server 原生集成 Cursor IDE

## 快速开始

```bash
# 安装依赖
pip install -e .

# 配置 API Key
export OPENAI_API_KEY=sk-...
# 或
export ANTHROPIC_API_KEY=sk-ant-...
export DEFAULT_MODEL=claude-sonnet-4-20250514

# 运行任务
multi-agent run "设计一个电商网站的用户认证系统"

# 交互模式
multi-agent interactive

# 指定模型 + 控制评审参数
multi-agent run --model gpt-4o \
  --min-plan-score 8 \
  --max-plan-attempts 3 \
  --min-result-score 6 \
  --max-retries 2 \
  -o result.md \
  "分析并优化这段代码的性能"

# 跳过评审（快速模式）
multi-agent run --skip-plan-review --skip-result-review "快速完成一个原型"
```

## 项目结构

```
src/multi_agent/
├── core/
│   ├── agent.py          # Agent 基类 — 自主执行单元
│   ├── task.py           # Task 数据模型
│   ├── planner.py        # 任务分解与规划（含评审迭代）
│   ├── orchestrator.py   # 编排引擎（含结果评估与重试）
│   ├── evaluator.py      # 三层评估：结构验证 / LLM审查 / 结果评分
│   └── message.py        # Agent 间消息总线
├── llm/
│   └── provider.py       # LLM 统一接口 (litellm)
├── tools/
│   ├── base.py           # Tool 基类
│   ├── file_tools.py     # 文件操作
│   ├── code_tools.py     # 代码执行
│   └── search_tools.py   # 知识检索
├── mcp/
│   └── server.py         # MCP Server (Cursor 集成)
└── cli/
    └── main.py           # CLI 入口
```

## 架构

```
用户任务
  ↓
Planner Agent → 生成规划
  ↓
结构验证（DAG合法性、Agent分配）
  ↓
LLM 审查（打分 + 建议，不合格则重新规划）
  ↓
Orchestrator → 按 DAG 调度多个 Expert Agent
  ↓                    ↕ MessageBus
结果评估（打分，不合格则重新规划+执行）
  ↓
汇总输出
```

## 质量保障

框架内置三层评估机制，确保规划和执行质量：

1. **结构验证**（零成本）— DAG 环检测、Agent 引用完整性、依赖合法性
2. **LLM 规划审查** — 独立 LLM 评估规划质量（1-10 分），指出缺失/冗余的 Agent，不合格自动带反馈重新规划
3. **执行结果评估** — 完成后评估每个 Agent 产出，整体质量不达标则重新执行

## Cursor 集成

在 Cursor 的 MCP 设置中添加：

```json
{
  "mcpServers": {
    "multi-agent": {
      "command": "python",
      "args": ["-m", "multi_agent.mcp.server"],
      "cwd": "/path/to/this/project"
    }
  }
}
```

可用 MCP 工具：
- `run_task(goal)` — 规划 + 评审 + 执行 + 结果评估
- `plan_task(goal)` — 仅规划和评审，不执行
- `get_last_plan()` — 查看最近的规划（含评审分数）
- `get_last_result()` — 查看最近的执行结果
- `get_last_review()` — 查看最近的结果评估

## 支持的模型

通过 litellm 支持所有主流模型：

| 提供商 | 模型示例 |
|--------|----------|
| OpenAI | `gpt-4o`, `gpt-4o-mini`, `o1-preview` |
| Anthropic | `claude-sonnet-4-20250514`, `claude-3-haiku-20240307` |
| Ollama | `ollama/llama3`, `ollama/mixtral` |
| Azure | `azure/gpt-4o` |
| Google | `gemini/gemini-pro` |