AI导哈

SQL生成代理

一个基于Google Gen AI Agent Development Kit (ADK)和MCP Toolbox的SQL生成代理，通过反射循环验证SQL查询的可靠性和安全性，支持Dataplex集成以增强数据理解。

  • by cwest
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 cwest/adk-sql-reflection-pattern

使用说明

带反射的ADK SQL生成代理

此项目演示了如何使用 Google Gen AI代理开发工具包（ADK） 和 MCP工具箱.

它的特点是 反射回路 在那里验证生成的SQL查询 使用BigQuery dry_run 执行前的能力，确保高 可靠性和安全性。

该项目还包括一个可选 Dataplex集成 这丰富了 代理通过从数据中获取语义上下文来理解数据 目录。

建筑

代理由几个按顺序编排的子代理组成：

  1. 语义丰富器 （可选，如果 DATAPLEX_ENABLED=true):
    • 术语提取器：从用户的查询中提取关键业务术语。
    • Dataplex搜索器：在Dataplex中搜索与表和元数据相关的内容 提取的术语。
  2. 架构检查器：查询BigQuery INFORMATION_SCHEMA 通过MCP 理解数据集。如果启用了Dataplex，它将使用筛选后的表 语义丰富器中的列表。
  3. SQL生成器循环 (LoopAgent):
    • 发电机：根据用户问题、模式和可选条件起草SQL 语义上下文来自Dataplex。
    • 验证器：通过MCP执行SQL的模拟运行，以检查语法 以及语义错误。
    • 审稿人：分析模拟运行结果。如果失败，它提供 指导返回生成器以进行下一次迭代。
  4. 最终响应者：执行已验证的SQL并回答用户的问题 数据问题。

先决条件

设置

  1. 克隆存储库：

    git clone https://github.com/cwest/adk-sql-reflection-pattern.git
cd adk-sql-reflection-pattern

  2. 安装依赖项：

    此项目使用 uv 管理依赖关系。确保您拥有一切 用于开发和运行标准和Dataplex的软件包 模式下，安装带有所有可选依赖项的项目：

    uv pip install ".[dev,dataplex]"

    这将安装基本要求以及用于测试和Dataplex的软件包 整合。

  3. 使用Google Cloud进行身份验证： 确保您具有应用程序默认值 已设置凭据（ADC）。

    gcloud auth application-default login

  4. 配置环境： 复制 .env.example 到 .env 并设置您的 GOOGLE_CLOUD_PROJECT。其他变量取决于您希望的模式 跑。

    cp .env.example .env

运行代理

这个项目有两种不同的模式。

标准模式（默认）

此模式使用公共 bigquery-public-data.google_trends 数据集和does 不 需要任何地形设置。

  1. 配置环境： 确保 DATAPLEX_ENABLED 设置为 false 或 在你的评论 .env 文件。你只需要设置你的项目ID。

    GOOGLE_CLOUD_PROJECT=your-project-id
# DATAPLEX_ENABLED=false

  2. 运行代理：

    uv run honcho start

  3. 测试代理： 打开ADK Web UI（通常 http://localhost:8000) 并使用以下示例查询 tests/test_cases_google_trends.md.

Dataplex启用模式

此模式演示了代理如何使用Dataplex中的语义元数据 回答更复杂的问题。它需要提供一个电子商务示例 使用Terraform的数据集和Dataplex资源。

  1. 配置环境： 更新您的 .env 启用Dataplex模式的文件 并配置必要的资源ID。

    GOOGLE_CLOUD_PROJECT=your-project-id
DATAPLEX_ENABLED=true
DATAPLEX_LAKE_ID=e-commerce-lake
DATAPLEX_ZONE_ID=analytics-curated-zone
DATAPLEX_LOCATION=us-central1

  2. 使用Terraform提供基础设施： 地形配置 将自动：

    • 为电子商务示例创建BigQuery数据集和表。
    • 创建Dataplex湖、区域和资源。
    • 运行一个脚本来生成示例数据并将其加载到BigQuery中。
    • 运行脚本将语义元数据从Dataplex附加到BigQuery 桌子。

    首先，初始化Terraform：

    terraform -chdir=terraform init

    然后，应用配置。您必须为项目提供变量 以及您要授予Dataplex管理权限的用户。

    export GCP_PROJECT="your-project-id"
export GCP_REGION="us-central1"
export DATAPLEX_ADMIN="your-email@example.com"

terraform -chdir=terraform apply -auto-approve \
  -var="project_id=$GCP_PROJECT" \
  -var="google_cloud_project=$GCP_PROJECT" \
  -var="region=$GCP_REGION" \
  -var="dataplex_admin_user=$DATAPLEX_ADMIN" \
  -var="dataplex_lake_id=e-commerce-lake" \
  -var="dataplex_zone_id=analytics-curated-zone"

  3. 运行代理：

    uv run honcho start

  4. 测试代理： 打开ADK Web UI并使用以下示例查询 tests/test_cases_dataplex.md这些 查询是专门为测试代理对业务规则的使用而设计的 以及Dataplex的语义理解。

这将开始：

  • 工具箱：在端口5000上公开BigQuery和Dataplex工具的MCP服务器。
  • ADK Web用户界面：代理界面，通常可在以下网址访问 http://localhost:8000 （检查控制台输出以获取确切的URL）。

项目结构

  • agents/sql_agent/：包含代理实现。
    • agent.py：根 SequentialAgent 定义。
    • semantic_enricher.py：使用Dataplex丰富查询的可选代理 背景。
    • schema_inspector.py：用于检索数据库架构的代理。
    • sql_generator_loop.py：核心反射回路（生成器、验证器、， 审阅者）。
    • final_responder.py：执行最终查询和应答的代理。
    • prompts.py：SQL生成的详细系统说明。
    • config.py：共享配置（MCP连接参数）。
  • tools.yaml：MCP工具箱的配置，定义BigQuery和 Dataplex工具。
  • Procfile：定义服务 honcho.
  • pyproject.toml：项目依赖关系。
  • terraform/：包含用于配置Google的Terraform配置文件 云资源。
    • main.tf：主Terraform配置，包括提供程序设置。
    • variables.tf：Terraform脚本的输入变量。
    • bigquery.tf：BigQuery数据集和表定义。
    • dataplex.tf：Dataplex湖、区域、资源和方面类型定义。
    • iam.tf：IAM策略定义（占位符）。

相关 MCP