Analytics Agent

分析代理 v2

由OpenAI Agents SDK和模型上下文协议（MCP）驱动的自助分析AI代理

版本2.0.0\ 状态📋 规划阶段\ 之前的版本: 分析代理 (FastAPI + 函数调用)

______________________________________________________________________

概述

Analytics Agent v2 是一个基于网页的AI助手，使用户能够使用自然语言查询复杂的数据源。它利用了：

• OpenAI智能体软件开发工具包 用于强大的代理编排
• 模型上下文协议（MCP） 用于通用数据源集成
• FastAPI 对于支持流式处理的后端API
• Next.js 用于现代网页聊天界面

主要特点:

• 🔌（电源插头/插座） MCP-无关（或MCP-无特定偏好）与任何MCP服务器兼容，无需代码更改
• 💬 多轮对话在后续问题中保持上下文连贯性
• ⚡（闪电符号，常用于表示快速、能量或电力等概念） 实时流媒体实时查看代理的工作进度
• 📊（表格） 智能上下文管理高效处理大型模式
• 🔍 看起来像是放大镜的符号，可以翻译为“🔍 放大镜”或者根据上下文具体含义翻译为“🔍 查看/放大/仔细观察”等。由于没有具体上下文，这里给出一个通用的翻译：“🔍 放大镜”。 完全可观测性查看工具调用、参数和响应
• 📝 审计日志记录每次交互均记录在案以确保合规
• 🎯（瞄准目标） 会话管理用于追踪对话的独特ID

______________________________________________________________________

文档

______________________________________________________________________

快速入门

先决条件

• python≥3.10
• Node.js大于等于18
• 紫外线Python包管理器（安装）
• OpenAI API密钥来自...的获取 platform.openai.com（直接翻译为中文即“openai的平台.com”，但通常我们直接保留网址原样，因为网址本身是国际通用的，无需翻译，这里仅说明其含义）
• MCP服务器运行中的实例（例如，Cube.js MCP 服务器）

安装

# Clone repository
cd /Users/babak.bashiri/workspace/analytics-agent-v2

# Backend setup
cd backend
uv sync
cp .env.example .env
# Edit .env with your credentials

# Frontend setup
cd ../frontend
npm install

# MCP Server (if not already running)
# Example: Cube MCP server
cd /Users/babak.bashiri/workspace/data-mcp/servers/cube
uv run cube-mcp-server

配置

1. 环境变量 (.env）：

OPENAI_API_KEY=sk-...
CUBE_API_URL=http://localhost:4000
CUBE_API_SECRET=your_secret
LOG_LEVEL=INFO

2. 大语言模型（LLM）配置 (config/llm_config.json）：

{
  "provider": "openai",
  "model": "gpt-4o",
  "temperature": 0.1,
  "api_key_env": "OPENAI_API_KEY"
}

3. MCP配置 (config/mcp_config.json)：

{
  "servers": {
    "cube-local": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "cube-mcp-server"],
      "env": {
        "CUBE_API_URL": "${CUBE_API_URL}",
        "CUBE_API_SECRET": "${CUBE_API_SECRET}"
      }
    }
  }
}

跑步

# Terminal 1: Backend
cd backend
uv run uvicorn main:app --reload --port 8000

# Terminal 2: Frontend
cd frontend
npm run dev

# Open browser
open http://localhost:3002

______________________________________________________________________

建筑

Web Browser (Next.js)
       │
       │ HTTP + SSE
       ▼
FastAPI Server
       │
       ├─ OpenAI Agents SDK
       │   ├─ Agent (instructions + tools)
       │   ├─ Session (conversation history)
       │   └─ Runner (execution orchestration)
       │
       ├─ MCP Service (generic client)
       │   ├─ Tool discovery
       │   ├─ Tool execution
       │   └─ Prompt fetching
       │
       └─ LLM Service (OpenAI)
              │
              ▼
         MCP Servers (stdio/HTTP)
              │
              ├─ Cube.js
              ├─ DataHub
              └─ Snowflake

关键原则该代理已 零知识 特定数据源的。所有与数据相关的特定逻辑都存在于MCP服务器中。

______________________________________________________________________

从v1中获得的关键学习点

行之有效的✅

1. MCP-无感知架构 - 数据源的切换非常顺畅
2. 模式总结 - 将上下文管理中的关键参数从85K减少到10K tokens
3. 实时流媒体 - 用户喜欢看到代理的进步
4. 工具轨迹可视化 - 调试和透明度的提升改善了用户体验
5. 会话ID生成 - 代理控制的ID比大型语言模型生成的更可靠

挑战与解决方案 🔧

______________________________________________________________________

发展路线图

第一阶段：核心代理（第1-2周）

• \[x\] 设置项目结构
• \[ \] 实现MCP服务层
• \[ \] 创建代理工厂
• \[ \] 使用Cube MCP服务器进行测试
• \[ \] 基本的 FastAPI 端点

第二阶段：直播与会议（第三周）

• \[ \] 实现SSE流
• \[ \] 会话管理
• \[ \] 上下文窗口优化
• \[ \] 多轮对话

第三阶段：前端开发（第4周）

• \[ \] Next.js 聊天界面
• \[ \] 实时更新
• \[ \] 工具轨迹可视化
• \[ \] 代币使用指标

第四阶段：测试与完善（第5周）

• \[ \] 单元测试
• \[ \] 集成测试
• \[ \] 性能优化
• \[ \] 文档

第五阶段：部署（第6周）

• \[ \] Docker 安装设置
• \[ \] Kubernetes 清单文件
• \[ \] CI/CD 流水线
• \[ \] 生产部署

______________________________________________________________________

对比：v1 与 v2

v1（FastAPI + OpenAI 函数调用）

优点:

• ✅ 对执行流程的完全控制
• ✅ 易于调试（逻辑清晰可见）
• ✅ 除OpenAI外，无其他外部依赖

缺点：

• ❌ 手动追踪对话历史
• ❌ 自定义工具执行循环（易出错）
• ❌ 手动上下文窗口管理
• ❌ 没有内置的追踪/可观测性功能

代码行数~960（仅main.py）

v2（OpenAI 代理SDK）

优点:

• ✅ SDK 自动处理对话历史
• ✅ 强大的工具执行功能，支持重试
• ✅ 内置追踪和可观测性
• ✅ 包含会话管理功能
• ✅ 更好的错误处理

缺点：

• ⚠️ 控制力减弱（SDK 抽象了细节）
• ⚠️ 需要理解SDK基础元素

预期代码行数（LOC）~400-500（主要逻辑）

何时使用每个（工具/方法）

如果满足以下条件，请使用v1（手动）：

• 你需要对执行过程拥有完全控制权
• 你想了解每一个细节
• 你在做原型设计或学习

如果使用v2（SDK）的情况是：

• 你想要的是生产就绪的稳健性
• 你更看重可维护性而非控制力
• 你需要内置的可观测性
• 你正在为规模化发展而构建

______________________________________________________________________

测试

单元测试

cd backend
uv run pytest tests/test_mcp_service.py -v
uv run pytest tests/test_agent.py -v

集成测试

uv run pytest tests/test_e2e.py -v

手动测试

# Test MCP connection
curl http://localhost:8000/api/mcp/tools

# Test chat endpoint
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What data is available?"}'

______________________________________________________________________

故障排除

后端无法启动

错误： ModuleNotFoundError: No module named 'agents'

修复：

cd backend
uv sync

MCP连接失败

错误： MCP connection test failed

检查:

1. MCP服务器正在运行： lsof -ti:3001
2. 环境变量已设置： cat .env
3. 配置正确： cat config/mcp_config.json

修复：

# Restart MCP server
cd /path/to/mcp-server
uv run cube-mcp-server

上下文限制超出

错误： context_length_exceeded

原因模式过大 + 对话过长

修复模式摘要应该能够处理这个问题。如果问题仍然存在：

1. 检查是否正在使用模式摘要（设置为2+）
2. 验证上下文修剪功能是否正常工作
3. 考虑进行简短的交流或开启新的对话

工具调用显示为“错误”

检查：

1. MCP服务器日志： tail -f /tmp/mcp-server.log
2. 工具参数有效
3. MCP服务器可以访问数据源

______________________________________________________________________

做出贡献

代码风格

# Format code
uv run ruff format .

# Lint
uv run ruff check .

# Type check
uv run mypy .

添加新的MCP服务器

1. 添加服务器配置到 config/mcp_config.json:

{
  "servers": {
    "my-server": {
      "type": "stdio",
      "command": "my-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

1. 重启后端代理 - 代理将自动发现工具

1. 无需更改代码！ 🎉

______________________________________________________________________

常见问题解答（FAQ）

问：这与v1有什么不同？

A.v2版本使用OpenAI Agents SDK进行编排，而不是手动循环。这提供了更好的鲁棒性、内置的会话管理，以及更少的维护代码。

问：我可以使用不同的大型语言模型（LLM）提供商吗？

A.目前仅支持OpenAI。未来版本可能通过提供商抽象支持Anthropic、Cohere等。

问：如何添加新的数据源？

A.为您的数据源创建或部署一个MCP服务器，并将其添加到 mcp_config.json代理自动发现并使用新工具。

问：为什么使用MCP而不是直接调用API？

A.MCP 提供了一种标准协议，用于工具发现、模式检查和执行。这使得代理具有真正的通用性——它可以在不修改代码的情况下与任何兼容 MCP 的数据源一起工作。

问：每次查询的费用是多少？

A.取决于：

• 模型：gpt-4o ~每查询0.01-0.05美元
• 模式大小：首次查询成本更高（完整模式）
• 对话长度：越长 = 上下文越多 = 成本越高

典型费用：每次多轮对话0.02-0.10美元。

问：我的数据安全吗？

A.：

• 数据永远不会离开您的基础设施（MCP服务器控制访问）
• 代理仅能看到MCP服务器返回的内容
• 所有查询均已记录，以供审计
• 在生产环境中添加认证（未来实施）

______________________________________________________________________

资源

文档

• OpenAI智能体SDK文档 （有空时）
• 模型上下文协议规范
• FastAPI 文档
• Next.js 文档

相关项目

• 分析代理 - v1版本的实现
• \data-mcp\ 可以翻译为“数据-MCP”或根据上下文具体含义进行更贴切的翻译，但直接翻译就是“数据-MCP”。在这里，\MCP\ 可能代表某个特定的缩写或术语，需要根据具体上下文来确定其准确含义。如果 \MCP\ 在某个领域有特定的含义，比如“多通道处理”（Multi-Channel Processing）或其他专业术语，那么翻译时可以结合这个含义进行更准确的表述。不过，没有具体上下文的情况下，直接翻译为“数据-MCP”是较为通用的做法 - Cube.js MCP 服务器
• MCP服务器 - 其他MCP服务器

支持

• GitHub 问题：\[仓库链接\]
• Slack: #分析代理（或 #数据分析助手，根据上下文具体翻译）
• 电子邮箱：data-team@example.com

______________________________________________________________________

许可证

麻省理工学院（MIT）

______________________________________________________________________

致谢

由数据工程团队构建，融合了以下方面的学习成果：

• v1 实现（FastAPI + 函数调用）
• 来自50多名用户的生产使用反馈
• OpenAI Agents SDK 最佳实践
• MCP协议社区

特别感谢所有v1版本的用户，帮助我们发现并修复了边缘情况！ 🙏

______________________________________________________________________

状态准备实施

下一步评论 TECHNICAL_SPECS.md 翻译为中文是：“技术规格说明文件.md” 并开始第一阶段的实施。