Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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

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

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

目標

テスト用に、現実的な多層データレイクを BigQuery にデプロイする。
Knowledge Catalog でカスタムメタデータテンプレート（アスペクトタイプ）を設計して登録し、公式データプロダクトと未加工のサンドボックステーブルを区別する。
Antigravity CLI (agy) を使用して、データガバナンスルールと AI エージェントのグラウンディングを確認する。

始める前に

始める前に、次のことを確認してください。

このチュートリアルで使用するGoogle Cloud プロジェクトを選択します。
プロジェクトで課金が有効になっていることを確認します。

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

環境を準備する

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

Google Cloud コンソールで、右上のツールバーにある [Cloud Shell をアクティブにする] をクリックします。環境がプロビジョニングされ、接続されるまでしばらく待ちます。
Cloud Shell で、今後のすべてのコマンドが特定の Google Cloud プロジェクトを対象とするように、PROJECT_ID 変数と REGION 変数を設定します。
```
export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"
```

必要な 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

Google Cloud DevRel Demos repository のクローンを作成します。

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

# 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 にサンプルデータレイクをデプロイする

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

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

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

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

これで、データが完全に取り込まれた、管理されていないデータレイクができました。AI エージェントから見ると、すべてのテーブルはまったく同じように見えます。

Knowledge Catalog でカスタムアスペクトタイプを定義する

次に、データガバナンスのルールを定義します。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 など、厳密なデータ型が適用されます。これにより、メタデータの構造が維持され、マシンリーダブルになります。

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

次の 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/ ディレクトリが作成されます。

BigQuery テーブルにアスペクトをアタッチする

スクリプトを実行する前に、テーブルにアタッチするデータを確認します。次のコマンドを実行して、内部財務データのメタデータを表示します。
```
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 エージェントはテーブル名に基づいて推測するのではなく、明確で構造化されたルールに基づいて評価できます。
アプリケーションスクリプトを実行します。このスクリプトは BigQuery テーブルを反復処理し、gcloud dataplex entries update コマンドを使用して、各テーブルにメタデータペイロードをアタッチします。
```
chmod +x ./apply_governance.sh
./apply_governance.sh
```

コンソール Google Cloud で適用されたアスペクトを確認する

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

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

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

Antigravity CLI でデータコンテキストをテストする

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

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

CLI でプラグインのインストールを確認する

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 のみであるため、このテーブルを指す必要があります。

シナリオ 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

クリーンアップ

繰り返し料金が発生しないようにするには、次の手順を行います。

Antigravity CLI セッションで、Ctrl+C を 2 回押すか、/quit と入力してセッションを終了します。
クリーンアップスクリプトを実行して、このチュートリアルで作成した BigQuery テーブル、データセット、Knowledge Catalog アスペクトタイプを破棄します。
```
chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh
```
サービスプラグインをアンインストールし、ローカルのデモファイルを削除します。
```
agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos
```

次のステップ

他の Knowledge Catalog のユースケースを試す。

Antigravity CLI を使用してデータ コンテキストをテストする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

目標

始める前に

環境を準備する

BigQuery にサンプル データレイクをデプロイする

Knowledge Catalog でカスタム アスペクト タイプを定義する

アスペクト テンプレート スキーマを調べる

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

データレイク テーブルにガバナンス アスペクトをアタッチする

アスペクト メタデータ ペイロードを生成する