🤖 OmniAgent：多代理数据分析助手
    ](<>)
想象一下，能够像队友一样与你的数据交谈。OmniAgent是一个基于人工智能的多智能体助手，可以让你用简单的英语提问，并立即获得有意义的见解、可视化和预测。无需编码，无需与仪表板搏斗，只需在需要时提供清晰的答案。
大多数人花了太多时间清理数据、弄清楚工具，并试图手动提取见解。OmniAgent通过理解您的意图并自动使用合适的专业代理为您完成工作，将复杂的数据分析转化为简单的对话体验，从而消除了这种摩擦。
______________________________________________________________________
📑 目录
______________________________________________________________________
✨ 特性
| 特性 | 描述 |
|---|---|
| 🗣️ 自然语言 | 用简单的英语提问 |
| 🎤 语音输入 | 使用浏览器麦克风回答您的问题 |
| 🤖 7专业代理 | 统计、Viz、聚合、预测、SQL、动态、语音 |
| 🔮 AI代码生成 | 动态代理实时创建自定义分析 |
| 📊 交互式图表 | 美丽的Plotly可视化 |
| 🧠 智能路由 | 自动为您的查询找到合适的代理 |
| 🔒 安全执行 | 沙盒代码执行，具有40多项安全检查 |
| 🎯 ML模型 | 使用一个命令构建预测模型 |
| 🐳 Docker就绪 | 使用Docker进行一次命令部署 |
______________________________________________________________________
🏗️ 系统架构
高级概述
┌──────────────────────────────────────────────────────────────────────────────┐
│ USER INTERFACE │
│ (Streamlit Web App) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Text Input │ │ Voice Input │ │ Suggestions │ │
│ │ (Chat) │ │ (Microphone) │ │ (Buttons) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └───────────────────┼───────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 🧠 MASTER AGENT │ │
│ │ │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │
│ │ │ Intent │──▶│ Router │──▶│ MCP Message Bus │ │ │
│ │ │ Detection │ │ Logic │ │ (Agent Communication) │ │ │
│ │ │ (200+ rules)│ │ │ │ │ │ │
│ │ └─────────────┘ └─────────────┘ └───────────┬─────────────┘ │ │
│ │ │ │ │
│ │ Check: Is Dynamic Agent pending? ◄──────┤ │ │
│ │ │ │ │ │
│ │ YES │ NO │ │ │
│ │ ▼ ▼ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ │ Route to Dynamic│ │ Route by Intent │ │ │
│ │ │ (Confirmation) │ │ (stats/viz/etc) │ │ │
│ │ └─────────────────┘ └─────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────────────────────┼─────────────────────────────────────┐ │
│ │ ▼ │ │
│ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ │
│ │ │ 📊 │ │ 📈 │ │ 📦 │ │ 🤖 │ │ 🔍 │ │ 🔮 │ │ │
│ │ │ Stats │ │ Viz │ │ Agg │ │ Predict│ │ SQL │ │Dynamic │ │ │
│ │ │ Agent │ │ Agent │ │ Agent │ │ Agent │ │ Agent │ │ Agent │ │ │
│ │ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ │ │
│ │ │ │
│ │ SPECIALIZED AGENTS │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ RESPONSE BUILDER │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │ │
│ │ │ Content │ │ Insights │ │ Suggestions │ │ Figures │ │ │
│ │ │ (Markdown) │ │ (Tips) │ │ (Buttons) │ │ (Plotly) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ └───────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────┘消息通信协议（MCP）
代理使用标准化的MCP消息进行通信：
MCPMessage(
id: str, # Unique message identifier
type: MessageType, # QUERY, RESPONSE, ERROR, EVENT
source: str, # Sending agent name
target: str, # Receiving agent name
content: str, # Message content
data: dict, # Additional payload
metadata: dict # Timestamps, context
)数据流
User Query → Master Agent → Intent Detection → Route to Agent → Process → Response
│ │
│ ▼
│ ┌─────────────────┐
│ │ If Dynamic: │
│ │ 1. Offer │
│ │ 2. Plan (LLM) │
│ │ 3. Execute │
│ └─────────────────┘
│ │
└────────────────────────────────────────────◄─┘______________________________________________________________________
📦 安装
先决条件
- Python 3.8或更高版本
- pip（Python包管理器）
- 现代网络浏览器（建议使用Chrome/Edge进行语音功能）
选项1:pip安装
# Clone the repository
git clone https://github.com/hoomanesteki/omniagent.git
cd omniagent
# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Run the application
streamlit run app.py选项2：Conda安装
# Clone the repository
git clone https://github.com/hoomanesteki/omniagent.git
cd omniagent
# Create conda environment
conda env create -f environment.yml
# Activate environment
conda activate omniagent
# Run the application
streamlit run app.py选项3：使用Make
make install # Install dependencies
make run # Run the application
make test # Run all tests______________________________________________________________________
🐳 Docker部署
Docker快速入门
# Build the image
docker build -t omniagent .
# Run the container
docker run -p 8501:8501 omniagent
# With API key for AI features
docker run -p 8501:8501 -e GROQ_API_KEY=your_key omniagent使用Docker Compose（推荐）
# Create .env file with your API key (optional)
echo "GROQ_API_KEY=your_key_here" > .env
# Start the service
docker-compose up -d
# View logs
docker-compose logs -f
# Stop the service
docker-compose downDocker命令参考
| 命令 | 描述 |
|---|---|
docker-compose up -d | 从后台开始 |
docker-compose up -d --build | 重建并启动 |
docker-compose down | 停止并移除容器 |
docker-compose logs -f | 跟踪日志 |
docker-compose restart | 重新启动服务 |
持久性数据
装载一个卷以保存上传的数据：
docker run -p 8501:8501 -v $(pwd)/data:/app/data omniagent______________________________________________________________________
🚀 快速开始
- 加载数据：上传CSV文件或从侧边栏中选择示例数据集
- 提出问题：自然地键入“平均年龄是多少？”或“显示价格直方图”
- 获取见解：查看可视化、统计数据和基于AI的分析
查询示例
| 查询 | 代理 | 结果 |
|---|---|---|
| “显示统计信息” | 📊 统计 | 描述性统计 |
| “年龄直方图” | 📈 Viz | 交互式直方图 |
| “按性别计数” | 📦 汇总 | 分组计数 |
| “预测薪资” | 🤖 预测 | ML模型 |
| “显示前10行” | 🔍 SQL | 数据预览 |
| “计算滚动平均值” | 🔮 动态 | 自定义分析 |
| “计算z分数” | 🔮 动态 | Z分数归一化 |
______________________________________________________________________
🤖 代理
代理概述
| 代理 | 表情符号 | 用途 | 命令示例 |
|---|---|---|---|
| 大师 | 🧠 | 查询路由和编排 | （内部） |
| 统计 | 📊 | 统计分析 | “价格均值”、“漏检” |
| 维兹 | 📈 | 可视化 | “直方图”、“散点图”、“热图” |
| 聚合 | 📦 | GroupBy操作 | “计数”、“求和”、“平均” |
| 预测 | 🤖 | 机器学习 | “预测”、“构建模型” |
| 结构化查询语言 | 🔍 | 数据探索 | “显示行”、“列”、“示例” |
| 动态的 | 🔮 | AI代码生成 | “滚动平均”、“查找异常值”、“z分数” |
| 语音 | 🎤 | 语音识别 | （麦克风输入） |
______________________________________________________________________
🔮 动态代理（AI驱动）
动态代理通过生成和执行自定义Python代码来处理超出内置功能的请求。
三步确认流程
┌─────────────────────────────────────────────────────────────────────────┐
│ DYNAMIC AGENT FLOW │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ STEP 1: OFFER (No LLM call - saves resources) │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ User: "Calculate rolling average of sales" │ │
│ │ │ │
│ │ Agent: "I can create a Rolling/Moving Average analysis. │ │
│ │ This requires AI. Type 'yes' to proceed or 'no'." │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ User types "yes" │
│ ▼ │
│ STEP 2: PLAN (LLM generates code) │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Agent: "Here's my plan: │ │
│ │ │ │
│ │ ```python │ │
│ │ result = df['sales'].rolling(window=7).mean() │ │
│ │ ``` │ │
│ │ │ │
│ │ Type 'yes' to execute or 'no' to cancel." │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ User types "yes" │
│ ▼ │
│ STEP 3: EXECUTE (Sandboxed execution) │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Agent: "✅ Analysis Complete! │ │
│ │ [Shows results and visualization]" │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘支持的分析类型
| 类型 | 关键字 | 示例 |
|---|---|---|
| 滚动/移动平均线 | “滚动”、“移动平均线”、“窗口” | “7天滚动平均线” |
| 异常检测 | “异常值”、“异常”、“IQR” | “使用IQR查找异常值” |
| Z-Score/标准化 | “Z-Score”、“normalize”、“Standardization” | “计算Z-scores” |
| 回归分析 | “回归”、“趋势线” | “带回归线的散点图” |
| 数据分箱 | “箱”、“分类”、“桶” | “分箱年龄” |
| 排名 | “顶部”、“底部”、“排名” | “销售额前10名” |
| 自定义 | 任何其他请求 | “按日期累计的金额” |
启用动态代理
- 启用 AI模式 在侧边栏中
- 输入您的 Groq API密钥 （免费） console.groq.com)
- 点击 验证并保存
- 问任何复杂的问题！
______________________________________________________________________
🎤 语音助手
OmniAgent支持 语音输入 通过浏览器内置的语音识别功能。
⚠️ 备注：声音是 仅语音转文本 （你说话，代理人回复短信）。
需求
| 要求 | 详细信息 |
|---|---|
| 浏览器 | Chrome、Edge或Safari浏览器（Firefox限定） |
| 麦克风 | 内置或外置 |
| 权限 | 必须允许浏览器麦克风访问 |
| 超文本传输安全协议 | 必需（本地主机用于开发） |
如何启用语音
- 切换 启用语音 在侧边栏中
- 点击 "🎤 开始说话” 按钮
- 允许麦克风访问 当浏览器提示时
- 把你的问题说清楚
- 查询已自动提交
浏览器麦克风设置
铬：
- 点击🔒 地址栏中的锁定图标
- 查找“麦克风”→ 选择“允许”
边缘：
- 点击🔒 地址栏中的锁定图标
- 单击“此网站的权限”
- 将麦克风设置为“允许”
游猎：
- 游猎→ 偏好设置→ 网站→ 麦克风
- 考虑OmniAgent站点
语音故障排除
| 问题 | 解决方案 |
|---|---|
| 麦克风不工作 | 检查浏览器权限 |
| 无转录 | 说话清晰，减少背景噪音 |
| “权限被拒绝” | 重置站点权限并再次允许 |
______________________________________________________________________
📁 项目结构
omniagent/
│
├── 📄 app.py # Main Streamlit entry point
├── 📄 requirements.txt # Python dependencies
├── 📄 requirements-dev.txt # Development dependencies
├── 📄 environment.yml # Conda environment
├── 📄 Makefile # Build automation (40+ commands)
├── 📄 Dockerfile # Docker image
├── 📄 docker-compose.yml # Docker Compose config
├── 📄 pytest.ini # Test configuration
├── 📄 README.md # This file
│
├── 📂 core/ # Core utilities
│ ├── __init__.py
│ ├── config.py # Configuration & settings
│ ├── analyzer.py # DataAnalyzer class
│ └── llm.py # LLM client (Groq API)
│
├── 📂 agents/ # Specialized agents
│ ├── __init__.py
│ ├── base.py # BaseAgent abstract class
│ ├── master_agent.py # 🧠 Orchestrator
│ ├── stats_agent.py # 📊 Statistics
│ ├── viz_agent.py # 📈 Visualization
│ ├── aggregate_agent.py # 📦 GroupBy
│ ├── predict_agent.py # 🤖 ML prediction
│ ├── sql_agent.py # 🔍 Data exploration
│ ├── dynamic_agent.py # 🔮 AI code generation
│ └── voice_agent.py # 🎤 Voice input
│
├── 📂 mcp/ # Message Communication Protocol
│ ├── __init__.py
│ └── protocol.py # MCPMessage, MCPBus
│
├── 📂 ui/ # User interface
│ ├── __init__.py
│ ├── components.py # Session, messages
│ ├── sidebar.py # Sidebar UI
│ └── chat.py # Chat interface
│
├── 📂 tests/ # Test suite (195 tests)
│ ├── conftest.py # Shared fixtures
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
│
├── 📂 data/ # Data files
│ ├── samples/ # Sample datasets
│ └── uploads/ # User uploads
│
└── 📂 docs/ # Documentation
├── A_API_REFERENCE.md
├── B_MCP_PROTOCOL.md
├── C_TESTING.md
├── D_SECURITY.md
└── E_DEPLOYMENT.md______________________________________________________________________
🧪 测试
运行测试
# Run all tests
make test
# Run specific test suites
make test-unit # Unit tests only
make test-integration # Integration tests
make test-security # Security tests
# Run with coverage
make coverage
# Run specific test file
pytest tests/unit/test_agents.py -v测试覆盖率
| 模块 | 测试 | 覆盖范围 |
|---|---|---|
| 核心 | 20+ | 配置、数据分析器、LLMClient |
| 代理 | 50+ | 所有7个代理，路由 |
| MCP协议 | 25+ | 消息、总线 |
| 安全 | 40+ | 代码安全，模式 |
| UI | 30+ | 帮助、关于、消息 |
| 集成 | 20+ | 端到端流程 |
______________________________________________________________________
🔒 安全
动态代理安全
动态代理在沙盒环境中执行AI生成的代码，其中包含40多种阻塞模式：
| 类别 | 阻塞模式 |
|---|---|
| 系统访问 | import os, import sys, subprocess |
| 代码注入 | eval(), exec(), compile() |
| 文件操作 | open(), .read(), .write() |
| 网络 | requests., urllib, socket |
| 反思 | globals(), locals(), getattr() |
| 危险邓德尔 | __builtins__, __class__ |
安全流程
Generated Code → Length Check → Pattern Check → Sandboxed Execution
↓ ↓
Too long? Dangerous?
↓ ↓
REJECT REJECT______________________________________________________________________
⚙️ 配置
环境变量
创建一个 .env 文件：
# Groq API (for Dynamic Agent)
GROQ_API_KEY=your_api_key_here
# LLM Settings (optional)
LLM_MODEL=llama-3.3-70b-versatile配置选项
| 设置 | 默认值 | 说明 |
|---|---|---|
PAGE_TITLE | "🤖 OmniAgent“ | 浏览器选项卡标题 |
LLM_MODEL | “骆驼-3.3-70b-多功能” | Groq型号 |
LLM_MAX_TOKENS | 2000 | 最大响应令牌数 |
MAX_SUGGESTIONS | 12 | 建议按钮 |
______________________________________________________________________
🔧 故障排除
常见问题
| 问题 | 解决方案 |
|---|---|
| “没有名为‘streamlit’的模块” | 运行 pip install -r requirements.txt |
| 端口8501正在使用 | 正在使用 streamlit run app.py --server.port=8502 |
| 语音不工作 | 使用Chrome/Edge，允许麦克风 |
| 动态代理失败 | 检查Groq API密钥是否有效 |
| Docker构建失败 | 确保Docker守护进程正在运行 |
获取帮助
- 检查 docs/ 详细文档文件夹
- 在GitHub上打开一个问题
- 在OmniAgent聊天中键入“help”
______________________________________________________________________
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
______________________________________________________________________
👨💻 作者
胡曼·埃斯特基
______________________________________________________________________
🙏 致谢
______________________________________________________________________
Made with ❤️ by Hooman Esteki