使用 Data Agent Kit 和 Antigravity IDE 进行分析

1. 简介

周一早上，财务总监刚刚给你发了条消息。本月平均订单价值下降了 7%，但总收入保持不变。但有些事情并不合理，董事会要求在周五之前得到答复。

您的公司 Cymbal Pets 是美国最大的在线宠物用品零售商之一。您所需的数据分散在三项 Google Cloud 服务中：BigQuery 中的销售和订单历史记录、Cloud SQL 中的客户和产品记录，以及 Cloud Storage 中的营销文件。通常情况下，像这样进行跨服务调查意味着需要在控制台之间切换、编写连接模板，并手动将结果拼接在一起。

在此 Codelab 中，您将使用 Antigravity IDE 中的 Google Cloud 数据代理套件 (DAK)，通过自然语言来调查异常情况。您只需描述要查找的内容，AI 智能体便会处理 BigQuery、Cloud SQL 和 Cloud Storage 之间的连接、SQL 和跨服务联接。破解此案后，您将要求智能体构建 dbt 流水线，以将您的发现投入实际应用，调试真实的数据建模 bug，并向首席财务官提供有预测支持的建议。

刚开始接触 Antigravity？如果您是首次使用该 IDE，请先参阅 Google Antigravity 使用入门。

您将执行的操作

• 使用 Knowledge Catalog 发现 BigQuery、Cloud SQL 和 Cloud Storage 中的数据资产
• 使用 MCP 工具在一次对话中查询多项服务，从而调查异常情况
• 构建 dbt 流水线，以使用暂存模型和自动化测试来暂存和联接跨服务数据
• 调试数据建模问题，因为代理会自行诊断并重构扇出 bug
• 使用 BigQuery 的 AI.FORECAST预测未来趋势并提供数据驱动的建议

所需条件

• 网络浏览器，例如 Chrome
• Antigravity IDE
• 启用了结算功能且可访问 Google Cloud 控制台的 Google Cloud 项目（我们建议使用新的专用项目来完成实践实验）
• 基本熟悉 SQL 和 Google Cloud 控制台

此 Codelab 适合中级数据从业者（分析工程师、数据分析师、数据科学家）。

本 Codelab 中创建的资源费用应低于 5 美元。请务必按照实验结束时的清理说明删除已预配的资源。

选择工具：本实验使用 Antigravity IDE。我们很快就会发布此调查的替代版本，这些版本专为 Antigravity 2.0、Antigravity CLI 和 Claude Code 量身打造！

2. 准备工作

在此部分中，您将运行一个设置脚本，该脚本会预配整个实验环境：包含订单数据的 BigQuery 数据集、包含客户和产品数据的 Cloud SQL Postgres 实例，以及包含促销活动记录的 Cloud Storage 存储分区。该脚本大约需要 8-10 分钟才能完成，Cloud SQL 配置是瓶颈。

选择或创建项目

在 Google Cloud 控制台中，选择现有项目或创建新项目。

验证结算信息

确保您的 Google Cloud 项目已启用结算功能。如需详细了解如何执行此操作，请参阅本指南。

启动 Cloud Shell

您将使用 Google Cloud Shell 运行设置脚本。

1. 打开 Google Cloud 控制台，然后点击窗口顶部的激活 Cloud Shell。

2. 连接成功后，设置项目 ID 并确认环境：

gcloud config set project <<YOUR_PROJECT_ID>>
export PROJECT_ID=$(gcloud config get-value project)

您应会看到如下所示的消息：

Your active configuration is: [cloudshell-####]
Updated property [core/project]

克隆存储库

将 Codelab 代码库克隆到 Cloud Shell 环境：

cd ~/
git clone --filter=blob:none --no-checkout https://github.com/GoogleCloudPlatform/devrel-demos.git
cd ~/devrel-demos
git sparse-checkout init --cone
git sparse-checkout set codelabs/agentic-data-labs
git checkout main
cd codelabs/agentic-data-labs/

运行设置脚本

设置脚本会自动准备整个实验环境，以便您直接开始调查：

cd ~/devrel-demos/codelabs/agentic-data-labs/scripts
chmod +x setup.sh setup_sql.sh
./setup.sh

setup.sh 的作用：

1. 启用 API：激活 BigQuery、Cloud SQL、Cloud Storage、Knowledge Catalog (Dataplex) 和支持性基础架构 API。
2. 创建 BigQuery 资源：将示例订单历史记录加载到 cymbal_pets 数据集中。
3. 创建 Cloud Storage 存储分区：将宣传广告系列记录上传到原始 GCS 存储分区。
4. 预配 Cloud SQL：生成一个后台工作器来构建 PostgreSQL 实例 (cymbal-pets-ops)。
5. 生成 .env：保存设置和拆解脚本的环境和数据库配置。

设置脚本创建的资源会在最终的清理步骤中通过 ./teardown.sh 删除。

完成后，您将看到前台环境的摘要：

╔══════════════════════════════════════════════════════╗
║   Base Setup complete!                               ║
╚══════════════════════════════════════════════════════╝

Your core BigQuery and GCS assets are ready.
Cloud SQL is currently provisioning in the background and will be fully ready by Step 4.

  BigQuery:   YOUR_PROJECT_ID.cymbal_pets
              ├── orders
              └── order_items

  GCS:        gs://YOUR_PROJECT_ID-cymbal-pets-raw
              └── promo_events.json

在您继续执行本实验的后续步骤时，系统会在后台预配数据库并为其植入初始数据。您可以使用以下命令在单独的终端面板中随时监控其进度：

tail -f /tmp/cloudsql_setup.log

请注意数据架构：历史销售记录（订单和订单项）存储在 BigQuery 中，而运营应用数据（客户、宠物资料和产品）存储在 Cloud SQL 中。这种拆分反映了现实世界中的组织，在这些组织中，分析仓库和运营数据库会保存不同的数据。

这里的基础数据集是官方的 Cymbal Pets 电子商务数据集（约 190 万个订单，涉及 9.2 万名客户），并添加了企业对企业记录，这些记录包含了你即将调查的谜团。

本部分总结：您运行了设置脚本来引导启动实验环境，并启动了后台数据库预配。

3. 设置 IDE 和 Data Agent Kit

打开 Antigravity IDE

您无需等待 Cloud SQL 完成！接下来，打开 Antigravity IDE 并将其连接到您的 Google Cloud 项目。

1. 如果您尚未下载并安装 Antigravity IDE，请从 Google Antigravity 下载页面下载并安装。
2. 启动 Antigravity IDE 桌面应用。
3. 在本地机器上创建一个新的空文件夹（例如，命名为 agentic-data-labs），然后选择 Open Folder 在 IDE 中打开该文件夹。此目录将作为您在此 Codelab 中的本地工作区。

安装 Data Agent Kit 扩展程序

Google Cloud Data Agent Kit 扩展程序为 BigQuery、Cloud SQL 和 Cloud Storage 添加了数据目录浏览器、代理技能和 MCP 服务器，以便您从编辑器中查询和检查这些服务。

1. 在 Antigravity IDE 中，点击屏幕最左侧活动栏中的扩展程序图标（看起来像四个正方形）。
2. 在“扩展程序”窗格顶部的搜索栏中，输入 Google Cloud Data Agent Kit。
3. 找到名为 Google Cloud Data Agent Kit（由 googlecloudtools 发布）的第一个结果。
4. 点击 Install 按钮。
5. 系统可能会显示提示，询问“您是否信任发布者 ‘googlecloudtools’ 及其扩展程序？”点击信任发布者并安装以继续。

安装完成后，您会在 Antigravity IDE 最左侧的活动栏中看到新的 Google Cloud Data Agent Kit 图标。

进行身份验证并配置扩展程序

安装完成后，将扩展程序连接到您的 Google Cloud 项目。

1. 系统应会自动打开一个名为“欢迎使用 Google Cloud Data Agent Kit”的初始配置页面。如果您未登录 Cloud 账号，请按照提示授予访问权限。
2. 在配置摘要部分中，找到项目字段。点击下拉菜单，然后选择您的 Google Cloud 项目。将您的区域设置为 us-central1。然后选择配置 MCP 服务器。

3. 在 MCP 配置窗格下，点击以启用 BigQuery 和 Cloud SQL。然后点击开始使用。

已安装或欢迎页面未打开？您可以随时手动打开扩展程序设置。点击最左侧活动栏中的 Google Cloud Data Agent Kit 图标，然后选择设置，即可切换配置。

关于有效技能/MCP 的注意事项：如果您在 IDE 中有其他自定义技能或 MCP 服务器处于有效状态，它们可能会干扰本实验的预期流程。如果代理的行为异常，请考虑在本实验中停用它们。

探索配置选项

设置完成后，您会进入“开始使用 Google Cloud Data Agent Kit”页面。

1. 在“设置和配置”下，单击开始使用。
2. 系统随即会打开Data Agent Kit 配置面板。探索各个标签页：
   • 项目和区域：验证所选的项目 ID，并检查是否已启用必需的 API（Cloud Storage API、BigQuery API、Catalog API 和 Cloud SQL Admin API）。
   • BigQuery：配置 BigQuery 查询的默认位置。使用 us-central1 区域。
   • 配置 MCP 服务器：查看已启用的 MCP 服务器（BigQuery、Notebook、Cloud SQL 等），这些服务器可让 AI 智能体安全地与您的数据互动。
   • 技能：探索预构建技能，这些技能可为智能体提供专门的功能，以处理复杂的数据任务。

本部分总结：您打开了 Antigravity IDE，将其连接到您的 Google Cloud 项目，并配置了 Data Agent Kit 远程 MCP 服务器。

4. 发掘数据

现在来设置场景。假设出现以下情况：首席财务官表示，上个月的平均订单价值下降了 7%，但总收入保持不变。在你要求代理人进行调查之前，你应该先了解你正在处理哪些数据。

在本部分中，您将手动探索 Data Agent Kit 面板，以便大致了解其功能。在开始查询数据之前，先了解数据是任何调查中至关重要的第一步。

探索 BigQuery 表

1. 在 Data Agent Kit 面板中，依次展开 CATALOG 下的您的项目 → BigQuery → cymbal_pets。
2. 点击 orders 表。系统会打开一个新标签页，其中显示了该表的详细信息。
3. 探索表格查看器左侧的标签页：
   • 数据：预览实际行。滚动浏览数据集并检查各列。
   • 架构：查看列名称和类型。请注意 order_type 和 promo_code 等字段，这些字段稍后会变得非常重要。
   • 其他标签页（“详细信息”“数据洞见”“数据剖析”等）：无需离开编辑器，即可访问通常在 Google Cloud 控制台中找到的元数据、数据沿袭和质量详细信息。

4. 现在点击order_items表并查看其架构。请注意 quantity 和 price 字段。

尽早发现线索。在浏览数据时，您可能已经注意到一些看似不寻常的内容：B2B-Wholesale 订单类型和 promo_code 字段。暂时不必担心如何将这些点串联起来。智能体将在这方面提供帮助。

探索 Cloud SQL 表

设置脚本还将客户、宠物和产品数据放置在 Cloud SQL 中的 PostgreSQL 数据库中。

5. 在“Data Agent Kit”面板中，点击目录部分下的通用搜索。
6. 在搜索框中，输入 pet_profiles，然后按 Enter 键。
7. 在搜索结果中，点击 pet_profiles 的 PostgreSQL 表结果（位于项目的 Cloud SQL 实例下）。请注意，边栏手风琴会自动展开，向您显示表格在数据库树中的确切位置。现在，点击树状结构中位于其正上方的 customers 表以打开其详细信息，然后探索架构和详细信息标签页。

探索 Cloud Storage 文件

最后，营销和宣传广告系列记录以原始 JSON 文件形式存储在 Cloud Storage 中。

8. 在左侧的 Data Agent Kit 面板中，展开 CLOUD STORAGE 部分。找到项目的原始数据存储分区 (YOUR_PROJECT_ID-cymbal-pets-raw)。
9. 单击存储分区内的 promo_events.json 文件。系统会打开一个新的编辑器标签页，让您可以在 IDE 中直接查看营销活动的原始 JSON 内容。

盘点

以下是您现在对数据了解的信息：

服务	表	有哪些内容
BigQuery	orders、order_items	约 190 万个订单，约 430 万个订单项，日期范围为 2023 年至 2025 年
Cloud SQL	customers、pet_profiles、products	约 9.2 万名客户、约 7,600 个宠物资料、206 款产品
Cloud Storage	promo_events.json	促销活动记录

为什么数据会分散在不同的服务中？这与实际架构类似。Cloud SQL 是 OLTP（事务型）数据库。它针对快速的行级操作进行了优化，例如更新客户的地址或处理单个订单。BigQuery 是一个 OLAP（分析型）仓库。它更适合扫描数百万行数据，以回答“我们本月的平均订单价值是多少？”之类的问题。在大多数组织中，您会发现数据同时存在于这两个位置，因此像 Data Agent Kit 这样的跨服务调查工具非常重要。

数据分布在三项服务中。在传统工作流程中，您需要设置连接、编写集成代码并手动联接结果。在下一步中，您将让 AI 智能体通过一次对话处理所有这些任务。

本部分总结：您使用了 Data Agent Kit 面板手动探索 BigQuery、Cloud SQL 和 Cloud Storage 中的数据架构。现在，您已经知道数据存储在何处以及有哪些可用字段，可以开始调查了。

5. 按数字顺序操作

现在，调查开始了。您将使用“聊天”窗格要求 AI 智能体从 BigQuery 中提取平均订单价值 (AOV) 数据。平均订单价值是一项业务指标，表示每笔订单的平均消费金额。智能体将使用 MCP 工具代表您进行查询，您将能够看到它运行的每个 SQL 查询。

提取平均订单价值趋势

1. 在 IDE 右侧的聊天窗格中，输入以下提示，然后按 Enter 键：

   Calculate our monthly average order value from August 2024 through January 2025
   using the orders and order_items tables in BigQuery.
   

2. 批准数据访问权限。谨慎对待 AI 智能体对数据库运行查询是明智之举。Data Agent Kit 会在访问数据之前暂停，并征求您的明确许可，让您始终掌控主动权。当系统提示时，您可以选择：
   • 仅这次访问时允许：批准单次使用（非常适合审核高风险查询）。
   • 始终允许：批准在会话期间持续使用此特定工具。
   • 否：完全阻止相应操作。

为获得最流畅的实验体验，请选择是，并始终允许。注意：权限是按工具授予的。代理使用新工具（例如 list_table_ids 或 execute_sql_readonly）时，您可能很快会看到更多提示。您也可以随意选择“始终允许”。

3. 观看代理的运作。聊天窗格还可作为透明度日志，记录智能体执行的所有操作。智能体不会像黑盒一样，而是会实时向您展示其推理过程和行动。
4. 智能体完成任务后，点击提示下方的工作了 X 分钟下拉菜单，展开完整的工作日志。您可以在此处详细了解 Gemini 如何得出答案：
   • 已探索：展开这些项可查看智能体读取文件、浏览文件夹或调用 MCP 工具（例如 datacloud_bigquery_remote / list_table_ids 和 execute_sql_readonly）的情况。您可以查看传递给工具的确切 JSON 实参和执行的 SQL。
   • 运行：展开这些项可查看代理执行的任何终端命令，例如 gcloud config list。

5. 查看结果。代理应返回包含每月 AOV 值的表格。您可以自己查看这些数字：前几个月的平均费用约为 110 美元，而 1 月份的平均费用降至约 103 美元。这就是 CFO 标记的异常情况。

什么是 MCP 工具和智能体技能？MCP 工具是安全连接，可让代理与 BigQuery 和 Cloud SQL 等外部服务进行交互。智能体技能是预构建的指令集（如 discovering-gcp-data-assets），用于教导智能体如何处理特定任务。它们共同构成了一个可审核性层。点击任意步骤，即可查看智能体执行的具体操作以及原因。

按渠道展开细目

总体 AOV 下降了，但下降的原因是什么？让我们来一探究竟。

1. 在“聊天”窗格中，输入：

   January looks lower than the prior months. 
   Break down January's AOV by order_type to see what's going on?
   

2. 代理运行另一个 BigQuery 查询，这次按 order_type 分组。仔细查看结果。您会发现一个显著的现象：线上和线下的平均订单价值 (AOV) 保持在 110 美元左右。不过，有一个新渠道 B2B-Wholesale 的平均订单价值要低得多（约为 75 美元）。这个新渠道拉低了混合平均值。
3. 该代理可能会主动建议调查 B2B 客户。如果没有，也没关系。您将在下一步中执行此操作。

代理会梳理思路。请注意，代理会解读结果，并可能会主动提供数据洞见，例如“B2B-Wholesale 渠道似乎是一种新的订单类型，之前几个月没有出现过。”这种主动分析是代理的一项关键功能。

本部分总结：您从中性数据提取中自行发现了 1 月份的 AOV 下降，然后按 order_type 深入分析，确定 B2B-Wholesale 是拉低混合平均值的新渠道。现在，您需要了解这些 B2B 客户是谁。

6. 跨越服务边界

您已在 BigQuery 中将 B2B-Wholesale 确定为异常渠道，但客户数据位于 Cloud SQL 中。借助 Data Agent Kit，您可以继续进行同一对话，而它会处理服务边界。

调查 B2B 客户

1. 在聊天窗格中，输入：

   Who are these B2B customers? Their profiles should be in our Cloud SQL database. 
   Check for:
   - Who they are
   - When they signed up
   - Whether they're new or existing customers
   

2. 仔细查看“聊天”窗格。这次，您应该会看到不同的 MCP 工具。现在，代理会查询 Cloud SQL 而不是 BigQuery。代理连接到 cymbal-pets-ops Cloud SQL Postgres 实例，并针对 customers 表运行查询。点击 显示详情 查看 SQL。
3. 查看结果。智能体应显示以下几项关键发现：
   • 所有 B2B 客户均可享受customer_type = 'Business'
   • 他们都是在过去 30 天内（2025 年 1 月）注册的
   • 其 last_name 值是商家名称，例如“Pet Supply Co”“Animal Care LLC”和“Happy Paws Inc”
   • 这类用户大约有 100 人，是本月之前从未出现过的群体

跨服务边界。在同一对话中，代理跨两个不同的 Google Cloud 服务（BigQuery 和 Cloud SQL）进行了查询。请注意，“聊天”窗格中显示了不同的 MCP 工具名称。无需建立连接，无需配置凭据。智能体自动处理了该问题。

关联促销代码

4. 代理可能会自行注意到，BigQuery 中的许多 B2B 订单的 promo_code 值为 BIGORDER25。如果它主动提供此观察结果，那就太好了。调查正在顺利进行。如果客服人员未提及促销代码，请提醒对方：

   I noticed a promo_code field on the orders table in BigQuery. 
   Check what promo codes appear on the B2B-Wholesale orders?
   

5. 代理会再次查询 BigQuery，发现大约 92% 的 B2B-Wholesale 订单具有 promo_code = 'BIGORDER25'。几乎所有 B2B 活动都与单个促销活动相关联。接下来，代理可能会在环境中的其他位置寻找促销数据。（它位于 Cloud Storage 中。）

本部分总结：代理查询了 Cloud SQL，结果显示 B2B 客户都是在 2025 年 1 月注册的新企业。结合 BigQuery 的发现（约 92% 的订单包含 promo_code = 'BIGORDER25'），现在可以确定是促销活动。是时候寻找来源了。

7. 找到缺失的部分

两项服务已完成，还剩一项。你知道的。什么这种情况已经发生（B2B 订单拉低了平均订单价值），而且WHO正在这样做（过去 30 天内新增的企业客户）。现在，您需要找到原因，答案就在 Cloud Storage 中。

检查 GCS 存储分区

1. 在聊天窗格中，输入：

   Good catch on the promo code. 
   We might have promotional campaign data in our GCS bucket. 
   Can you check what's there?
   

2. 该代理没有预配置的 Cloud Storage MCP 工具，因此会自动转为使用其终端工具运行 gcloud storage 命令。它会请求运行 gcloud storage ls 等命令的权限。允许这些命令，然后展开聊天窗格中的 Ran 日志，查看用于读取和解析 promo_events.json 文件的确切 CLI 命令。
3. 代理应在文件中识别出三个宣传广告系列：

   广告系列	促销代码	折扣	目标	日期
   夏季宠物护理用品促销活动	PETSUMMER15	八五折	全部	2024 年 6 月
   B2B Wholesale Push	BIGORDER25	七五折	B2B	2025 年 1 月
   会员节假日奖励	LOYAL10	9 折	忠诚会员	2024 年 12 月

   这就是原因。BIGORDER25 促销代码对应于名为 B2B Wholesale Push 的广告系列：面向 B2B 客户提供 25% 的折扣，最低订购数量为 50 件。

三项服务，一次对话。在最后三个部分中，该代理已查询 BigQuery（销售和订单历史记录）、Cloud SQL（客户和产品数据）和 Cloud Storage（促销记录），所有这些操作都是在同一聊天串中完成的，无需您进行任何配置或上下文切换。这正是 Data Agent Kit 的核心价值：一个可在整个数据资产中运行的 AI 智能体。

总结

4. 让智能体总结找到的所有内容：

   Put it all together. 
   What happened to our average order value?
   

5. 该智能体提供清晰、结构化的整合结果，将所有三个数据源关联起来。它应说明以下内容：
   1. 平均订单价值下降是真实存在的，但并非现有业务的衰退。线上和线下 AOV 均稳定在 110 美元左右。
   2. 2025 年 1 月，出现了一个新的 B2B 批发渠道，订单量约为 25,000，但平均订单价值 (AOV) 要低得多（约 75-100 美元）。
   3. B2B 客户是 100 个新企业账号，这些账号都是在过去 30 天内注册的 (Cloud SQL)。
   4. 活动由一项促销活动（“B2B 批发推广”）推动，该活动提供 25% 的批量订单折扣，最低订购量为 50 件（Cloud Storage）。
   5. 收入保持不变，因为 B2B 订单量大抵消了价格下降的影响。不过，在 25% 的批发折扣下，单位利润率大幅压缩（降幅约为 65%），如果将运费和运营开销考虑在内，整体盈利能力将受到严重威胁。
   这是调查取得突破性进展的时刻。CFO 的问题有明确的答案：AOV 下降是因为一项以营销为导向的 B2B 计划在 1 月份带来了大量低价订单。现有业务运行状况良好。

本部分总结：您在 Cloud Storage 中找到了原因：一项 B2B 促销活动，提供批量订单 75 折优惠。该代理将所有三项服务的发现结果综合成清晰的叙述。调查阶段已完成。接下来，您将根据这些发现采取行动。

8. 构建流水线

您已破解此支持请求。现在，CFO 希望此分析能够自动更新。在此部分中，您将要求代理构建一个 dbt 项目，该项目会对 BigQuery 数据进行暂存，并生成一个事实表以用于持续的 AOV 分析。

此时，智能体从调查员转变为工程师。您会看到它从单个提示开始，搭建整个 dbt 项目并运行整个流水线。

什么是 dbt？dbt（数据构建工具）是一个框架，可让数据从业者使用 SQL 在数据仓库中转换数据。它将 SQL 视为代码，并添加了版本控制、自动化测试和依赖项管理功能。

搭建 dbt 项目

1. 在聊天窗格中，输入以下提示。此部分有意以目标为导向，而非按步骤进行。你在告诉经纪人什么你想要的，不是如何建造它：

   I want to productionize our AOV analysis so it updates automatically. Build a dbt project that:
   1. Creates staging models for the BigQuery tables (orders and order_items) and a mart called fct_order_analysis that calculates AOV by channel and month
   2. Add a uniqueness test on order_id and run dbt build
   

2. 观察自我修正：如果您展开 “Worked for Ns”日志，可能会看到代理检查 dbt，并在发现它缺失时自动运行命令来创建 Python 虚拟环境 (.venv)。它正在为您处理环境设置！

3. 查看实施计划：代理将生成正式的实施计划。您可以查看其建议的文件和架构，根据需要添加注释，然后点击继续，让代理执行该计划。

4. 观看聊天窗格，了解智能体如何执行其计划，编写必要的 .sql 文件和 YAML 配置。当它完成并成功编译项目后，将显示更改摘要。点击全部接受，将这些文件添加到工作区。

5. 在左侧的探索器中探索新生成的 dbt 项目。您应该会看到类似如下所示的结构：

   dbt/
   ├── models/
   │   ├── marts/
   │   │   └── fct_order_analysis.sql
   │   └── staging/
   │       ├── schema.yml
   │       ├── sources.yml
   │       ├── stg_order_items.sql
   │       └── stg_orders.sql
   ├── dbt_project.yml
   └── profiles.yml
   

6. 点击 .sql 模型文件，查看代理生成的 SQL。请注意它如何处理以下情况：
   • 临时模型：包含源引用的已清理和重命名的列
   • 数据超市模型：按渠道划分的联接逻辑和 AOV 计算
   • 处理访客结账: 您可能会注意到COALESCE(customer_type, 'Guest')或放宽空约束。此模型可处理未登录账号的零售客户购买交易，并保留有效的订单收入，而不是舍弃不完整的记录。

查看 Mart 代码：打开 models/marts/fct_order_analysis.sql。请注意，它会先汇总各个订单项，以使事实表保持在订单粒度。提示：请仅修改 models/ 目录中的源文件，而不要修改 /target/ 中的自动生成的文件！

7. 查看“聊天”窗格（或点击生成的 Walkthrough 制品），了解代理是否确认所有模型已实现且所有测试均已通过。来自 Mart 的 AOV 结果应确认您在调查期间发现的情况：

   - Online: ~$110
   - Offline: ~$110
   - B2B-Wholesale: ~$75 to $77
   

本部分总结：该代理根据一个以目标为导向的提示构建了一个 dbt 项目：搭建了临时表模型和数据集市模型，成功运行了 dbt build，并确认了 AOV 异常。接下来，您将提出一个难题，看看智能体如何应对复杂情况。

9. 当测试失败时，代理会调试

流水线可以正常运行，但仅使用 BigQuery 数据。产品团队希望通过 Cloud SQL 中的客户和宠物个人资料数据来丰富分析，以便根据饮食需求推荐产品。这意味着代理需要跨越 Cloud SQL 边界并处理一个细微的数据建模 bug，即经典的维度建模“扇出”联接。

什么是“扇出”？如果某个订单属于一位养了 3 只宠物的客户，标准 SQL JOIN 将为该单个订单创建 3 个相同的行（每只宠物对应一行）。这会“分散”数据，并破坏“平均订单价值”等指标，因为它会重复计算同一订单的收入 3 次！如需解决此问题，您必须在加入之前将宠物聚合到列表（数组）中。

根据您使用的模型及其推理能力，代理将通过以下两种方式之一来处理此请求：主动避免 bug（选项 A）或在测试失败后进行自我修复（选项 B）。让我们看看智能体选择了哪条路径！

触发请求

1. 在聊天窗格中，输入：

   Enrich fct_order_analysis with customer data and pet profile data from our Cloud SQL database. 
   Include customer type and each customer's pets and dietary needs so we can recommend products. 
   Keep the uniqueness test on order_id and run dbt build.
   

2. 观看代理的运作。它将发现 Cloud SQL 表，确定如何将数据桥接到 BigQuery（通过联合查询或具体化副本），创建新的临时模型，并修改 fct_order_analysis.sql。

架构说明：MCP 与联合查询
在本 Codelab 的前面部分，代理使用 Cloud SQL MCP 工具直接查询 Cloud SQL，以进行临时交互式调查。现在，在 dbt 流水线中，dbt-bigquery 会在 BigQuery 中运行转换。为了从 BigQuery 查询 Cloud SQL 数据，代理会通过 cymbal-pets-cloudsql BigQuery 连接资源使用 BigQuery 联合查询 (EXTERNAL_QUERY(...))。

方案 A：主动式代理（避免 bug）

如果您使用的是高级推理模型，智能体可能会在编写任何代码之前检测到粒度变化。由于客户可以拥有多只宠物，因此直接联接会导致订单重复，并导致您在 order_id 上请求的唯一性测试失败。

1. 观察主动聚合：在聊天窗格说明或演练制品中，代理可能会指出它在联接宠物数据之前对其进行了预聚合，以防止出现“经典扇出”。它通常会使用聚合函数（例如 ARRAY_AGG() 或 STRING_AGG()）来合并每位客户的多只宠物。
2. 检查结果：由于代理主动保护了事实表的粒度，因此 dbt build 首次运行即成功通过。您可以通过检查生成的 Walkthrough 制品来验证这一点，该制品通常会显示成功的测试输出以及查询结果。

智能体避开了该 bug。查看 fct_order_analysis.sql 中生成的 SQL，了解其汇总结构，然后跳到下一部分提供答案。

选项 B：自我修复代理（调试和诊断）

如果模型先写入一个简单的直接左连接，SQL 查询本身会成功运行，但自动化 dbt test 套件会捕获粒度变化！

1. 观察测试失败情况：您会在聊天窗格的执行进度日志中看到报告的失败情况：

   Completed with 1 error
   
   Failure in test unique_fct_order_analysis_order_id
   Got 287 results, configured to fail if != 0
   

   对 order_id 进行唯一性测试时，发现存在重复条目，原因是拥有多只宠物的客户分散了订单。
2. 让代理诊断并自行修复：由于测试失败，请让代理进行调试。在聊天窗格中，输入：

   The uniqueness test failed. Can you figure out why and fix it?
   

3. 观看诊断过程：智能体将查询数据，发现 pet_profiles 中的一对多关系，说明直接联接会将粒度从每个订单一行更改为每个订单中每只宠物一行，并重写模型以预先汇总宠物资料：

   -- Pre-aggregating pets per customer to resolve fan-out
   LEFT JOIN (
     SELECT
       customer_id,
       COUNT(*) AS num_pets,
       STRING_AGG(DISTINCT pet_type, ', ') AS pet_types,
       STRING_AGG(DISTINCT dietary_needs, ', ') AS dietary_needs
     FROM pet_profiles
     GROUP BY customer_id
   ) pet_agg ON c.customer_id = pet_agg.customer_id
   

4. 验证修复：代理再次运行 dbt build，这次所有模型都已实现，并且所有测试都已成功通过！

本部分总结：无论您的代理是主动避免了 bug，还是在测试失败后成功实现了自我修复，您都已看到它跨越了 Cloud SQL 边界，集成了客户和宠物个人资料数据，并在事实表中为每个订单保留了一行数据。流水线已完成并经过测试！

10. 提供答案

今天是星期四。您本周初面临的局面是：一位忧心忡忡的 CFO，以及分散在三个云服务中的数据。现在，您已经找到了根本原因并创建了生产流水线。是时候提供答案了，同时还要提供有量化预测支持的前瞻性建议。

撰写摘要

1. 在聊天窗格中，输入：

   Write an executive summary covering:
   - Main findings and the quantitative margin impact
   - Project AOV for the subsequent quarter if the B2B program continues at its current trajectory
   - A data-driven recommendation
   

2. 观看代理的工作过程。

   关于输出格式和变体的注意事项：大语言模型具有不确定性。根据所用的模型，智能体可以直接在“聊天”窗格中输出执行摘要，也可以创建专用的 Markdown 文件（例如 executive_summary_cfo.md 或 output.txt）并在聊天中链接该文件。

   每次运行时，确切的数字、计算的总数（例如潜在的利润损失或平均 AOV 降幅）和格式布局都会有所不同。重要的是研究发现的核心结构逻辑。

3. 查看智能体的摘要。典型且结构良好的回答应包含以下内容：
   • 核心发现：1 月份的平均订单价值下降完全是因为新增了 B2B-Wholesale 渠道。线上和线下渠道的平均价格仍稳定在 110 美元左右。
   • 根本原因：“B2B 批发推送”（批量订单可享 75 折优惠）吸引了 100 个新账号，带来了约 25,000 笔订单。
   • 利润影响：批发订单使平均单件利润下降了约 65%（从约 7.50 美元降至约 2.60 美元）。
   • 收入：总体收入保持不变，因为 B2B 交易量高抵消了价格下降的影响。

使用 AI.FORECAST 预测 AOV

4. 代理还应生成前瞻性预测。查找代理针对 BigQuery 运行 AI.FORECAST 查询的 MCP 工具调用。此查询使用内置的 TimesFM 基础模型，根据历史趋势将 AOV 向前预测 90 天。该查询应在两种情况下将 AOV 向前预测 90 天：广告系列继续投放（AOV 在结构上受到抑制）与广告系列终止投放（AOV 恢复到约 110 美元）。

提示（如果客服人员不使用 AI.FORECAST）：如果客服人员提供的是定性预测，而不是定量预测，请尝试：

Use BigQuery's AI.FORECAST function to generate a 90-day forecast with confidence intervals.

5. 查看代理的战略建议。建议应涵盖以下方面：
   • 重组折扣：实施利润下限或限制批量折扣，以保护单位级利润。
   • 强制执行更严格的 MOQ：防止零售买家滥用批发价格。
   • 单独报告：单独跟踪零售部门和 B2B 部门，避免掩盖零售业绩。

完整故事

周一，平均订单价值下降 7% 触发了演练，现在财务总监已经找到了明确的解决方案：

• 零售健康：核心零售渠道在基准水平上保持健康稳定。
• 批发渠道的涌入：平均订单价值下降完全是由于新的 B2B 批发渠道和 BIGORDER25 广告系列。
• 利润率影响：25% 的批量折扣严重侵蚀了单位利润率，尽管收入保持不变，但盈利能力却受到威胁。
• 战略性预测：AI.FORECAST 预测表明，重组批发层级将恢复混合 AOV。

您提供数据支持的建议，以确定批发利润下限并分离零售/B2B 报告。

本部分回顾：您要求智能体撰写包含边际分析的执行摘要，生成 AI.FORECAST 预测，并提供数据驱动的建议。调查已完成。

11. 清理

为避免系统向您的 Google Cloud 账号持续收取费用，请运行拆解脚本来删除此 Codelab 中创建的资源。

请勿忘记此步骤！即使 Cloud SQL 实例处于空闲状态，也会产生费用。如果您跳过清理步骤，可以稍后随时运行清理脚本，也可以删除用于此 Codelab 的整个 Google Cloud 项目。

1. 返回 Google Cloud Shell（您在其中运行了设置脚本），然后运行拆解脚本：

cd ~/devrel-demos/codelabs/agentic-data-labs/scripts
chmod +x teardown.sh
./teardown.sh

2. 脚本将显示计划删除的所有资源，并在继续操作之前要求确认：
   • Cloud SQL 实例 (cymbal-pets-ops)：所有表
   • BigQuery 数据集（cymbal_pets、dbt_marts）：所有表和模型
   • Cloud Storage 存储分区 (gs://YOUR_PROJECT_ID-cymbal-pets-raw)
   • BigQuery 连接 (cymbal-pets-cloudsql)
3. 请输入 y 进行确认。拆解大约需要 2-3 分钟。

[INFO]  Deleting BigQuery dataset cymbal_pets...
[ OK ]  BigQuery dataset cymbal_pets deleted.
[INFO]  Deleting BigQuery dataset dbt_marts...
[ OK ]  BigQuery dataset dbt_marts deleted.
[INFO]  Deleting GCS bucket gs://YOUR_PROJECT_ID-cymbal-pets-raw...
[ OK ]  GCS bucket deleted.
[INFO]  Deleting BigQuery connection cymbal-pets-cloudsql...
[ OK ]  BQ connection deleted.
[INFO]  Deleting Cloud SQL instance cymbal-pets-ops...
[ OK ]  Cloud SQL instance deleted.

12. 恭喜！

您已成功完成 Cymbal Pets 调查！您使用可在整个 Google Cloud 数据资产中运行的 AI 智能体，将模糊不清的 CFO 问题转化为完全可操作的、有预测支持的建议。

您完成的任务

1. 🔍 跨服务探索：使用 Data Agent Kit 的 Knowledge Catalog 发现并预览 BigQuery、Cloud SQL 和 Cloud Storage 中的资产。
2. 🕵️‍♂️ 借助 AI 进行调查：使用 MCP 工具在单个聊天窗格对话中查询多项服务，以将 AOV 异常情况追溯到批量 B2B 促销活动。
3. 🔧 构建了生产流水线：搭建了一个完整的 dbt 项目，用于清理、联接和测试订单数据及客户数据。
4. 🐛 调试了扇出 bug：观察到代理自动诊断了粒度问题，并重构了 dbt SQL 模型以预先汇总客户宠物资料。
5. 📈 预测和推荐: 使用 BigQuery 内置的 AI.FORECAST 对 AOV 趋势进行建模，并向 CFO 提供数据驱动的建议。

主要概念

概念	要点回顾
MCP 工具	安全且可审核的连接，可让 AI 智能体代表您查询 BigQuery、Cloud SQL、Spanner 等服务以及其他数据库，并且每次调用都会显示在“聊天”窗格中
Agent Skills	预构建的指令集（例如 dbt-bigquery 或 discovering-gcp-data-assets），可让代理学习特定领域的最佳实践，而无需您提示
跨服务调查	该代理可在单个对话中查询多个 Google Cloud 服务，无需设置连接，也无需在控制台之间切换上下文
以目标为导向的提示	告诉代理您想要什么（“构建一个按渠道计算 AOV 的 dbt 项目”），而不是如何实现，让代理选择实现方法
Data Agent Kit	该扩展程序可将 MCP 工具和代理技能与数据发现功能绑定在一起，让您能够从所选 IDE 中访问整个 Google Cloud 数据资产

后续步骤

• 如需详细了解其功能，请参阅数据代理工具包文档
• 了解 BigQuery ML 和 AI 函数，包括 AI.FORECAST、AI.GENERATE 和 AI.EMBED
• 尝试使用 Antigravity IDE 基于您自己的数据构建跨服务调查