Menggunakan Antigravity CLI untuk menguji konteks data

Pengayaan metadata di Knowledge Catalog (sebelumnya Dataplex Universal Catalog) memungkinkan Anda memberikan konteks data terstruktur sehingga agen AI dapat mendasarkan jawabannya pada sumber tepercaya dan bersertifikasi. Dalam tutorial ini, Anda akan melampirkan aspek kustom ke tabel BigQuery contoh dan menggunakan Antigravity CLI untuk menguji cara agen AI menerapkan aturan tata kelola Anda.

Tujuan

• Men-deploy data lake multi-tingkat yang realistis di BigQuery untuk pengujian.
• Mendesain dan mendaftarkan template metadata kustom (jenis aspek) di Knowledge Catalog untuk membedakan produk data resmi dari tabel sandbox mentah.
• Verifikasi aturan tata kelola data dan grounding agen AI menggunakan Antigravity CLI (agy).

Sebelum memulai

Sebelum memulai, pastikan Anda melakukan hal berikut:

• Pilih projectGoogle Cloud untuk tutorial ini.
• Konfirmasi bahwa penagihan diaktifkan untuk project Anda.

Untuk menyelesaikan tutorial ini, Anda juga harus memiliki pemahaman dasar tentang BigQuery dan Knowledge Catalog.

Menyiapkan lingkungan Anda

Tutorial ini menggunakan Google Cloud Shell, lingkungan command line yang berjalan di cloud. Antigravity CLI (agy) sudah diinstal sebelumnya di Google Cloud Shell.

1. Dari konsol Google Cloud , klik Activate Cloud Shell di toolbar kanan atas. Proses menyediakan dan menghubungkan ke lingkungan memerlukan waktu beberapa saat.

2. Di Cloud Shell, tetapkan variabel PROJECT_ID dan REGION Anda sehingga semua perintah mendatang menargetkan project Google Cloud spesifik Anda.

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

3. Aktifkan layanan Google Cloud yang diperlukan.

   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. Buat clone repositori Demo DevRelGoogle Cloud .

   Download kode dan skrip infrastruktur dari GitHub. Gunakan sparse checkout untuk mengambil folder tertentu yang Anda perlukan untuk tutorial ini.

   # 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
   

Men-deploy data lake contoh di BigQuery

Lingkungan data di dunia nyata jarang sekali bersih. Agen AI dapat melakukan penalaran, tetapi mereka memulai dengan nol pengetahuan tentang perusahaan spesifik Anda. Bayangkan Anda bertanya kepada agen, "Berapa pendapatan Q1 kita?" Tanpa panduan, agen mungkin memilih dari puluhan tabel bernama "pendapatan" di database Anda, mulai dari laporan resmi hingga data pengujian mentah. Jika agen memilih tabel dengan nama yang terdengar paling mirip, agen dapat memberikan jawaban salah yang meyakinkan berdasarkan sumber yang belum diverifikasi.

Untuk menyimulasikan skenario ini, Anda memerlukan campuran data mart "resmi" dan tabel "sandbox" yang tidak tepercaya. Anda akan menggunakan skrip penyiapan untuk men-deploy set data dan tabel BigQuery.

Jadikan skrip penyiapan sebagai file yang dapat dieksekusi, lalu jalankan. Tindakan ini akan membuat tiga set data BigQuery (finance_mart, marketing_prod, analyst_sandbox) dan mengisi tabelnya dengan data sampel:

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

Sekarang Anda memiliki data lake yang terisi penuh, tetapi tidak diatur. Bagi agen AI, setiap tabel terlihat sama persis.

Menentukan jenis aspek kustom di Knowledge Catalog

Sekarang, Anda menentukan aturan tata kelola data Anda. Untuk melakukannya di Knowledge Catalog, Anda membuat jenis aspek, yang merupakan template metadata yang dapat digunakan kembali dan berjenis kuat.

Di bagian ini, Anda akan mendaftarkan template ini menggunakan gcloud CLI agar dapat melihat cara template ini ditentukan.

Memeriksa skema template aspek

Tampilkan konten aspect_template.json untuk melihat definisi skema:

cat aspect_template.json

Struktur JSON berikut akan ditampilkan:

{
  "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",
      "...": "..."
    }
  ]
}

Perhatikan bagaimana skema ini menerapkan jenis data yang ketat, seperti enum untuk tingkat kekritisan (GOLD_CRITICAL, SILVER_STANDARD, BRONZE_ADHOC) dan bool untuk is_certified. Hal ini memastikan metadata tetap terstruktur dan dapat dibaca mesin.

Mendaftarkan jenis aspek di Knowledge Catalog

Jalankan perintah gcloud berikut untuk mendaftarkan template ini di registry Knowledge Catalog Anda:

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"

Melampirkan aspek tata kelola ke tabel data lake

Ini adalah langkah rekayasa yang penting. Saat ini, tabel finance_mart.fin_monthly_closing_internal dan analyst_sandbox.tmp_data_dump_v2_final_real terlihat identik bagi agen AI. Tabel hanyalah objek dengan kolom.

Untuk membedakannya, Anda menerapkan aspek, yang melampirkan label metadata bersertifikasi ke tabel ini untuk membedakannya. Di perusahaan sungguhan, Anda akan mengotomatiskan proses ini dengan pipeline CI/CD. Dalam tutorial ini, Anda akan menyimulasikan otomatisasi tersebut dengan skrip.

Membuat payload metadata aspek

Kunci aspek Knowledge Catalog harus unik secara global (diawali dengan project ID Anda). Skrip ./generate_payloads.sh menghasilkan file metadata YAML secara dinamis:

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

Tindakan ini akan membuat direktori aspect_payloads/ yang berisi 4 file YAML yang menentukan berbagai skenario tata kelola data (fin_internal.yaml, fin_public.yaml, mkt_realtime.yaml, sandbox.yaml).

Melampirkan aspek ke tabel BigQuery

1. Sebelum menjalankan skrip, lihat data yang Anda lampirkan ke tabel. Jalankan perintah berikut untuk melihat metadata data keuangan internal Anda:

   cat aspect_payloads/fin_internal.yaml
   

   File YAML menentukan konteks bisnis untuk tabel:

   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
   

   Perhatikan bagaimana hal ini secara eksplisit menentukan konteks bisnis, seperti menetapkan is_certified: true dan menetapkan tingkat GOLD_CRITICAL. Hal ini memberi agen AI aturan yang jelas dan terstruktur untuk dievaluasi, bukan menebak berdasarkan nama tabel.

2. Jalankan skrip aplikasi. Skrip ini melakukan iterasi melalui tabel BigQuery Anda dan menggunakan perintah gcloud dataplex entries update untuk melampirkan payload metadata ke setiap tabel:

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

Memverifikasi aspek yang diterapkan di konsol Google Cloud

Sebelum melanjutkan, pastikan skrip menerapkan aspek dengan benar di konsol Google Cloud :

1. Buka halaman Knowledge Catalog di konsol Google Cloud . Anda dapat menggunakan kotak penelusuran di bagian atas untuk menemukannya.
2. Telusuri fin_monthly_closing_internal. Pilih nama tabel BigQuery di hasil untuk membuka halaman detailnya.
3. Di bagian Tag dan aspek opsional di bagian bawah, temukan aspek official-data-product-spec. Pastikan nilainya cocok dengan skenario "Gold Internal" yang Anda terapkan.

Anda kini telah mengonfirmasi bahwa tabel BigQuery yang secara teknis identik (fin_monthly_closing_internal dan tmp_data_dump_v2_final_real) dibedakan secara logis oleh metadata yang dapat dibaca mesin.

Menguji konteks data Anda dengan Antigravity CLI

Sebelum membangun aplikasi, Anda dapat memverifikasi logika tata kelola data secara lokal dengan Antigravity CLI. Untuk melakukannya, instal plugin Knowledge Catalog dan konfigurasikan keahlian agen.

Menginstal plugin Knowledge Catalog

Di Cloud Shell, instal plugin layanan:

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

Memeriksa definisi skill agen

Kemampuan agen adalah file definisi statis yang dapat digunakan kembali dan terletak di .agents/skills/knowledge-catalog-governance/SKILL.md. Agen ini berisi logika yang menerjemahkan aturan abstrak manusia seperti "Saya memerlukan data yang aman" menjadi pencarian teknis terstruktur.

Untuk memeriksa penyiapan skill dan memahami cara kerja konteks data, periksa file SKILL.md:

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

Perhatikan bahwa perintah ini menginstruksikan model untuk mengikuti loop ketat Fase 1 (Verifikasi Metadata) dan Fase 2 (Eksekusi Kueri). Model harus menemukan dan memverifikasi metadata sebelum membuat pernyataan SQL apa pun. Logika yang mengutamakan penelusuran ini mencegah agen menebak nama tabel atau memberikan jawaban yang tidak akurat dari sumber yang belum diverifikasi.

Memulai sesi Antigravity CLI

Mulai sesi CLI Antigravity. Karena Anda berada di folder project, CLI akan otomatis menemukan dan memuat skill dari direktori .agents/skills:

agy

Catatan: Anda mungkin melihat beberapa file konteks dimuat. Hal ini wajar. CLI akan memuat skill lokal untuk aturan spesifik project ini, ditambah petunjuk default untuk plugin layanan.

Memverifikasi penginstalan plugin di CLI

Di prompt Antigravity CLI, pastikan plugin aktif. Ketik /mcp untuk mencantumkan alat dan plugin yang dikonfigurasi:

/mcp

Output akan menampilkan knowledge-catalog yang tercantum sebagai plugin aktif dengan alat yang tersedia:

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

Menjalankan skenario verifikasi konteks data

Sekarang saatnya melihat konteks data Anda beraksi. Tempelkan perintah ini ke sesi CLI Antigravity satu per satu.

Tips: Jika diminta untuk mengizinkan penggunaan alat, pilih "2. Ya, dan selalu izinkan 'knowledge-catalog/search_entries' dalam percakapan ini" untuk pengujian tanpa harus menyetujui setiap langkah.

Skenario 1: Mengambil data tingkat gold bersertifikasi

Lihat apakah Antigravity CLI dapat menemukan data paling tepercaya untuk rapat direksi yang sangat penting:

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 akan melewati data mentah dan menemukan fin_monthly_closing_internal. Hal ini dilakukan dengan mencocokkan permintaan Anda untuk data "finalized" dan "confidential" dengan tag GOLD_CRITICAL dan INTERNAL_ONLY yang Anda terapkan sebelumnya.

Skenario 2: Membatasi pengambilan ke data yang disetujui secara eksternal

Anggaplah Anda ingin membagikan data secara eksternal. Anda ingin memastikan CLI tidak membocorkan rahasia internal:

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?

Meskipun tabel internal memiliki detail paling banyak, CLI harus mengabaikannya. Gemini akan mengarahkan Anda ke fin_quarterly_public_report karena ini satu-satunya tabel yang diberi tag sebagai EXTERNAL_READY.

Skenario 3: Mengambil data streaming real-time

Data scientist sering kali memerlukan info terbaru yang mutlak. Lihat apakah Antigravity CLI memahami perbedaan antara batch harian dan livestream:

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 akan menemukan mkt_realtime_campaign_performance. Kolom ini mengidentifikasi frekuensi update REALTIME_STREAMING dalam metadata.

Skenario 4: Mempelajari data sandbox yang tidak tersertifikasi

Terkadang, "cukup baik" lebih baik daripada "sempurna". Lihat apakah Antigravity CLI dapat menemukan data sandbox mentah untuk beberapa pekerjaan ML eksperimental:

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 akan menemukan tmp_data_dump_v2_final_real. GKE mengetahui bahwa ini adalah pilihan yang tepat karena cocok dengan paket BRONZE_ADHOC dan ditandai secara eksplisit dengan is_certified: false.

Setelah selesai menguji, Anda dapat keluar dari sesi CLI:

/quit

Pembersihan

Ikuti langkah-langkah berikut untuk menghindari tagihan berulang:

1. Jika Anda berada dalam sesi Antigravity CLI, keluar dari sesi dengan menekan Ctrl+C dua kali atau mengetik /quit.

2. Jalankan skrip pembersihan untuk menghapus tabel BigQuery, set data, dan jenis aspek Knowledge Catalog yang dibuat dalam tutorial ini:

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

3. Uninstal plugin layanan dan hapus file demo lokal Anda:

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

Langkah berikutnya

• Coba kasus penggunaan Knowledge Catalog lainnya.