使用说明

🤖 OmniAgent：多代理数据分析助手

想象一下，能够像队友一样与你的数据交谈。OmniAgent是一个基于人工智能的多智能体助手，可以让你用简单的英语提问，并立即获得有意义的见解、可视化和预测。无需编码，无需与仪表板搏斗，只需在需要时提供清晰的答案。

大多数人花了太多时间清理数据、弄清楚工具，并试图手动提取见解。OmniAgent通过理解您的意图并自动使用合适的专业代理为您完成工作，将复杂的数据分析转化为简单的对话体验，从而消除了这种摩擦。

📑 目录

特性
系统架构
安装
Docker部署
快速开始
代理
动态代理
语音助手
项目结构
测试
安全
配置
故障排除
许可证

✨ 特性

特性	描述
🗣️ 自然语言	用简单的英语提问
🎤 语音输入	使用浏览器麦克风回答您的问题
🤖 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 down

Docker命令参考

命令	描述
`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许可证获得许可-请参阅许可证文件以获取详细信息。

👨‍💻 作者

胡曼·埃斯特基

🌐 网站：网站.ca
📧 github： @胡曼内斯特基

🙏 致谢

溪流 -Web框架
Plotly -交互式图表
格罗克 -快速LLM推理
Scikit学习 -机器学习

Made with ❤️ by Hooman Esteki