# Multi-Agent 演示系统 — 使用文档

## 项目概览

基于 **FastAPI + SSE + 真实 LLM 调用** 的多 Agent 协作演示系统，展示三种经典多 Agent 架构模式：

| 模式 | 流程 | Agent 数量 |
|------|------|-----------|
| **Supervisor（主管模式）** | Supervisor 拆任务 → Researcher 搜索 → Coder 分析 → Supervisor 整合 | 3 |
| **Pipeline（流水线模式）** | 搜索 Agent → 分析 Agent → 报告 Agent | 3 |
| **Debate（辩论模式）** | 正方立论 → 反方反驳 → 正方回应 → 反方回应 → 裁判评判 | 3 |

所有 Agent 均调用真实 LLM（DeepSeek），使用真实工具（Tavily 搜索、Python 执行、数学计算），无任何 Mock 数据。

---

## 项目结构

```
multi-agent-demo/
├── config.py          # 配置中心（API Key、模型、端口）
├── agent.py           # Agent 基类（LLM 调用 + 工具循环）
├── orchestrator.py    # 三种模式的执行引擎
├── tools.py           # 工具注册表（web_search、calculator、run_python）
├── server.py          # FastAPI 后端（SSE 实时推送）
└── index.html         # 前端页面（液态玻璃 UI）
```

---

## 环境要求

- **Python** >= 3.11
- **uv** 包管理器（推荐）或 pip
- **DeepSeek API Key**（或其他兼容 OpenAI 接口的 LLM）
- **Tavily API Key**（用于 web_search 工具）

---

## 配置说明

所有配置集中在 `config.py`，支持环境变量覆盖。

### 配置项一览

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|---------|--------|------|
| LLM API Key | `LLM_API_KEY` | 内置 Key | DeepSeek API Key |
| LLM Base URL | `LLM_BASE_URL` | `https://api.deepseek.com/v1` | OpenAI 兼容接口地址 |
| LLM 模型 | `LLM_MODEL` | `deepseek-v4-flash` | 模型名称 |
| Tavily API Key | `TAVILY_API_KEY` | 内置 Key | 搜索工具 Key |
| 应用端口 | `APP_PORT` | `8900` | Web 服务端口 |

### 方式一：修改 config.py（直接改默认值）

```python
LLM_API_KEY    = os.getenv("LLM_API_KEY", "你的API Key")
LLM_BASE_URL   = os.getenv("LLM_BASE_URL", "https://你的接口地址/v1")
LLM_MODEL      = os.getenv("LLM_MODEL", "你的模型名")
TAVILY_API_KEY = os.getenv("TAVILY_API_KEY", "你的Tavily Key")
```

### 方式二：设置环境变量（推荐，不改代码）

```bash
export LLM_API_KEY="sk-xxx"
export LLM_BASE_URL="https://api.deepseek.com/v1"
export LLM_MODEL="deepseek-chat"
export TAVILY_API_KEY="tvly-xxx"
export APP_PORT="8900"
```

---

## 服务启动

### 使用 uv（推荐）

```bash
cd multi-agent-demo

uv run --python 3.11 \
  --with fastapi \
  --with uvicorn \
  --with pydantic \
  --with openai \
  --with tavily-python \
  python server.py
```

### 使用 pip

```bash
cd multi-agent-demo

# 创建虚拟环境
python3.11 -m venv .venv
source .venv/bin/activate

# 安装依赖
pip install fastapi uvicorn pydantic openai tavily-python

# 启动
python server.py
```

### 启动成功标志

```
INFO:     Started server process [xxxxx]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8900 (Press CTRL+C to quit)
```

浏览器访问 **http://localhost:8900** 即可打开演示页面。

---

## 依赖说明

| 包名 | 用途 |
|------|------|
| `fastapi` | Web 框架 |
| `uvicorn` | ASGI 服务器 |
| `pydantic` | 数据校验 |
| `openai` | LLM API 客户端（兼容所有 OpenAI 接口格式） |
| `tavily-python` | 搜索工具 API |

> `openai` 库用于调用所有兼容 OpenAI 接口的 LLM（DeepSeek、Moonshot、智谱等），不限于 OpenAI 的模型。

---

## 三种模式详解

### Supervisor 模式

```
用户提问
  ↓
Supervisor 分析任务，拆解为子任务
  ↓
Researcher 执行 web_search 搜索真实信息
  ↓
Coder 执行 calculator / run_python 做数据分析
  ↓
Supervisor 整合所有结果，输出最终答案
```

### Pipeline 模式

```
用户提问
  ↓
搜索 Agent 采集信息（web_search）
  ↓
分析 Agent 结构化分析（calculator + run_python）
  ↓
报告 Agent 生成最终报告（run_python）
```

### Debate 模式

```
用户提出辩题
  ↓
正方辩手 搜索资料 + 立论
  ↓
反方辩手 搜索资料 + 反驳 + 立论
  ↓
正方辩手 回应反驳
  ↓
反方辩手 最终反驳
  ↓
裁判 综合评判，给出结论
```

---

## 工具清单

| 工具 | 功能 | 使用的 Agent |
|------|------|-------------|
| `web_search` | Tavily 搜索，每次返回 2 条结果 | Researcher、正/反方辩手、搜索 Agent |
| `calculator` | 安全数学计算（加减乘除、幂运算） | Coder、裁判、分析 Agent |
| `run_python` | 隔离执行 Python 代码（10 秒超时） | Coder、裁判、分析/报告 Agent |
| `text_analyze` | 文本统计（字符数、词数、行数） | 可选 |

---

## 内置预设任务

页面提供三个预设按钮，点击自动填入示例查询：

- **Supervisor**：Agent 面试题调研 + 数据分析
- **Pipeline**：LangChain / CrewAI / AutoGen 竞品分析报告
- **Debate**：LangGraph vs 纯代码手写的技术选型辩论

---

## 实时执行追踪

通过 SSE（Server-Sent Events）实时推送每个执行步骤：

- LLM 调用：模型名、耗时（ms）、Token 数、当前轮次
- 工具调用：工具名、输入参数、返回结果、耗时
- 步骤状态：开始/结束标记、Agent 名称、执行动作
- 最终结果：完整答案、总耗时

---

## 常见问题

**端口被占用**

```bash
lsof -i:8900          # 查看占用进程
kill -9 <PID>         # 杀掉进程
# 或换端口
export APP_PORT=9000
```

**DeepSeek API 报错**

- 检查 API Key 是否有效
- 确认 Base URL 以 `/v1` 结尾
- 检查账户余额

**Tavily 搜索失败**

- 检查 Tavily API Key 是否有效
- 免费版有调用次数限制
- 代码内置 3 次重试机制

**切换到其他 LLM**

修改环境变量即可，无需改代码：

```bash
export LLM_BASE_URL="https://api.moonshot.cn/v1"
export LLM_API_KEY="你的Key"
export LLM_MODEL="moonshot-v1-8k"
```