Antigravity CLI を使用してデータ コンテキストをテストする

AI エージェントは推論できますが、特定の企業に関する知識はゼロから始まります。エージェントに「第 1 四半期の収益は？」と質問することを考えてみましょう。ガイダンスがないと、エージェントはデータベース内の「収益」という名前の数十個のテーブル（公式レポートからテストデータまで）から選択する可能性があります。エージェントが最も近い名前のテーブルを選択した場合、未確認のソースに基づいて説得力のある誤った回答を返す可能性があります。

このコンテキストの問題を解決するのがメタデータの拡充です。このチュートリアルでは、このコンテキストを提供するアスペクトを設定し、Antigravity CLI を使用してデータ コンテキストをテストし、エージェントが信頼できる認定データに基づいて回答を正確に生成できることを確認します。

目標

  • テスト用に現実的なマルチティア データレイクをデプロイします。
  • Knowledge Catalog でカスタム メタデータ テンプレート（アスペクト タイプ）を設計して登録し、公式のデータ プロダクトと未加工のサンドボックス テーブルを区別します。
  • Antigravity CLI（agy）を使用してデータガバナンス ルールを検証します。

始める前に

始める前に、次の操作を行ってください。

このチュートリアルを完了するには、BigQuery と Knowledge Catalog の基本的な知識も必要です。

環境を準備する

このチュートリアルでは、クラウドで実行されるコマンドライン環境である Google Cloud Shell を使用します。Antigravity CLI（agy）は、Google Cloud Shell にプリインストールされています。

  1. Google Cloud コンソールで、右上のツールバーにある [Cloud Shell をアクティブにする] をクリックします。環境がプロビジョニングされ、接続されるまでしばらく待ちます。

  2. Cloud Shell で PROJECT_ID 変数と REGION 変数を設定して、以降のすべてのコマンドが特定の Google Cloud プロジェクトをターゲットとするようにします。

    export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

  3. 必要な Google Cloud サービスを有効にします。

    gcloud services enable \
  artifactregistry.googleapis.com \
  bigquery.googleapis.com \
  dataplex.googleapis.com \
  aiplatform.googleapis.com \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  iam.googleapis.com

  4. Google Cloud DevRel Demos リポジトリのクローンを作成します。

    GitHub からインフラストラクチャ コードとスクリプトをダウンロードします。スパース チェックアウトを使用して、このチュートリアルに必要な特定のフォルダのみを pull します。

    # Perform a shallow clone to get only the latest repository structure without the full history
git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos

# Specify and download only the folder you need for this tutorial
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

サンプル データレイクを構築する

現実世界のデータ環境は、クリーンであることはほとんどありません。現実をシミュレートするには、「公式」データマートと信頼できない「サンドボックス」テーブルを混在させる必要があります。

設定スクリプトを使用して、BigQuery データセットとテーブルをデプロイします。

設定スクリプトを実行可能にして実行します。これにより、3 つの BigQuery データセット（finance_mart、marketing_prod、analyst_sandbox）が作成され、そのテーブルにサンプルデータが入力されます。

chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

これで、データレイクにデータが完全に取り込まれましたが、ガバナンスは適用されていません。AI エージェントにとって、すべてのテーブルはまったく同じように見えます。

データ ガバナンス テンプレート（アスペクト タイプ）を作成する

次に、データ ガバナンスのルールを定義します。Knowledge Catalog でこれを行うには、再利用可能な厳密な型指定のメタデータ テンプレートであるアスペクト タイプを作成します。

このセクションでは、gcloud CLI を使用してこのテンプレートを登録し、その定義を確認します。

アスペクト スキーマを調べる

aspect_template.json の内容を出力して、スキーマ定義を確認します。

cat aspect_template.json

次の JSON 構造が表示されます。

{
  "name": "OfficialDataProductSpec",
  "type": "record",
  "recordFields": [
    {
      "name": "product_tier",
      "type": "enum",
      "enumValues": [
        { "name": "GOLD_CRITICAL", "index": 1 },
        { "name": "SILVER_STANDARD", "index": 2 },
        { "name": "BRONZE_ADHOC", "index": 3 }
      ],
      ...
    },
    {
      "name": "is_certified",
      "type": "bool",
      ...
    }
  ]
}

このスキーマでは、重要度階層（GOLD_CRITICAL、SILVER_STANDARD、BRONZE_ADHOC）に enum、is_certified に bool など、厳密なデータ型が適用されています。これにより、メタデータが構造化され、マシンで読み取り可能になります。

アスペクト タイプを登録する

次の gcloud コマンドを実行して、このテンプレートを Knowledge Catalog レジストリに登録します。

gcloud dataplex aspect-types create official-data-product-spec \
    --location="${REGION}" \
    --project="${PROJECT_ID}" \
    --description="Defines the comprehensive profile of a data product for data governance agents." \
    --display-name="Official Data Product Spec" \
    --metadata-template-file-name="aspect_template.json"

データ ガバナンスを適用する

これは重要なエンジニアリング ステップです。現在、テーブル finance_mart.fin_monthly_closing_internal と analyst_sandbox.tmp_data_dump_v2_final_real は AI エージェントとまったく同じように見えます。これらは列を持つオブジェクトにすぎません。

これらを区別するには、アスペクトを適用します。これにより、認定メタデータ ラベルがこれらのテーブルに付加され、区別できるようになります。実際の企業では、CI/CD パイプラインを使用してこれを自動化します。このチュートリアルでは、スクリプトを使用して自動化をシミュレートします。

データ ガバナンス ペイロードを生成する

Knowledge Catalog のアスペクト キーはグローバルに一意である必要があります（プロジェクト ID が接頭辞として付加されます）。./generate_payloads.sh スクリプトは、YAML メタデータ ファイルを動的に生成します。

chmod +x ./generate_payloads.sh
./generate_payloads.sh

これにより、さまざまなデータガバナンス シナリオ（fin_internal.yaml、fin_public.yaml、mkt_realtime.yaml、sandbox.yaml）を定義する 4 つの YAML ファイルを含む aspect_payloads/ ディレクトリが作成されます。

CLI を使用してアスペクトを適用する

  1. スクリプトを実行する前に、テーブルに添付するデータを確認します。次のコマンドを実行して、内部財務データのメタデータを表示します。

    cat aspect_payloads/fin_internal.yaml

    YAML ファイルは、テーブルのビジネス コンテキストを定義します。

    your-project-id.us-central1.official-data-product-spec:
  data:
    product_tier: GOLD_CRITICAL
    data_domain: FINANCE
    usage_scope: INTERNAL_ONLY
    update_frequency: DAILY_BATCH
    is_certified: true

    この例では、is_certified: true の設定や GOLD_CRITICAL 階層の割り当てなど、ビジネス コンテキストが明示的に定義されています。これにより、AI エージェントはテーブル名に基づいて推測するのではなく、評価するための明確で構造化されたルールを取得できます。

  2. アプリケーション スクリプトを実行します。このスクリプトは、BigQuery テーブルを反復処理し、gcloud dataplex entries update コマンドを使用して、各テーブルにメタデータ ペイロードを添付します。

    chmod +x ./apply_governance.sh
./apply_governance.sh

メタデータを確認する

次に進む前に、スクリプトが Google Cloud コンソールでアスペクトを正しく適用したことを確認します。

  1. Google Cloud コンソールで [Knowledge Catalog] ページを開きます。上部にある検索バーを使って拡張機能を探すことができます。
  2. fin_monthly_closing_internal を検索します。結果で BigQuery テーブル名を選択して、詳細ページを開きます。
  3. 下部の [オプションのタグとアスペクト] セクションで、official-data-product-spec アスペクトを見つけます。値が適用した「Gold Internal」シナリオと一致していることを確認します。

これで、技術的に同一の BigQuery テーブル（fin_monthly_closing_internal と tmp_data_dump_v2_final_real）が、マシンリーダブルなメタデータによって論理的に区別されていることを確認できました。

Antigravity CLI を使用してデータ コンテキストをテストする

アプリケーションをビルドする前に、Antigravity CLI を使用してデータガバナンス ロジックをローカルで検証できます。これを行うには、Knowledge Catalog プラグインをインストールして、エージェント スキルを構成します。

サービス プラグインをインストールする

Cloud Shell で、サービス プラグインをインストールします。

export DATAPLEX_PROJECT="${PROJECT_ID}"

agy plugin install https://github.com/gemini-cli-extensions/dataplex

エージェント スキルを検査する

エージェント スキルは、.agents/skills/knowledge-catalog-governance/SKILL.md にある静的で再利用可能な定義ファイルです。これには、「安全なデータが必要」などの抽象的な人間のルールを構造化された技術的なルックアップに変換するロジックが含まれています。

スキル設定を確認し、データ コンテキストの仕組みを理解するには、SKILL.md ファイルを調べます。

cat .agents/skills/knowledge-catalog-governance/SKILL.md

このプロンプトは、モデルに厳密なフェーズ 1（メタデータの検証）とフェーズ 2（クエリの実行）のループに従うよう指示しています。モデルは、SQL ステートメントを構築する前に、メタデータを検出して検証する必要があります。この検索優先ロジックにより、エージェントがテーブル名を推測したり、未確認のソースから回答を生成したりすることを防ぐことができます。

Antigravity CLI を起動してシナリオをテストする

Antigravity CLI セッションを開始します。プロジェクト フォルダにいるため、CLI は .agents/skills ディレクトリからスキルを自動的に検出して読み込みます。

agy

インストールを確認する

Antigravity CLI のプロンプトで、プラグインが有効になっていることを確認します。/mcp と入力して、構成済みのツールとプラグインを一覧表示します。

/mcp

出力には、knowledge-catalog がアクティブなプラグインとしてリストされ、使用可能なツールが表示されます。

MCP Servers ... >  ✓ knowledge-catalog  Tools: search_entries, lookup_context, lookup_entry

試してみる

それでは、データ コンテキストの動作を確認しましょう。これらのプロンプトを Antigravity CLI セッションに 1 つずつ貼り付けます。

シナリオ 1: 「ゴールド」標準データを見つける

Antigravity CLI が、重要な取締役会で最も信頼できるデータを見つけられるかどうかを確認します。

We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?

CLI は元データをスキップして fin_monthly_closing_internal を見つける必要があります。これは、リクエストされた「確定」データと「機密」データを、以前に適用した GOLD_CRITICAL タグと INTERNAL_ONLY タグと照合することで実現されます。

シナリオ 2: 公開

データを外部で共有したいとします。CLI で内部シークレットが漏洩しないようにします。

I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?

内部テーブルには最も詳細な情報が含まれていますが、CLI はこのテーブルをバイパスする必要があります。EXTERNAL_READY というタグが付いているテーブルは fin_quarterly_public_report だけなので、fin_quarterly_public_report が返されます。

シナリオ 3: リアルタイムの運用ニーズ

データ サイエンティストは最新の情報を必要とすることがよくあります。Antigravity CLI が毎日のバッチとライブストリームの違いを理解しているかどうかを確認します。

My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?

CLI は mkt_realtime_campaign_performance を検出します。メタデータ内の REALTIME_STREAMING の更新の頻度を識別します。

シナリオ 4: サンドボックスの探索

「完璧」よりも「十分」な方が良い場合もあります。Antigravity CLI で、試験運用中の ML 作業の未加工のサンドボックス データを見つけられるかどうかを確認します。

I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment.

CLI は tmp_data_dump_v2_final_real を検出します。この選択が正しいのは、BRONZE_ADHOC 階層と一致し、is_certified: false で明示的にマークされているためです。

テストが完了したら、CLI セッションを終了できます。

/quit

クリーンアップ

定期購入料金が発生しないようにするには、次の手順を行います。

  1. Antigravity CLI セッションで、Ctrl+C を 2 回押すか、/quit と入力してセッションを終了します。

  2. クリーンアップ スクリプトを実行して、このチュートリアルで作成した BigQuery テーブル、データセット、Knowledge Catalog アスペクト タイプを破棄します。

    chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh

  3. サービス プラグインをアンインストールし、ローカルのデモファイルを削除します。

    agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos

まとめ

堅牢なデータ基盤を構築し、メタデータを使用して厳密なコンテキストを適用し、Antigravity CLI を使用してすべてがローカルで動作することを確認しました。

次のステップ