Data Agent Kit と Antigravity IDE を使用した分析

1. はじめに

月曜日の朝、CFO からメッセージが届きました。今月は平均注文額が 7% 減少しましたが、総収益は横ばいです。何かおかしいことがあり、取締役会は金曜日までに回答を求めています。

Cymbal Pets は、米国最大手のオンライン ペット用品小売業者の 1 つです。必要なデータは、3 つの Google Cloud サービスに分散しています。販売履歴と注文履歴は BigQuery、顧客と商品のレコードは Cloud SQL、マーケティング ファイルは Cloud Storage にあります。通常、このようなサービス間の調査を行うには、コンソールを切り替え、接続ボイラープレートを作成し、結果を手動でつなぎ合わせる必要があります。

この Codelab では、Antigravity IDE で Google Cloud Data Agent Kit（DAK）を使用して、自然言語で異常を調査します。検索する内容を記述すると、AI エージェントが BigQuery、Cloud SQL、Cloud Storage 間の接続、SQL、クロスサービス結合を処理します。ケースを解決したら、エージェントに dbt パイプラインを構築して調査結果を運用化し、実際のデータ モデリング バグをデバッグして、予測に基づく推奨事項を CFO に提供するよう依頼します。

Antigravity を初めてご利用ですか？IDE を初めて使用する場合は、まず Google Antigravity のスタートガイドをご覧ください。

演習内容

• Knowledge Catalogを使用して、BigQuery、Cloud SQL、Cloud Storage 全体でデータアセットを検出する
• MCP ツールを使用して、単一の会話で複数のサービスをクエリして異常を調査する
• dbt パイプラインを構築する。ステージング モデルと自動テストを使用して、サービス間のデータをステージングして結合します。
• エージェントがファンアウト バグを自己診断してリファクタリングする際に、データ モデリングの問題をデバッグする
• 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]

リポジトリのクローンを作成する

Cloud Shell 環境に Codelab リポジトリのクローンを作成します。

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 e コマース データセット（92,000 人の顧客による約 190 万件の注文）です。これに、これから調査する謎が埋め込まれた企業間取引のレコードが追加されています。

セクションのまとめ: 設定スクリプトを実行してラボ環境をブートストラップし、バックグラウンド データベースのプロビジョニングを開始しました。

3. IDE と Data Agent Kit を設定する

Antigravity IDE を開く

Cloud SQL の完了を待つ必要はありません。Antigravity IDE を開いて、Google Cloud プロジェクトに接続します。

1. まだインストールしていない場合は、Google Antigravity ダウンロード ページから Antigravity IDE をダウンロードしてインストールします。
2. Antigravity IDE デスクトップ アプリケーションを起動します。
3. ローカルマシンに新しい空のフォルダ（agentic-data-labs など）を作成し、[フォルダを開く] を選択して IDE で開きます。これが、Codelab のローカル ワークスペースとして機能します。

Data Agent Kit 拡張機能をインストールする

Google Cloud Data Agent Kit 拡張機能は、BigQuery、Cloud SQL、Cloud Storage 用のデータカタログ ブラウザ、エージェント スキル、MCP サーバーを追加します。これにより、エディタからこれらのサービスをクエリして検査できます。

1. Antigravity IDE で、画面の左端にあるアクティビティ バーの [拡張機能] アイコン（4 つの正方形のようなアイコン）をクリックします。
2. [拡張機能] ペインの上部にある検索バーに「Google Cloud Data Agent Kit」と入力します。
3. Google Cloud Data Agent Kit という名前の最初の結果（googlecloudtools によって公開）を見つけます。
4. [Install] ボタンをクリックします。
5. 「パブリッシャー「googlecloudtools」とその拡張機能を信頼しますか？」というメッセージが表示されることがあります。[Trust Publishers & Install] をクリックして続行します。

インストールが完了すると、Antigravity IDE の左端にあるアクティビティ バーに、新しい Google Cloud Data Agent Kit アイコンが表示されます。

拡張機能を認証して構成する

インストール後、拡張機能を Google Cloud プロジェクトに接続します。

1. 「Google Cloud Data Agent Kit へようこそ」というタイトルのオンボーディング ページが自動的に開きます。Cloud アカウントにログインしていない場合は、画面の指示に沿ってアクセスを許可します。
2. [構成の概要] セクションで、プロジェクト フィールドを見つけます。プルダウンをクリックして、Google Cloud プロジェクトを選択します。リージョンを us-central1 に設定します。[Configure MCP Servers] を選択します。

3. [MCP 構成] ペインで、[BigQuery] と [Cloud SQL] をクリックして有効にします。[使ってみる] をクリックします。

すでにインストールされている場合や、ようこそページが開かない場合拡張機能の設定はいつでも手動で開くことができます。左端のアクティビティ バーで Google Cloud Data Agent Kit アイコンをクリックし、[設定] を選択して、構成を切り替えます。

アクティブなスキル/MCP に関する注: IDE で他のカスタムスキルまたは MCP サーバーがアクティブになっている場合、このラボの想定されるフローが妨げられる可能性があります。エージェントが予期しない動作をする場合は、このラボではエージェントを無効にすることを検討してください。

構成オプションを確認する

設定が完了すると、[Google Cloud Data Agent Kit を使ってみる] ページが表示されます。

1. [設定と構成] で、[開始] をクリックします。
2. [Data Agent Kit Configuration] パネルが開きます。タブを確認します。
   • プロジェクトとリージョン: 選択したプロジェクト ID を確認し、必要な API（Cloud Storage API、BigQuery API、Catalog API、Cloud SQL Admin API）が有効になっていることを確認します。
   • BigQuery: BigQuery クエリのデフォルトの場所を構成します。リージョン us-central1 を使用します。
   • MCP サーバーを構成する: AI エージェントがデータを安全に操作できるようにする、有効な MCP サーバー（BigQuery、Notebooks、Cloud SQL など）を表示します。
   • スキル: エージェントに複雑なデータタスク用の特別な機能を提供する事前構築済みのスキルを確認します。

セクションのまとめ: Antigravity IDE を開き、Google Cloud プロジェクトに接続して、Data Agent Kit のリモート MCP サーバーを構成しました。

4. データを検出する

シーンを設定しましょう。状況は次のとおりです。CFO は、先月の平均注文額が 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] パネルの [CATALOG] セクションで、[Universal Search]（ユニバーサル検索）をクリックします。
6. 検索ボックスに「pet_profiles」と入力して、Enter を押します。
7. 検索結果で、pet_profiles の PostgreSQL テーブルの結果（プロジェクトの Cloud SQL インスタンスの下）をクリックします。サイドバーのアコーディオンが自動的に展開され、データベース ツリー内のテーブルの場所が正確に表示されます。ツリーのすぐ上にある customers テーブルをクリックして詳細を開き、[スキーマ] タブと [詳細] タブを確認します。

Cloud Storage ファイルを調べる

最後に、マーケティング キャンペーンとプロモーション キャンペーンのレコードが Cloud Storage に未加工の JSON ファイルとして保存されます。

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	約 92, 000 人のお客様、約 7, 600 件のペット プロフィール、206 個の商品
Cloud Storage	promo_events.json	プロモーション キャンペーンの記録

データがサービス間で分割されているのはなぜですか？これは、実際のアーキテクチャを反映しています。Cloud SQL は OLTP（トランザクション）データベースです。顧客の住所の更新や単一の注文の処理など、高速な行レベルのオペレーションに最適化されています。BigQuery は OLAP（分析）ウェアハウスです。「今月の平均注文額はいくらか？」などの質問に答えるために数百万行をスキャンする場合に適しています。ほとんどの組織では、データが両方に存在します。そのため、Data Agent Kit などのクロスサービス調査ツールが非常に重要になります。

データは 3 つのサービスに分散されています。従来のワークフローでは、接続を設定し、統合コードを記述して、結果を手動で結合する必要があります。次のステップでは、AI エージェントが 1 つの会話ですべてを処理できるようにします。

セクションのまとめ: Data Agent Kit パネルを使用して、BigQuery、Cloud SQL、Cloud Storage 全体のデータ アーキテクチャを手動で探索しました。データの保存場所と使用可能なフィールドがわかったので、調査を開始できます。

5. 番号に沿って操作します。

調査が開始されます。チャット ペインを使用して、AI エージェントに BigQuery から平均注文額（AOV）データを取得するよう依頼します。AOV は、1 回の注文あたりに費やされる平均金額を表すビジネス指標です。エージェントは 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 は、データにアクセスする前に明示的な権限を求めることで、ユーザーが制御できるようにします。プロンプトが表示されたら、次のいずれかを選択します。
   • 今回のみ許可: 1 回の使用を承認します（リスクの高いクエリの監査に最適です）。
   • 常に許可: セッション中にこの特定のツールの使用を継続的に承認します。
   • No: アクションを完全にブロックします。

ラボをスムーズに利用するには、[はい、常に許可します] を選択します。注: 権限はツールごとに付与されます。エージェントが新しいツール（list_table_ids や execute_sql_readonly など）を使用すると、すぐにいくつかのプロンプトが表示される可能性があります。これらのプロンプトも [常に許可] に設定していただいて構いません。

3. エージェントの動作を確認します。チャット ペインは、エージェントが行ったすべての操作の透明性ログとしても機能します。エージェントはブラック ボックスではなく、推論とアクションをリアルタイムで表示します。
4. エージェントが終了したら、プロンプトの下にある [Worked for Xm] プルダウンをクリックして、完全な作業ログを開きます。ここでは、回答がどのように生成されたかを詳しく調べることができます。
   • Explored: これらの項目を開くと、エージェントがファイルを読み取ったり、フォルダを参照したり、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 は減少しましたが、その原因は何でしょうか？Let's find out.（HONEY の節約額を確認してみましょう。）

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 で安定しています。しかし、平均注文額がはるかに低い（約 75 ドル）新しいチャネル B2B-Wholesale があります。この新しいチャネルがブレンド平均値を押し下げています。
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 ツールが表示されます。エージェントは BigQuery ではなく Cloud SQL にクエリを実行するようになりました。エージェントは 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 人のユーザーが該当します。

サービス境界を越える。エージェントは、同じ会話内で 2 つの異なる 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-Wholesale 注文の約 92% に promo_code = 'BIGORDER25' が含まれていることを確認します。B2B アクティビティのほぼすべてが 1 つのプロモーション キャンペーンに関連付けられています。エージェントは、環境内の他の場所でプロモーション データを検索する可能性があります。（Cloud Storage にあります）。

セクションの要約: エージェントは Cloud SQL にクエリを実行し、B2B 顧客がすべて 2025 年 1 月に登録した新規ビジネスであることを明らかにしました。BigQuery の調査で、注文の約 92% に promo_code = 'BIGORDER25' が含まれていることが判明したため、プロモーション キャンペーンが原因である可能性が高くなりました。ソースを見つける時間です。

7. 欠けているピースを見つける

2 つのサービスがダウンし、もう 1 つがダウンする可能性があります。何が起こったのか（B2B 注文が AOV を押し下げている）、誰がそれを行っているのか（過去 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 などのコマンドを実行する権限を求められます。これらのコマンドを許可し、Chat ペインの [実行] ログを開いて、promo_events.json ファイルの読み取りと解析に使用された正確な CLI コマンドを確認します。
3. エージェントは、ファイル内の 3 つのプロモーション キャンペーンを特定する必要があります。

   キャンペーン	プロモーション コード	割引	ターゲット	日付
   ペットケア用品のサマーセール	PETSUMMER15	15% 割引	すべて	2024 年 6 月
   B2B 卸売プッシュ	BIGORDER25	25% オフ	B2B	2025 年 1 月
   ポイント プログラム メンバーのホリデー ボーナス	LOYAL10	10% オフ	ロイヤリティ メンバー	2024 年 12 月

   それが原因です。BIGORDER25 プロモーション コードは、B2B Wholesale Push というキャンペーンに対応しています。B2B のお客様は、最小注文数 50 個で 25% 割引になります。

3 つのサービスを 1 つの会話に。最後の 3 つのセクションでは、エージェントが BigQuery（販売履歴と注文履歴）、Cloud SQL（顧客データと商品データ）、Cloud Storage（プロモーション レコード）にクエリを実行しました。すべて同じチャット スレッドから、ユーザー側の構成やコンテキストの切り替えは必要ありません。これが Data Agent Kit のコアバリューです。データ資産全体で動作する単一の AI エージェントです。

すべてをまとめる

4. エージェントに、見つかったすべての情報を統合するよう依頼します。

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

5. エージェントは、3 つのデータソースすべてを接続する明確で構造化された統合を提供します。次のような説明が表示されます。
   1. AOV の減少は事実ですが、既存のビジネスの減少ではありません。オンラインとオフラインの AOV は約$110 で安定しています。
   2. 2025 年 1 月に新しい B2B 卸売チャネルが登場し、注文数は約 25,000 件、AOV は大幅に低い（約$75 ～ 100）です。
   3. B2B のお客様は、過去 30 日以内に登録した 100 個の新しいビジネス アカウントです（Cloud SQL）。
   4. このアクティビティは、50 個以上の注文で 25% 割引を提供するプロモーション キャンペーン（「B2B Wholesale Push」）によって促進されています（Cloud Storage）。
   5. B2B 注文の量が多いことで、価格の低下が相殺され、収益は横ばいになっています。ただし、卸売割引率が 25% の場合、ユニットの利益率は大幅に圧縮され（約 65% 減少）、送料と運用上のオーバーヘッドを考慮すると、全体的な収益性が著しく脅かされます。
   この時点で調査が完了します。CFO の質問に対する明確な答えは、マーケティング主導の B2B プログラムにより、1 月に大量の低価格注文が殺到したため、AOV が低下したということです。既存のビジネスは健全です。

セクションのまとめ: Cloud Storage で原因を特定しました。原因は、一括注文で 25% 割引を提供する B2B プロモーション キャンペーンでした。エージェントは、3 つのサービスすべての調査結果を明確な説明にまとめました。調査フェーズが完了しました。次に、これらの結果を運用化します。

8. パイプラインをビルドする

事件を解決しました。CFO は、この分析が自動的に更新されることを望んでいます。このセクションでは、BigQuery データをステージングし、継続的な AOV 分析用のファクト テーブルを生成する dbt プロジェクトを構築するようにエージェントに指示します。

ここで、エージェントは調査担当者からエンジニアに移行します。単一のプロンプトから、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') または緩和された null 制約が表示されることがあります。このモデルは、アカウントなしで行われた小売店のゲスト購入をモデル化し、不完全なレコードを削除する代わりに有効な注文収益を保持します。

マートコードの確認: models/marts/fct_order_analysis.sql を開きます。注文粒度でファクト テーブルを維持するために、まず項目を統合していることに注目してください。ヒント: /target/ 内の自動生成されたファイルではなく、models/ ディレクトリ内のソースファイルのみを編集してください。

7. チャット ペインで（または生成されたウォークスルー アーティファクトをクリックして）、すべてのモデルがマテリアライズされ、すべてのテストに合格したことをエージェントが確認したことを確認します。マートの AOV の結果は、調査中に判明した内容を裏付けるものである必要があります。

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

セクションの要約: エージェントは、目標指向の単一のプロンプトから dbt プロジェクトを構築しました。ステージング モデルとマートモデルをスキャフォールディングし、dbt build を正常に実行して、AOV の異常を確認しました。次に、エージェントが複雑さをどのように処理するかを確認するために、変化球を投げます。

9. テストが失敗すると、エージェントがデバッグします。

パイプラインは機能しますが、BigQuery データのみを使用します。プロダクト チームは、Cloud SQL の顧客とペットのプロフィール データを使用して分析を拡充し、食事のニーズに基づいて商品を推奨したいと考えています。つまり、エージェントは Cloud SQL の境界をブリッジし、微妙なデータ モデリング バグ（古典的なディメンショナル モデリングの「ファンアウト」結合）を処理する必要があります。

「ファンアウト」とは何ですか？1 件の注文が 3 匹のペットを飼っている顧客に属している場合、標準 SQL JOIN は、その 1 件の注文に対して 3 つの同一の行を作成します（ペットごとに 1 つ）。これによりデータが「拡散」し、同じ注文の収益が 3 回カウントされるため、平均注文額などの指標が台無しになります。この問題を修正するには、結合する前にペットをリスト（配列）に集約する必要があります。

使用しているモデルとその推論機能に応じて、エージェントはこのリクエストを 2 つの方法（バグを事前に回避する（オプション 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: プロアクティブ エージェント（バグ回避）

高度な推論モデルを使用している場合、エージェントはコードを記述する前に粒度の変化を検出することがあります。お客様は複数のペットを飼っている可能性があるため、直接結合すると注文が重複し、order_id でリクエストした一意性テストが失敗します。

1. 事前集計を観察する: エージェントは、チャット ペインの説明またはウォークスルー アーティファクトで、ペットデータを結合する前に事前集計して「従来のファンアウト」を防いだことをメモしている場合があります。通常、この処理は集計関数（ARRAY_AGG() や STRING_AGG() など）を使用して、顧客ごとに複数のペットを折りたたむことで行われます。
2. 結果を確認する: エージェントがファクト テーブルの粒度を事前に保護したため、dbt build は 1 回目の試行で正常に実行され、合格します。これを確認するには、生成されたチュートリアル アーティファクトを確認します。多くの場合、クエリ結果とともに成功したテスト出力が表示されます。

エージェントがバグを回避しました。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 で 1 対多の関係を検出します。エージェントは、この関係を直接結合すると、粒度が 1 行 / 注文から 1 行 / 注文 / ペットに変更されることを説明し、ペット プロファイルを事前集計するようにモデルを書き換えます。

   -- 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 の境界を越え、顧客とペットのプロフィール データを統合し、ファクト テーブルで注文ごとに 1 行を維持していることがわかりました。パイプラインが完成し、テスト済みです。

10. 回答を配信する

木曜日です。週の初めは、CFO が心配しており、3 つのクラウド サービスにデータが分散していました。これで、根本原因と本番環境パイプラインが特定されました。回答を配信するまでの時間と、定量的な予測に裏付けられた将来を見据えた推奨事項。

エグゼクティブ サマリーを作成する

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. エージェントの動作を確認します。

   出力形式とバリエーションに関する注: 大規模言語モデルは非決定的です。アクティブなモデルに応じて、エージェントは Chat ペインに直接要約を出力することも、専用の Markdown ファイル（executive_summary_cfo.md や output.txt など）を作成してチャットにリンクすることもできます。

   正確な数値、計算された合計（潜在的な利益の損失や平均 AOV の減少など）、フォーマット レイアウトは実行ごとに変動します。重要なのは、調査結果の構造的なロジックです。

3. エージェントのエグゼクティブ サマリーを確認します。一般的で構造化された回答では、次の点に対応する必要があります。
   • 主な結果: 1 月の AOV は、新しい B2B 卸売チャネルのみが原因で減少しました。オンラインとオフラインは引き続き安定しており、約 110 ドルです。
   • 根本原因: 「B2B Wholesale Push」（一括注文 25% オフ）により、100 個の新しいアカウントが獲得され、約 25,000 件の注文が発生しました。
   • 利益への影響: 卸売注文により、平均単価利益が約 65% 減少しました（約 7.50 ドルから約 2.60 ドルに）。
   • 収益: B2B のボリュームが大きいため、価格の低下が相殺され、全体的な収益は横ばい。

AI.FORECAST を使用して AOV を予測する

4. また、エージェントは将来の予測も生成する必要があります。エージェントが BigQuery に対して AI.FORECAST クエリを実行する MCP ツール呼び出しを探します。このクエリでは、組み込みの TimesFM 基盤モデルを使用して、過去の傾向に基づいて AOV を 90 日間予測します。このクエリでは、キャンペーンの継続（構造的に AOV が低下）とキャンペーンの終了（約$110 まで回復）の 2 つのシナリオで AOV を 90 日間予測します。

ナッジ（エージェントが AI.FORECAST を使用していない場合）: エージェントが定量的な予測ではなく定性的な予測を提供している場合は、次のことを試してください。

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

5. エージェントの戦略的な推奨事項を確認します。推奨事項には、以下を含める必要があります。
   • 割引を再構築する: 単位レベルの利益率を保護するために、利益率の下限を設定するか、一括割引の上限を設定します。
   • より厳しい MOQ を適用する: 小売業者が卸売価格を不正使用するのを防ぎます。
   • レポートを分ける: 小売部門と B2B 部門を個別にトラッキングして、小売部門のパフォーマンスが隠蔽されないようにします。

全文

月曜日に平均注文額が 7% 減少したことに対する訓練として始まったこの問題について、CFO は明確な解決策を提示しました。

• 小売ヘルスケア: 主要な小売チャネルは、ベースラインで健全かつ安定した状態を維持しています。
• 卸売の流入: AOV の低下は、新しい B2B 卸売チャネルと BIGORDER25 キャンペーンが原因です。
• 利益率への影響: 25% の一括割引により、ユニットの利益率が大幅に低下し、収益が横ばいにもかかわらず収益性が脅かされています。
• 戦略的予測: AI.FORECAST の予測によると、卸売階層を再構築すると、平均注文額のブレンドが回復します。

卸売マージンの下限を設定し、小売/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. 🐛 ファンアウト バグをデバッグ: エージェントが粒度の問題を自動的に診断し、dbt SQL モデルをリファクタリングして顧客のペット プロファイルを事前集計するのを確認しました。
5. 📈 予測と推奨: BigQuery の組み込みの AI.FORECAST を使用して AOV の傾向をモデル化し、データドリブンの推奨事項を CFO に提供しました。

主なコンセプト

コンセプト	学習した内容
MCP ツール	安全で監査可能な接続。AI エージェントが BigQuery、Cloud SQL、Spanner などのサービスや他のデータベースに対してユーザーに代わってクエリを実行し、すべての呼び出しがチャット ペインに表示されます。
Agent Skills（エージェントのスキル）	エージェントにドメイン固有のベスト プラクティスを教える事前構築済みの命令セット（dbt-bigquery や discovering-gcp-data-assets など）。プロンプトを入力する必要はありません。
クロスサービス調査	エージェントは、接続設定やコンソール間のコンテキスト切り替えなしで、1 つの会話で複数の Google Cloud サービスをクエリします。
目標指向のプロンプト	エージェントに「どのように」ではなく「何を」してほしいかを伝え（「チャネル別に AOV を計算する dbt プロジェクトを構築して」）、実装方法をエージェントに選択させる
Data Agent Kit	MCP ツールやエージェント スキルからデータ検出まで、すべてを統合する拡張機能。選択した IDE 内から Google Cloud のデータ資産全体にアクセスできます。

次のステップ

• データ エージェント キットのドキュメントで、その機能の詳細を確認する
• AI.FORECAST、AI.GENERATE、AI.EMBED などの BigQuery ML と AI 関数について学習する
• 独自のデータで Antigravity IDE を使用して、独自のクロスサービス調査を構築してみる