带反射的ADK SQL生成代理
此项目演示了如何使用 Google Gen AI代理开发工具包（ADK） 和 MCP工具箱.
它的特点是 反射回路 在那里验证生成的SQL查询 使用BigQuery dry_run 执行前的能力，确保高 可靠性和安全性。
该项目还包括一个可选 Dataplex集成 这丰富了 代理通过从数据中获取语义上下文来理解数据 目录。
建筑
代理由几个按顺序编排的子代理组成：
- 语义丰富器 （可选，如果
DATAPLEX_ENABLED=true):
- 术语提取器：从用户的查询中提取关键业务术语。 - Dataplex搜索器：在Dataplex中搜索与表和元数据相关的内容 提取的术语。
- 架构检查器：查询BigQuery
INFORMATION_SCHEMA通过MCP
理解数据集。如果启用了Dataplex，它将使用筛选后的表 语义丰富器中的列表。
- SQL生成器循环 (
LoopAgent):
- 发电机：根据用户问题、模式和可选条件起草SQL 语义上下文来自Dataplex。 - 验证器：通过MCP执行SQL的模拟运行，以检查语法 以及语义错误。 - 审稿人：分析模拟运行结果。如果失败，它提供 指导返回生成器以进行下一次迭代。
- 最终响应者：执行已验证的SQL并回答用户的问题
数据问题。
先决条件
- Python 3.11+
uv用于依赖性管理。- 谷歌云SDK(
gcloud)
安装和配置。
mcp-toolbox已安装二进制文件
以及您的系统PATH。
- 地形 安装。
设置
- 克隆存储库：
git clone https://github.com/cwest/adk-sql-reflection-pattern.git
cd adk-sql-reflection-pattern- 安装依赖项：
此项目使用 uv 管理依赖关系。确保您拥有一切 用于开发和运行标准和Dataplex的软件包 模式下，安装带有所有可选依赖项的项目：
uv pip install ".[dev,dataplex]"这将安装基本要求以及用于测试和Dataplex的软件包 整合。
- 使用Google Cloud进行身份验证： 确保您具有应用程序默认值
已设置凭据（ADC）。
gcloud auth application-default login- 配置环境： 复制
.env.example到.env并设置您的
GOOGLE_CLOUD_PROJECT。其他变量取决于您希望的模式 跑。
cp .env.example .env______________________________________________________________________
运行代理
这个项目有两种不同的模式。
标准模式（默认）
此模式使用公共 bigquery-public-data.google_trends 数据集和does 不 需要任何地形设置。
- 配置环境： 确保
DATAPLEX_ENABLED设置为false或
在你的评论 .env 文件。你只需要设置你的项目ID。
GOOGLE_CLOUD_PROJECT=your-project-id
# DATAPLEX_ENABLED=false- 运行代理：
uv run honcho start- 测试代理： 打开ADK Web UI（通常
http://localhost:8000)
并使用以下示例查询 tests/test_cases_google_trends.md.
Dataplex启用模式
此模式演示了代理如何使用Dataplex中的语义元数据 回答更复杂的问题。它需要提供一个电子商务示例 使用Terraform的数据集和Dataplex资源。
- 配置环境： 更新您的
.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- 使用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"- 运行代理：
uv run honcho start- 测试代理： 打开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策略定义（占位符）。