内容
# 🧠 智能分析系统
**一个用于对话式数据分析的多智能体AI系统。**
*由 BrainBots 团队构建。*
上传一个 CSV 文件，询问“每个地区的平均收入是多少？”，然后观察 Supervisor Agent 如何实时委托 Data Analyst Agent 和 Visualization Agent 协作 — 整个推理过程透明可见，不隐藏在黑盒中。
🔗 **[在线演示](#)** · 📺 **[架构](#-how-it-works-architecture)** · 🚀 **[快速开始](#-setup-local)**
> ⭐ 如果这个项目对你有用或感兴趣，请考虑给仓库点赞 — 它也能帮助其他人发现它。
---
## ✨ 为什么这个项目与众不同
- 🤖 **真正的多智能体协作** — 不是一个 AI 做所有事情，而是 Supervisor 委托给专业智能体，类似 LangGraph 风格
- 🔌 **基于 MCP 的工具** — 智能体的工具（数据分析、图表、电子邮件）生活在标准 Model Context Protocol 服务器中，与推理逻辑解耦
- 📚 **基于 RAG** — 在编写任何分析代码之前，检索实际的数据集模式，而不是猜测列名
- 📈 **交互式仪表盘** — 真正的 pandas + Plotly 分析在您上传数据时立即运行，无需提问
- 📧 **能采取实际行动的智能体** — Communicator Agent 可以实际发送电子邮件报告，而不仅仅显示文本
- 🧑🤝🧑 **完全透明** — 每个响应都显示哪些智能体运行了以及它们执行了什么代码
---
## 🧠 工作原理（架构）
该项目使用 **多智能体监督架构** — 不是一个 AI 尝试做所有事情，而是由 Supervisor Agent 协调的小团队的专业智能体协作。这与您自己的团队如何将工作分配给不同人员类似。
```
┌───────────────────────────┐
用户输入问题 │ Streamlit UI │
────────────────────▶ │ (app.py) │
└─────────────┬──────────────┘
│
▼
┌───────────────────────────┐
│ RAG Retrieval │
│ (rag/retrieve.py) │
│ 查找相关列信息 │
└─────────────┬──────────────┘
▼
┌───────────────────────────┐
│ Supervisor Agent │ "这个
│ (agent/graph.py) │ 问题需要什么？"
└──────┬─────────┬───────────┘
│ │
需要数据 │ │ 需要图表
▼ ▼
┌─────────────────┐ ┌──────────────────┐
│ 数据分析智能体 │ │ 可视化智能体 │
│ Agent │ │ Agent │
│ （通过 MCP 工具运行 pandas） │ │ （通过 MCP 工具绘制图表） │
└────────┬─────────┘ └─────────┬─────────┘
└─────────┬─────────────┘
▼
┌───────────────────────────┐
│ Communicator Agent │
│ 编写最终答案， │
│ 如果需要则发送电子邮件 │
└───────────────────────────┘
```
### 四个概念及其具体实现
| 概念 | 实现位置 | 功能 |
|---|---|---|
| **LLM** | `agent/graph.py` 中的所有智能体（通过 `ChatGroq`） | 每个专业智能体使用 LLM 进行其特定任务 — 规划、分析、图表代码或通信 |
| **RAG** | `rag/ingest.py`、`rag/retrieve.py` | 存储列名、类型和样本到 ChromaDB 向量存储；检索相关列信息以便智能体不猜测列名 |
| **MCP** | `mcp_server/server.py` | 暴露共享工具（`describe_dataframe`、`run_pandas_code`、`generate_chart`、`send_email_report`）供任意智能体调用 — 工具与智能体解耦 |
| **多智能体协作** | `agent/graph.py` | **Supervisor Agent** 规划并委托给 **Data Analyst Agent** 和 **Visualization Agent**，然后 **Communicator Agent** 最终确定响应 — 四个不同智能体，每个智能体一个任务 |
| **LangGraph** | `agent/graph.py` | 将整个团队实现为显式状态图，具有条件路由 — 可以指向 `route_from_supervisor()` 并解释工作如何委托 |
### 为什么这个设计在 viva 中容易解释
每个文件夹 = 一个概念，每个 **智能体函数** = 一个团队成员的任务。如果评估者询问“多智能体部分在哪里？”，你可以指向 `agent/graph.py` 中的四个函数：`supervisor_node`、`data_analyst_node`、`visualization_node`、`communicator_node` — 并解释 Supervisor 的 `route_from_supervisor()` 函数是可见且可读的委托逻辑，而不是黑盒。
---
## 📁 文件夹结构
```
agentic-data-analyst/
├── mcp_server/
│ └── server.py # MCP 工具：describe_dataframe, run_pandas_code, generate_chart
├── rag/
│ ├── ingest.py # 从上传的 CSV 文件架构构建向量数据库
│ └── retrieve.py # 为给定问题获取相关列信息
├── agent/
│ └── graph.py # LangGraph 状态图（智能体的推理循环）
├── app.py # Streamlit UI（聊天界面 + 图表）
├── sample_data/
│ └── sample_sales.csv # 示例数据集，用于立即测试
├── requirements.txt
├── .env.example
└── README.md
```
---
## 🚀 本地设置
**1. 克隆并进入项目**
```bash
git clone <your-repo-url>
cd agentic-data-analyst
```
**2. 创建虚拟环境**
```bash
python -m venv venv
source venv/bin/activate # 在 Windows 上：venv\Scripts\activate
```
**3. 安装依赖**
```bash
pip install -r requirements.txt
```
**4. 添加 API 密钥**
```bash
cp .env.example .env
# 然后编辑 .env 并粘贴您的免费 Groq API 密钥
# 在 https://console.groq.com/keys 获取
```
**5. 运行应用**
```bash
streamlit run app.py
```
打开 Streamlit 打印的本地 URL（通常为 `http://localhost:8501`），上传 `sample_data/sample_sales.csv`，然后：
- 立即检查 **Auto Dashboard 标签** — 它已经显示真实的统计数据和图表
- 切换到 **Ask the Agent** 并尝试：
- “每个地区的平均收入是多少？”
- “给我一个按类别划分的利润条形图”
- “哪个地区销售的单位最多？”
- “将每个地区的平均收入发送到 your.email@example.com”（需要下面的电子邮件设置）
**可选：启用电子邮件功能**
电子邮件工具需要一个具有“应用密码”的 Gmail 帐户（不是您的普通密码）：
1. 在您的 Google 帐户上启用两步验证
2. 前往 https://myaccount.google.com/apppasswords 并生成一个 16 个字符的应用密码
3. 将您的 Gmail 地址和该应用密码放入 `.env` 中作为 `EMAIL_ADDRESS` 和 `EMAIL_APP_PASSWORD`
如果您跳过此步骤，其他所有功能仍然有效 — 电子邮件按钮/工具只会告诉您它未配置，而不是崩溃。
---
## ☁️ 部署
### 选项 A：Streamlit 社区云（最简单，免费）
1. 将此仓库推送到 GitHub（确保 `.env` 位于 `.gitignore` 中 — 永远不要提交真正的 API 密钥）。
2. 前往 [share.streamlit.io](https://share.streamlit.io)，使用 GitHub 登录。
3. 点击“新建应用”，选择您的仓库，将主文件设置为 `app.py`。
4. 在“高级设置 → 机密”下，添加：
```
GROQ_API_KEY = "your_real_key_here"
```
5. 部署。Streamlit Cloud 自动安装 `requirements.txt`。
> 注意：MCP 服务器由代理作为本地子进程启动，因此它在 Streamlit Cloud 上无需额外设置即可运行。
### 选项 B：Hugging Face Spaces
1. 创建一个新的 Space，选择 **Streamlit** SDK。
2. 上传仓库文件（或通过 GitHub 连接）。
3. 在 Space **设置 → 仓库机密** 下添加 `GROQ_API_KEY`。
4. Space 自动构建和部署。
### 选项 C：Render / Railway（更多控制）
1. 从您的 GitHub 仓库创建一个新的 **Web 服务**。
2. 构建命令：`pip install -r requirements.txt`
3. 启动命令：`streamlit run app.py --server.port $PORT --server.address 0.0.0.0`
4. 在仪表盘中将 `GROQ_API_KEY` 添加为环境变量。
**部署后：** 在隐身窗口中打开实时链接以确认它为新用户正常工作，然后将实时链接添加到此 README。
---
## 🛠️ 建议的改进（良好的“未来工作”讨论点）
- 添加一个真正的字典 UI，以便用户可以描述自己的列以获得更好的 RAG 上下文
- 支持多种文件格式（Excel，JSON）
- 持久化聊天历史记录和过去的 Q&A 到向量存储中，以便代理“记住”会话中的早期问题
- 为多个用户部署时添加身份验证
- 为生产使用将基于 `exec()` 的沙盒替换为适当隔离的代码执行服务
---
## 🖼️ 截图
<!-- 替换这些截图为真实截图后再提交/分享。
拍摄运行应用的截图，将它们保存在 `screenshots/`
文件夹中，然后更新下面的路径。 -->
| 自动仪表盘 | 多智能体聊天 |
|---|---|
|  |  |
---
## 👥 （BrainBots）
由一个 4 人团队作为大学代理 AI 项目的一部分构建：
| 成员 | 关注领域 |
|---|---|
| [姓名] | RAG 层（`rag/`） |
| [姓名] | MCP 工具服务器（`mcp_server/`） |
| [姓名] | 多智能体编排（`agent/graph.py`） |
| [姓名] | 前端 + 部署（`app.py`，README） |
---
## 📄 许可证
MIT 许可证 — 免费使用、修改和学习。详见 `LICENSE`。
---
## 📚 使用的关键库
- [LangGraph](https://langchain-ai.github.io/langgraph/) — 代理编排为状态图
- [langchain-mcp-adapters](https://github.com/langchain-ai/langchain-mcp-adapters) — 将 MCP 工具桥接到 LangChain/LangGraph
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) — 定义工具服务器
- [ChromaDB](https://www.trychroma.com/) + [sentence-transformers](https://www.sbert.net/) — RAG 向量存储和嵌入
- [Groq](https://groq.com/) — 快速、免费的 LLM 推理（Llama 3.3）
- [Streamlit](https://streamlit.io/) — 交互式 UI
