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

1. 簡介

週一早上，財務長傳訊息給您，本月平均訂單價值下降 7%，但總收益持平。有些地方不對勁，董事會要求在週五前找出答案。

貴公司 Cymbal Pets 是美國最大的線上寵物用品零售商之一。您需要的資料分散在三項 Google Cloud 服務中：BigQuery 中的交易資料、Cloud SQL 中的客戶和產品記錄，以及 Cloud Storage 中的行銷檔案。通常，要像這樣整合跨服務調查，就必須在控制台之間切換、編寫連線樣板，以及手動合併結果。

在本程式碼實驗室中，您將在 Antigravity IDE 中使用 Google Cloud Data Agent Kit (DAK)，以自然語言調查異常狀況。您只要說明要尋找的內容，AI 代理程式就會處理 BigQuery、Cloud SQL 和 Cloud Storage 之間的連線、SQL 和跨服務聯結。破案後，您會要求代理程式建構 dbt 管道，將發現的結果付諸實行、偵錯實際的資料模型錯誤，並向財務長提供有預測結果佐證的建議。

第一次使用 Antigravity 嗎？如果您是第一次使用 IDE，請查看這個程式碼實驗室，瞭解 Google Antigravity 的入門知識。

學習內容

• 使用 Knowledge Catalog 探索 BigQuery、Cloud SQL 和 Cloud Storage 中的資料資產
• 使用 MCP 工具，在單一對話中查詢多項服務，調查異常狀況
• 建構 dbt 管道，使用暫存模型和自動化測試，暫存及聯結跨服務資料
• 偵錯資料建模問題，因為代理程式會自行診斷並重構擴散傳遞功能錯誤
• 使用 BigQuery 的 AI.FORECAST預測未來趨勢，並提供以資料為依據的建議

軟硬體需求

• 網路瀏覽器，例如 Chrome
• 已啟用計費功能的 Google Cloud 雲端專案
• 對 SQL 和 Google Cloud 控制台有基本瞭解

本程式碼研究室適用於中階資料從業人員 (分析工程師、資料分析師、資料科學家)。

本程式碼研究室建立的資源費用應低於 $5 美元。

選擇工具：本實驗室使用 Antigravity IDE。我們很快就會發布替代版本，專為 Antigravity 2.0、Antigravity CLI 和 Claude Code 量身打造！

2. 事前準備

在本節中，您將執行設定指令碼，佈建整個實驗室環境：包含訂單資料的 BigQuery 資料集、包含客戶和產品資料的 Cloud SQL Postgres 執行個體，以及包含宣傳活動記錄的 Cloud Storage bucket。指令碼大約需要 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]

複製存放區

將程式碼研究室存放區複製到 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 和 Data Agent Kit

開啟 Antigravity IDE

您不必等待 Cloud SQL 完成作業！請開啟 Antigravity IDE，並連結至 Google 雲端專案。

1. 如果尚未下載並安裝 Antigravity IDE，請前往 Google Antigravity 下載頁面。
2. 啟動 Antigravity IDE 電腦版應用程式。
3. 在本機上建立新的空白資料夾 (例如命名為 agentic-data-labs)，然後選擇「Open Folder」(開啟資料夾)，在 IDE 中開啟該資料夾。這會做為本程式碼研究室的本機工作區。

安裝 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. 系統應會自動開啟名為「Welcome to Google Cloud Data Agent Kit」(歡迎使用 Google Cloud Data Agent Kit) 的入門頁面。如果未登入 Cloud 帳戶，請按照提示允許存取。
2. 在「設定摘要」部分，找到專案欄位。按一下下拉式選單，然後選取 Google Cloud 專案。將區域設為 us-central1。然後選取「設定 MCP 伺服器」。

3. 在「MCP Configuration」窗格下方，按一下以啟用「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、Notebooks、Cloud SQL 等)，讓 AI 代理安全地與您的資料互動。
   • 技能：探索預先建構的技能，為代理提供專門功能，處理複雜的資料工作。

本節重點：您已開啟 Antigravity IDE、連結至 Google Cloud 專案、設定 Data Agent Kit 遠端 MCP 伺服器，並對 BigQuery 執行查詢，確認連線正常運作。

4. 探索您的資料

現在來設定場景。假設情況如下：財務長表示上個月的平均訂單價值下降了 7%，但總收益持平。要求專員調查前，請先瞭解您使用的資料。

在本節中，您將手動探索 Data Agent Kit 面板，瞭解相關功能。在開始查詢資料前先瞭解資料，是任何調查的重要第一步。

探索 BigQuery 資料表

1. 在 Data Agent Kit 面板中，展開「目錄」下方的專案 →「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」面板中，按一下「CATALOG」(目錄) 部分下方的「Universal Search」(通用搜尋)。
6. 在搜尋框中輸入 pet_profiles，然後按下 Enter 鍵。
7. 在搜尋結果中，按一下 pet_profiles 的 PostgreSQL 資料表結果 (位於專案的 Cloud SQL 執行個體下方)。請注意，側欄手風琴會自動展開，顯示表格在資料庫樹狀結構中的確切位置。現在，點選樹狀結構中位於其正上方的 customers 資料表，開啟詳細資料，並瀏覽「結構定義」和「詳細資料」分頁。

探索 Cloud Storage 檔案

最後，行銷和宣傳活動記錄會以原始 JSON 檔案的形式儲存在 Cloud Storage 中。

8. 在左側的 Data Agent Kit 面板中，展開「CLOUD STORAGE」部分。找出專案的原始 bucket (YOUR_PROJECT_ID-cymbal-pets-raw)。
9. 按一下值區中的 promo_events.json 檔案。系統會開啟新的編輯器分頁，讓您直接在 IDE 中查看行銷活動的原始 JSON Lines 內容。

盤點

現在您已瞭解資料環境：

服務	表格	內容
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. 代理程式完成作業後，按一下提示下方的「Worked for Xm」(為 Xm 執行作業) 下拉式選單，即可展開完整的工作記錄。您可以在這裡檢查系統如何得出答案：
   • 探索：展開這些項目，即可查看代理程式讀取檔案、瀏覽資料夾或呼叫 MCP 工具 (例如 datacloud_bigquery_remote / list_table_ids 和 execute_sql_readonly)。您可以查看傳遞至工具的確切 JSON 引數，以及執行的 SQL。
   • 已執行：展開這些項目，即可查看代理程式執行的任何終端機指令，例如 gcloud config list。

5. 查看結果。代理程式應傳回每月平均訂單價值表。請自行查看數據：前幾個月的費用約為$110 美元，1 月則降至$103 美元左右。這就是財務長標記的異常狀況。

什麼是 MCP 工具和代理程式技能？MCP 工具是安全連線，可讓代理與 BigQuery 和 Cloud SQL 等外部服務互動。代理技能是預先建構的指令集 (例如 discovering-gcp-data-assets)，可教導代理如何處理特定工作。共同形成可稽核層。按一下任一步驟，即可查看代理執行的操作和原因。

依管道細查

整體 AOV 下降，但下降的原因是什麼？讓我們一起來看看。

5. 在「Chat」窗格中輸入：

   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 批發管道似乎是新的訂單類型，先前幾個月並未出現」等洞察資訊。這種主動分析是 DAK 代理的重要功能。

章節重點：您從中性資料擷取中發現 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，發現 B2B 批發訂單中約有 92% 含有 promo_code = 'BIGORDER25'。幾乎所有 B2B 活動都與單一宣傳活動相關聯。現在，服務專員應該會想知道這個優惠碼的來源。系統可能會詢問環境中是否有其他促銷資料。(Cloud Storage 中有)。

本節重點：代理程式查詢 Cloud SQL 後發現，所有 B2B 客戶都是在 2025 年 1 月註冊的新商家。加上 BigQuery 發現約 92% 的訂單都含有 promo_code = 'BIGORDER25'，現在線索指向促銷活動。現在要找出來源。

7. Find the Missing Piece

兩項服務的業績下滑，還有一項服務即將跟進。您知道發生了什麼事 (B2B 訂單拉低了平均訂單價值)，也知道是誰造成這種情況 (過去 30 天內的新商家客戶)。現在您需要找出「原因」，答案就在 Cloud Storage 中。

檢查 GCS bucket

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 等指令。允許這些指令，然後展開「Chat」窗格中的「Ran」記錄，查看用於讀取及剖析 promo_events.json 檔案的確切 CLI 指令。
3. 代理商應在檔案中找出三項宣傳活動：

   廣告活動	促銷代碼	折扣	目標	日期
   夏季寵物照護用品特賣	PETSUMMER15	八五折優惠	全部	2024 年 6 月
   B2B 批發推播	BIGORDER25	25% off	B2B	2025 年 1 月
   會員假期獎勵	LOYAL10	10% 折扣	會員	2024 年 12 月

   這就是了。BIGORDER25 優惠碼對應至名為「B2B Wholesale Push」的廣告活動：B2B 客戶只要訂購數量達 50 單位，即可享有 75 折優惠。這就是鐵證。

三種服務，一場對話。在過去三節中，代理程式已從同一個對話串查詢 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 筆，平均訂單價值則低得多 (約 $75 美元至 $100 美元)。
   3. B2B 客戶是 100 個新企業帳戶，全都在過去 30 天內註冊 (Cloud SQL)。
   4. 活動是由宣傳活動帶動 (「B2B Wholesale Push」)，提供大量訂單 75 折優惠，最低訂購量為 50 個單位 (Cloud Storage)。
   5. 由於 B2B 訂單量高，抵銷了較低的價格，因此收益持平。然而，在 25% 的批發折扣下，單位利潤大幅壓縮 (約減少 65%)，若將運費和營運費用納入考量，整體獲利能力將受到嚴重威脅。
   這是調查點擊的時間點。財務長的問題有明確答案：行銷主導的 B2B 計畫在 1 月湧入大量低價訂單，導致平均訂單價值下降。現有業務的健康狀態良好。

章節重點：您在 Cloud Storage 中發現了關鍵證據：一項 B2B 促銷活動，提供大量訂單 75 折優惠。代理商將這三項服務的調查結果彙整成清楚的敘述，調查階段已完成。接著，您將根據這些發現採取行動。

8. 建構管道

你已偵破案件。現在財務長希望這項分析能自動更新。在本節中，您會要求代理程式建構 dbt 專案，該專案會暫存 BigQuery 資料，並產生事實資料表，以持續分析平均訂單價值。

此時，代理程式會從「調查員」轉為「工程師」，您會看到系統從單一提示開始，架構整個 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. 在「Chat」窗格中，觀察代理程式執行計畫的過程，並編寫必要的 .sql 檔案和 YAML 設定。完成並成功編譯專案後，系統會顯示變更摘要。按一下「全部接受」，將這些檔案新增至工作區。

5. 在左側的「Explorer」中，探索新產生的 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。請注意以下處理方式：
   • 暫存模型：已清除並重新命名的資料欄，附有來源參照
   • Mart 模型：依管道的聯結邏輯和平均訂單價值計算

查看 Mart 程式碼：開啟 models/marts/fct_order_analysis.sql。請注意，系統會先彙整委刊項，將事實資料表維持在訂單細節層級。提示：請只編輯 models/ 目錄中的來源檔案，不要編輯 /target/ 中自動產生的檔案！

7. 查看「即時通訊」窗格，確認專員已確認所有模型都已實現，且所有測試都已通過。市集中的平均訂單價值結果應會證實您在調查期間發現的內容：

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

章節重點：代理程式從單一目標導向提示詞建構 dbt 專案：搭建暫存和集市模型、成功執行 dbt build，並確認 AOV 異常狀況。接著，您會提出較複雜的問題，看看代理如何處理。

9. 測試失敗時，代理程式會進行偵錯

管道可以運作，但只會使用 BigQuery 資料。產品團隊想使用 Cloud SQL 中的顧客和寵物設定檔資料，進一步分析資料，以便根據飲食需求推薦產品。也就是說，代理程式需要跨越 Cloud SQL 邊界並處理細微的資料模型錯誤，也就是典型的維度模型「擴散傳遞功能」聯結。

什麼是「擴散傳遞功能」？如果某位顧客有 3 隻寵物，且下了一筆訂單，標準 SQL JOIN 會為該筆訂單建立 3 個相同的資料列 (每隻寵物各一列)。這樣會「分散」資料，並破壞平均訂單價值等指標，因為系統會將同一筆訂單的收益計算 3 次！如要修正這個問題，您必須先將寵物彙整到清單 (陣列) 中，再加入。

視使用的模型及其推論能力而定，代理程式會透過下列兩種方式處理這項要求：主動避免錯誤 (選項 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：主動式代理程式 (避免發生錯誤)

如果您使用進階推論模型，代理程式可能會在編寫任何程式碼之前偵測到粒度變化。系統發現客戶可以擁有多隻寵物，因此直接聯結會導致訂單重複，並立即讓您在 order_id 上要求的唯一性測試失敗。

1. 觀察主動彙整：在聊天窗格說明或逐步導覽構件中，代理程式可能會註記已預先彙整寵物資料，再加入資料，以避免「傳統扇出」。系統通常會使用匯總函式 (例如 ARRAY_AGG() 或 STRING_AGG())，為每位顧客收合多個寵物。
2. 查看結果：dbt build 首次執行並通過測試，因為代理程式主動保護了事實資料表的精細度。您可以檢查產生的 Walkthrough 構件，其中通常會顯示成功的測試輸出內容和查詢結果，藉此驗證這點。

如果代理人確實這麼做，恭喜你！您已見證主動式 AI 工程。請花點時間查看 fct_order_analysis.sql 中生成的 SQL，瞭解匯總的結構，然後跳到下一節「提供答案」。

方法 B：自我修復代理程式 (偵錯與診斷)

如果模型先編寫簡單的直接左側聯結，SQL 查詢本身會順利執行，但自動化 dbt test 套件會偵測到粒度變化！

1. 觀察測試失敗情形：您會在「Chat」窗格的執行進度記錄中看到失敗回報：

   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，這次所有模型都會具體化，且所有測試都會順利通過！

章節回顧：無論代理程式是主動避免錯誤，還是測試失敗後成功自我修復，您都已看到代理程式跨越 Cloud SQL 邊界、整合客戶和寵物設定檔資料，並維持完美的資料表細微程度。管道現在已穩固完整，且通過完整測試！

10. 提供答案

今天是星期四。您在一週開始時，面對的是憂心忡忡的財務長，以及分散在三項雲端服務中的資料。現在您已找出根本原因，並建立實際工作環境管道。現在是時候提供答案，以及根據量化預測結果提出的前瞻性建議。

撰寫內容提要

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)，並在對話中提供連結。

   每次執行時，確切數字、計算總和 (例如潛在損失的利潤或平均訂單價值降幅) 和格式配置都會有所不同。重點在於調查結果的核心結構邏輯。

3. 查看代理的內容提要。結構良好的典型回覆應包含以下內容：
   • 核心發現：1 月的平均訂單價值下降，完全是因為新的 B2B 批發通路。線上和線下仍穩定維持在$110 美元左右。
   • 根本原因：「B2B Wholesale Push」(大量訂單可享 75 折優惠) 吸引了 100 個新帳戶，帶來約 25,000 筆訂單。
   • 利潤影響：批發訂單使平均單位利潤減少約 65% (從約$7.50 美元降至約$2.60 美元)。
   • 收益：整體收益持平，因為 B2B 交易量高，抵銷了價格較低的影響。

使用 AI.FORECAST 預測平均訂單價值

4. 代理程式也應產生前瞻性預測。尋找 MCP 工具呼叫，其中代理程式會對 BigQuery 執行 AI.FORECAST 查詢。這項查詢會使用內建的 TimesFM 基礎模型，根據歷來趨勢預測未來 90 天的平均訂單價值。這項查詢應預測未來 90 天的平均訂單價值，並考量兩種情況：廣告活動持續放送 (平均訂單價值結構性下降)，以及廣告活動終止 (平均訂單價值回升至約$110 美元)。

提示 (如果服務專員未使用 AI.FORECAST)：如果服務專員提供的是質性預測而非量化預測，請嘗試下列做法：

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

5. 查看代理的策略建議。完整的建議可能包括：
   • 調整折扣結構：實施利潤底限或設定大量折扣上限，保護單一產品的利潤。
   • 強制執行更嚴格的最低訂購量：防止零售買家濫用批發價格。
   • 分開製作報表：獨立追蹤零售和 B2B 部門，避免掩蓋零售成效。

完整報導

週一，平均訂單價值下跌 7%，因此展開消防演習，而財務長已明確解決問題：

• 零售健康：核心零售通路維持健康穩定。
• 批發湧入：平均訂單價值下降完全是因為新的 B2B 批發管道和 BIGORDER25 廣告活動。
• 利潤影響：25% 的大量折扣大幅侵蝕單位利潤，即使收益持平，獲利仍受到威脅。
• 策略性預測：AI.FORECAST 預測結果顯示，重組批發層級可恢復混合平均訂單價值。

您提供有資料佐證的建議，以建立批發利潤下限，並區隔零售/B2B 報表。

章節重點：您要求代理程式撰寫利潤分析的執行摘要、生成 AI.FORECAST 預測，並提供以資料為依據的建議。調查完畢。

11. 清除

如要避免系統持續向您的 Google Cloud 帳戶收取費用，請執行清除指令碼，刪除本程式碼研究室建立的資源。

1. 在 Antigravity IDE 底部的「Terminal」面板 (或 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 執行個體仍會產生費用。如果略過拆除作業，您隨時可以稍後執行，或刪除用於本程式碼研究室的整個 Google Cloud 專案。

12. 恭喜！

您已順利完成「The Cymbal Pets Investigation」！您從模糊不清的財務長問題，到使用可處理整個 Google Cloud 資料資產的 AI 代理程式，獲得有預測資料佐證的完整建議。

你的成就

1. 🔍 跨服務探索：使用 Data Agent Kit 的 Knowledge Catalog，在 BigQuery、Cloud SQL 和 Cloud Storage 中探索及預覽資產。
2. 🕵️‍♂️ 透過 AI 進行調查：在單一即時通訊窗格對話中，使用 MCP 工具查詢多項服務，將 AOV 異常狀況追溯至大量 B2B 促銷活動。
3. 🔧 建構生產管道：搭建完整的 dbt 專案，用於清理、彙整及測試交易和客戶資料。
4. 🐛 修正擴散傳遞功能錯誤：觀察代理程式自動診斷精細程度問題，並重構 dbt SQL 模型，預先彙整顧客寵物設定檔。
5. 📈 預測和建議：使用 BigQuery 內建的 AI.FORECAST 模擬 AOV 趨勢，並向財務長提供資料驅動的建議。

核心概念

概念	您學到的內容
MCP 工具	安全且可稽核的連線，可讓 AI 代理代表您查詢 BigQuery、Cloud SQL、Spanner 和其他資料庫等服務，且每次呼叫都會顯示在「對話」窗格中
Agent Skills	預先建立的指令集 (例如 dbt-bigquery 或 discovering-gcp-data-assets)，可教導代理程式特定領域的最佳做法，無須提示
跨服務調查	在單一對話中查詢多項 Google Cloud 服務，不必設定連線，也不必在控制台之間切換
以目標為導向的提示	告訴代理程式你想要什麼 (「建立 dbt 專案，計算各管道的每筆交易平均金額」)，而不是如何，並讓代理程式選擇實作方法
Data Agent Kit	這個擴充功能會將所有項目 (MCP 工具、代理程式技能和資料探索) 綁在一起，讓您從所選 IDE 存取整個 Google Cloud 資料資產

後續步驟

• 如要進一步瞭解 Data Agent Kit 的功能，請參閱說明文件。
• 瞭解 BigQuery ML 和 AI 函式，包括 AI.FORECAST、AI.GENERATE 和 AI.EMBED
• 使用 Antigravity IDE 和自有資料，嘗試建構專屬的跨服務調查