Menggunakan Antigravity CLI untuk menguji konteks data

Agen AI dapat menalar, tetapi mereka memulai dengan nol pengetahuan tentang perusahaan spesifik Anda. Bayangkan Anda bertanya kepada agen, "Berapa pendapatan kita pada kuartal 1?" Tanpa panduan, agen mungkin memilih dari lusinan tabel bernama "pendapatan" di database Anda, mulai dari laporan resmi hingga data pengujian yang tidak teratur. Jika agen memilih tabel dengan nama yang terdengar paling mirip, agen dapat memberikan jawaban yang salah dan meyakinkan berdasarkan sumber yang tidak terverifikasi.

Pengayaan metadata adalah solusi untuk masalah konteks ini. Dalam tutorial ini, Anda akan menyiapkan aspek yang memberikan konteks ini, dan menggunakan Antigravity CLI untuk menguji konteks data dan memverifikasi bahwa agen dapat secara akurat mendasarkan jawabannya pada data tepercaya dan bersertifikasi.

Tujuan

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

Sebelum memulai

Sebelum memulai, pastikan Anda melakukan hal berikut:

• Pilih Google Cloud project 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 di Google Cloud Shell.

1. Dari Google Cloud konsol, 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 agar 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 Google Cloud repositori Demo DevRel.

   Download kode dan skrip infrastruktur dari GitHub. Gunakan checkout jarang untuk menarik hanya folder tertentu yang Anda butuhkan 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 sampel di BigQuery

Lingkungan data dunia nyata jarang sekali bersih. Untuk menyimulasikan realitas, Anda memerlukan gabungan tabel "sandbox" yang tidak tepercaya dan data mart "resmi".

Anda menggunakan skrip penyiapan untuk men-deploy set data dan tabel BigQuery.

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

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

Sekarang Anda memiliki data lake yang terisi sepenuhnya, 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 memiliki jenis yang kuat.

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

Periksa skema template aspek

Output 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 oleh 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 engineering 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. Objek ini hanyalah objek dengan kolom.

Untuk membedakannya, Anda menerapkan aspek, yang melampirkan label metadata bersertifikasi ke tabel ini untuk membedakannya. Di perusahaan yang sebenarnya, Anda akan mengotomatiskan hal 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 membuat 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 menyetel is_certified: true dan menetapkan tingkat GOLD_CRITICAL. Dengan demikian, agen AI memiliki 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, periksa apakah skrip menerapkan aspek dengan benar di konsol Google Cloud :

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

Sekarang Anda telah mengonfirmasi bahwa tabel BigQuery yang identik secara teknis (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, Anda menginstal plugin Knowledge Catalog dan mengonfigurasi kemampuan 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

Keahlian agen adalah file definisi statis yang dapat digunakan kembali dan terletak di .agents/skills/knowledge-catalog-governance/SKILL.md. Bagian 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 menyusun pernyataan SQL apa pun. Logika mengutamakan penelusuran ini mencegah agen menebak nama tabel atau berhalusinasi jawaban dari sumber yang tidak terverifikasi.

Mulai 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 memuat skill lokal untuk aturan khusus project ini, ditambah petunjuk default untuk plugin layanan.

Memverifikasi penginstalan plugin di CLI

Di perintah 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. Tempel perintah ini ke sesi Antigravity CLI 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 emas bersertifikasi

Lihat apakah Antigravity CLI dapat menemukan data yang paling tepercaya untuk rapat dewan yang 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 "final" dan "rahasia" dengan tag GOLD_CRITICAL dan INTERNAL_ONLY yang Anda terapkan sebelumnya.

Skenario 2: Membatasi pengambilan data yang disetujui secara eksternal

Berpura-puralah Anda ingin membagikan data secara eksternal. Anda ingin memastikan CLI tidak membiarkan rahasia internal apa pun bocor:

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 melewatinya. Anda akan diarahkan ke fin_quarterly_public_report karena ini adalah satu-satunya tabel yang diberi tag EXTERNAL_READY.

Skenario 3: Mengambil data streaming real-time

Ilmuwan data sering kali memerlukan info terbaru. 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: Menjelajahi data sandbox yang tidak bersertifikasi

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. Google mengetahui bahwa ini adalah pilihan yang tepat karena cocok dengan tingkat 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 biaya 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, set data, dan jenis aspek Knowledge Catalog BigQuery 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.