Data Planning Agent

数据规划代理

将高级业务意图转换为结构化的MCP（模型上下文协议）代理 数据产品要求提示 （数据PRP）通过人工智能驱动的对话细化。

概述

数据规划代理是用于自动生成商业智能仪表板的多代理系统中的第一个组件。它通过以下方式帮助数据科学家和分析师收集全面的需求：

1. 开始 具有模糊的商业意图
2. 精炼 通过人工智能引导澄清问题
3. 生成 结构化、机器可读的数据PRP文档

输出数据PRP用作 数据发现代理，实现自动数据源识别和分析。

特性

• 🤖 AI驱动的对话：使用Gemini 2.5 Pro进行智能需求收集
• ❓ 聪明提问：一次最多可提出4个重点问题，偏向于多选以提高效率
• 📋 结构化输出：生成标准化的数据PRP标记文档
• 💾 灵活的存储：支持两个地面军事系统(gs://)以及本地文件路径
• 🎨 组织背景：加载自定义上下文文件，以根据您的组织定制代理行为
• 🔌 MCP集成：完整的MCP服务器实现（stdio+HTTP传输）
• 🖥️ 交互式CLI：直接从命令行测试对话
• 🎯 光标兼容：作为Cursor MCP服务器无缝工作

安装

先决条件

• Python 3.10或更高版本
• 依赖管理诗
• Gemini API密钥

设置

1. 克隆存储库：

cd /home/user/git/data-planning-agent

1. 使用Poetry安装依赖项：

poetry install

1. 创建一个 .env 示例中的文件：

cp .env.example .env

1. 在中配置环境变量 .env:

# Required
GEMINI_API_KEY=your-gemini-api-key-here

# Optional (with defaults)
GEMINI_MODEL=gemini-2.5-pro
OUTPUT_DIR=./output
MCP_TRANSPORT=stdio
LOG_LEVEL=INFO

用法

交互式CLI模式

测试规划代理的最简单方法：

poetry run planning-agent

这将启动一个交互式会话，引导您完成以下操作：

1. 输入您的初始商业意图
2. 回答澄清问题
3. 生成并保存最终数据PRP

MCP服务器模式（用于游标集成）

作为MCP服务器运行以与Cursor集成：

# Stdio transport (default)
poetry run python -m data_planning_agent.mcp

# HTTP transport
MCP_TRANSPORT=http poetry run python -m data_planning_agent.mcp

与光标一起使用

将此配置添加到您的 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "data-planning-agent": {
      "command": "poetry",
      "args": ["run", "python", "-m", "data_planning_agent.mcp"],
      "cwd": "/home/user/git/data-planning-agent",
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

然后在Cursor中使用这些MCP工具：

1. start_planning_session

开始新的计划会议：

{
  "initial_intent": "We want to provide the merchandising team insights into trending items in region 7"
}

返回会话ID和初始澄清问题。

2. continue_conversation

继续对话并回复：

{
  "session_id": "your-session-id",
  "user_response": "a) Regional managers, they need both summary and detail"
}

返回后续问题或完成通知。

3. generate_data_prp

生成最终数据PRP：

{
  "session_id": "your-session-id",
  "output_path": "gs://my-bucket/planning/data_prp.md",
  "save_to_file": true
}

返回生成的数据PRP标记和文件位置。

对话流程示例

User: "We want to provide the merchandising team insights into trending items in region 7"

Agent: Based on your intent, I have a few questions:

1. What is the primary audience for this analysis?
   a) Executives (high-level summary)
   b) Regional managers (summary + detail)
   c) Data analysts (detailed data)
   d) Other (please specify)

2. What key metrics define "trending" for your use case?
   a) Unit sales volume
   b) Revenue growth
   c) Profit margin
   d) Multiple metrics (please specify)

3. What time frame should we analyze?
   a) Last 4 weeks
   b) Last 8 weeks
   c) Last quarter
   d) Custom period (please specify)

4. Do you need comparisons to previous periods?
   a) Yes, week-over-week
   b) Yes, year-over-year
   c) Yes, both
   d) No comparisons needed

User: "b) Regional managers
       a) Unit sales volume
       b) Last 8 weeks  
       a) Yes, week-over-week"

Agent: [Asks follow-up questions or generates Data PRP]

数据PRP输出格式

生成的数据PRP遵循以下结构：

# Data Product Requirement Prompt

## 1. Executive Summary

* **Objective:** [One-sentence business goal]
* **Target Audience:** [Who will use this]
* **Key Question:** [Primary question to answer]

## 2. Business Context

[Detailed paragraph explaining the scenario and decisions to be made]

## 3. Data Requirements

### 3.1. Key Metrics

* [Metric 1]
* [Metric 2]

### 3.2. Dimensions & Breakdowns

* [Dimension 1]
* [Dimension 2]

### 3.3. Filters

* [Filter 1]
* [Filter 2]

## 4. Success Criteria

* **Primary Metric:** [Main success indicator]
* **Timeline:** [Delivery expectations]

组织背景

通过加载影响所有人工智能交互的上下文文件，规划代理可以根据您的组织进行定制。

什么是组织环境？

上下文文件是标记文档，为AI提供：

• 公司特定术语和标准
• 标准操作程序
• 数据治理政策
• 技术限制
• 通信偏好

如何使用上下文

1. 创建上下文目录 （本地或GCS）：

   mkdir ./context

1. 添加标记文件 凭借您的组织知识：

   # context/01_organization.md
   # context/02_sop.md
   # context/03_constraints.md

1. 配置代理 使用您的上下文：

   # .env
   CONTEXT_DIR=./context
   # or for GCS:
   # CONTEXT_DIR=gs://my-bucket/planning-context/

1. 文件会自动加载 当代理启动时

示例上下文文件

请参阅 context.example/ 真实示例目录：

• 01_组织.md：组织背景、团队结构、沟通方式
• 02_sop.md：标准作业程序、术语标准、数据治理
• 03_限制.md：技术限制、首选分析模式、预算考虑

益处

• 一致性：代理使用您的术语并遵循您的SOP
• 治理：自动应用您的数据治理策略
• 效率：无需在每次对话中重复组织背景
• 灵活性：更新上下文文件而不更改代码

情境行为

• 上下文是 在所有AI提示前添加 （初始问题、跟进、PRP生成）
• 上下文是 对用户隐藏 -它默默地引导代理行为
• 上下文是 可选的 -代理在没有它的情况下正常工作
• 多个文件 按字母顺序连接
• 支持两者 本地 和 格拉斯哥昏迷量表 存储

配置

所有配置都通过环境变量进行管理。看 .env.example 完整列表：

建筑

组件

• MCP服务器 (src/data_planning_agent/mcp/)

- Stdio和HTTP传输 - JSON-RPC 2.0协议 - SSE支持实时更新

• 客户 (src/data_planning_agent/clients/)

- GeminiClient：Gemini API对话包装器 - StorageClient：GCS和本地文件I/O

• 核心逻辑 (src/data_planning_agent/core/)

- ConversationManager：会话状态管理 - RequirementRefiner：对话编排 - PRPGenerator：数据PRP降价生成

• 模型 (src/data_planning_agent/models/)

- PlanningSession：会话数据模型 - DataProductRequirementPrompt：PRP架构

• 命令行界面 (src/data_planning_agent/cli/)

- 交互式命令行界面

与数据发现代理集成

┌─────────────────────┐
│  Planning Agent     │  1. Gathers requirements
│  (This repo)        │     through conversation
└──────────┬──────────┘
           │
           │ Data PRP.md
           ▼
┌─────────────────────┐
│ Data Discovery      │  2. Searches for relevant
│ Agent               │     datasets using PRP
└──────────┬──────────┘
           │
           │ Discovered datasets
           ▼
┌─────────────────────┐
│ Query Generation    │  3. Generates SQL queries
│ Agent               │     for analysis
└─────────────────────┘

测试

使用pytest运行测试：

# All tests
poetry run pytest

# Unit tests only
poetry run pytest tests/unit/

# With coverage
poetry run pytest --cov=data_planning_agent --cov-report=html

发展

代码质量

黑色格式代码：

poetry run black src/ tests/

带褶边的棉绒：

poetry run ruff check src/ tests/

项目结构

data-planning-agent/
├── src/data_planning_agent/
│   ├── mcp/              # MCP server implementation
│   ├── clients/          # External service clients
│   ├── core/             # Business logic
│   ├── models/           # Data models
│   └── cli/              # Command-line interface
├── tests/                # Test suite
├── pyproject.toml        # Poetry configuration
├── .env.example          # Environment variables template
└── README.md             # This file

故障排除

常见问题

问题: GEMINI_API_KEY not set

• 解决方案：确保您的 .env 文件包含有效的Gemini API密钥

问题：会话超时或达到最大圈数

• 解决方案：增加 MAX_CONVERSATION_TURNS 在 .env

问题：GCS写入权限被拒绝

• 解决方案：确保您的GCP凭据具有对存储桶的写入权限

问题：游标无法连接到MCP服务器

• 解决方案：检查一下 MCP_TRANSPORT=stdio 和那个 cwd 路径正确

许可证

Apache许可证2.0-请参阅 许可证 了解详情。

贡献

欢迎投稿！拜托：

1. 复刻仓库
2. 创建要素分支
3. 添加新功能的测试
4. 确保所有测试通过
5. 提交拉取请求

相关项目

• 数据发现代理 -发现相关数据集
• 查询生成代理 -生成SQL查询
• 数据发现基础架构 -GCP基础设施

支持

对于问题、疑问或贡献，请在GitHub上打开问题。