使用 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 使用入门 Codelab，获取全面的入门知识。

您将执行的操作

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

所需条件

• 网络浏览器，例如 Chrome
• 启用了结算功能的 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 配置是瓶颈。

启动 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/

运行设置脚本

设置脚本可在几分钟内准备好整个实验环境。它会处理以下任务：启用 API、加载和扩充 BigQuery 数据、将宣传素材资源上传到 GCS，然后在您开始实验时自动生成一个后台工作器，以便在后台预配和配置 Cloud SQL Postgres。

该脚本会安全地自动生成 Cloud SQL 密码，并自动将其保存到您的 .env 文件中。

cd ~/devrel-demos/codelabs/agentic-data-labs/scripts
chmod +x setup.sh setup_sql.sh
./setup.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 电子商务数据集（约 92,000 名客户的 190 万笔订单），其中还添加了嵌入了您即将调查的神秘事件的企业对企业记录。

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

3. 设置 IDE 和数据代理套件

打开 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 扩展程序可直接在编辑器中与 Google Cloud 数据服务深度集成，让您无需切换上下文即可与 BigQuery、Cloud SQL、Cloud Storage 等服务进行交互。

1. 在 Antigravity IDE 中，点击屏幕最左侧活动栏中的扩展程序图标（看起来像四个正方形）。
2. 在“扩展程序”窗格顶部的搜索栏中，输入 Google Cloud Data Agent Kit。
3. 找到由 googlecloudtools 发布的名为 Google Cloud Data Agent Kit 的扩展程序
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. 系统随即会打开数据代理配置面板。探索各个标签页：
   • 项目和区域：验证所选的项目 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 服务器，并通过针对 BigQuery 运行查询来验证连接。

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 Lines 内容。

盘点库存

现在，您已了解数据格局的以下方面：

服务	表格	What's There
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. Follow the Numbers

现在，调查开始了。您将使用“聊天”窗格要求 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），用于教导代理如何处理特定任务。它们共同构成了一个可审核性层。点击任意步骤，即可查看智能体执行的具体操作以及原因。

按渠道展开细目

平均订单价值总体有所下降，但下降来自何处？让我们来一探究竟。

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

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

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

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

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

6. 跨服务边界

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

调查 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 订单拉低了平均订单价值），也知道是谁在这样做（过去 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 批发推广”）推动，该广告系列提供批量订单 75 折优惠，最低订购量为 50 件（Cloud Storage）。
   5. 收入保持不变，因为 B2B 订单量大抵消了价格下降的影响。不过，在 25% 的批发折扣下，单位利润率大幅压缩（降幅约为 65%），如果将运费和运营开销考虑在内，整体盈利能力将受到严重威胁。
   这是调查取得突破性进展的时刻。CFO 的问题有明确的答案：AOV 下降是因为一项以营销为主导的 B2B 计划在 1 月份带来了大量低价订单。现有业务健康状况良好。

本部分总结：您在 Cloud Storage 中找到了确凿证据：一项 B2B 促销活动，提供批量订单 25% 的折扣。该代理将所有三项服务的发现结果整合为清晰的叙述。调查阶段已完成。接下来，您将根据这些发现结果制定行动方案。

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 计算

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

7. 在“聊天”窗格中查看代理是否确认所有模型已具体化且所有测试均已通过。来自 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。

选项 A：主动式代理（避免 bug）

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

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

如果您的代理做到了这一点，那么恭喜您！您已经见证了主动式 AI 工程。花点时间查看 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 月份的平均订单价值 (AOV) 下降完全是因为新增了 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 中创建的资源。

1. 在 Antigravity IDE 底部的终端面板（或 Cloud Shell）中，前往 Codelab 目录并运行以下命令：

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

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

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

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

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 基于您自己的数据构建跨服务调查