使用说明

分析代理 v2

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

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

概述

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

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

主要特点:

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

文档

文件	描述
PRD.md 翻译成中文是：“产品需求文档（.md 格式）”	完整的产品需求文档
`TECHNICAL_SPECS.md` 翻译为中文是：“技术规格说明书.md”	详细的实施规范
README.md	此文件 - 项目概述和快速入门

快速入门

先决条件

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中获得的关键学习点

行之有效的✅

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

挑战与解决方案 🔧

挑战	v1 方法	v2 改进
上下文限制错误	手动修剪逻辑	SDK 会话 + 强力摘要
工具执行错误	手动重试循环	SDK Runner 自动处理
查询中的类型混淆	摘要中无类型信息	在模式摘要中包含类型
UI中重复的工具调用	复杂的合并逻辑	更好的事件排序
会话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

检查:

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

修复：

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

上下文限制超出

错误： context_length_exceeded

原因模式过大 + 对话过长

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

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

工具调用显示为“错误”

检查：

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

做出贡献

代码风格

# Format code
uv run ruff format .

# Lint
uv run ruff check .

# Type check
uv run mypy .

添加新的MCP服务器

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

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

重启后端代理 - 代理将自动发现工具
无需更改代码！ 🎉

常见问题解答（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服务器返回的内容
所有查询均已记录，以供审计
在生产环境中添加认证（未来实施）

资源

文档

支持

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

许可证

麻省理工学院（MIT）

致谢

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

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

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

状态准备实施

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