Multi-Agent

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（直接改默认值）

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")

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

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（推荐）

cd multi-agent-demo

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

使用 pip

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 名称、执行动作
• 最终结果：完整答案、总耗时

---

常见问题

端口被占用

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

DeepSeek API 报错

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

Tavily 搜索失败

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

切换到其他 LLM

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

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