Menggunakan Antigravity CLI untuk menguji konteks data

Agen AI dapat berpikir, tetapi mereka memulai dengan pengetahuan nol 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 yang tidak rapi. Jika agen memilih tabel dengan nama yang paling mirip, agen dapat menampilkan 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 bersertifikat.

Tujuan

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

Sebelum memulai

Sebelum memulai, pastikan Anda melakukan hal berikut:

• Pilih Google Cloud project untuk tutorial ini.
• Pastikan 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) telah diinstal sebelumnya 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 sehingga semua perintah mendatang menargetkan project spesifik Google Cloud Anda.

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

3. Aktifkan layanan yang diperlukan 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. Clone repositori Google Cloud DevRel Demos.

   Download kode dan skrip infrastruktur dari GitHub. Gunakan checkout jarang untuk menarik hanya folder spesifik 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
   

Membuat contoh data lake

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

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 contoh data:

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

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

Membuat template tata kelola data (jenis aspek)

Sekarang, Anda akan menentukan aturan tata kelola data. Untuk melakukannya di Knowledge Catalog, Anda akan 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 sehingga Anda dapat melihat cara template ini ditentukan.

Memeriksa skema aspek

Outputkan konten aspect_template.json untuk melihat definisi skema:

cat aspect_template.json

Skema ini akan menampilkan struktur JSON berikut:

{
  "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

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"

Menerapkan tata kelola data

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. Tabel tersebut hanyalah objek dengan kolom.

Untuk membedakannya, Anda akan menerapkan aspek, yang melampirkan label metadata bersertifikat ke tabel ini untuk membedakannya. Di perusahaan yang sebenarnya, Anda akan mengotomatiskan hal ini dengan pipeline CI/CD. Dalam tutorial ini, Anda akan mensimulasikan otomatisasi tersebut dengan skrip.

Membuat payload tata kelola data

Kunci aspek Knowledge Catalog harus unik secara global (diawali dengan project ID Anda). Skrip ./generate_payloads.sh akan 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 skenario tata kelola data yang berbeda (fin_internal.yaml, fin_public.yaml, mkt_realtime.yaml, sandbox.yaml).

Menerapkan aspek menggunakan CLI

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 file ini secara eksplisit menentukan konteks bisnis, seperti menetapkan is_certified: true dan menetapkan tingkat GOLD_CRITICAL. Hal ini memberikan aturan yang jelas dan terstruktur kepada agen AI untuk dievaluasi, bukan menebak berdasarkan nama tabel.

2. Jalankan skrip aplikasi. Skrip ini akan 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 metadata

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

1. Buka halaman Knowledge Catalog di Google Cloud konsol. 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 Optional tags and aspects di bagian bawah, temukan aspek official-data-product-spec. Pastikan nilai 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 oleh mesin.

Menguji konteks data Anda dengan Antigravity CLI

Sebelum membuat aplikasi, Anda dapat memverifikasi logika tata kelola data secara lokal dengan Antigravity CLI. Untuk melakukannya, Anda akan menginstal plugin Knowledge Catalog dan mengonfigurasi kemampuan agen.

Menginstal plugin layanan

Di Cloud Shell, instal plugin layanan:

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

Memeriksa kemampuan agen

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

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

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

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

Memulai Antigravity CLI dan menguji skenario

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

agy

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

Memverifikasi penginstalan

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

Cobalah

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

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

Skenario 1: Menemukan data standar "Gold"

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

Skenario 2: Pengungkapan publik

Anggap Anda ingin membagikan data secara eksternal. Anda ingin memastikan CLI tidak membocorkan rahasia internal apa pun:

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 terbanyak, CLI harus melewatinya. CLI harus mengarahkan Anda ke fin_quarterly_public_report karena tabel tersebut adalah satu-satunya tabel yang diberi tag EXTERNAL_READY.

Skenario 3: Kebutuhan operasional real-time

Data scientist 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 harus menemukan mkt_realtime_campaign_performance. CLI mengidentifikasi frekuensi update REALTIME_STREAMING dalam metadata.

Skenario 4: Eksplorasi sandbox

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 harus menemukan tmp_data_dump_v2_final_real. CLI 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 menghancurkan 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. Hapus instalasi plugin layanan dan hapus file demo lokal Anda:

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

Kesimpulan

Anda telah membangun dasar data yang solid, menerapkan konteks yang ketat menggunakan metadata, dan memverifikasi bahwa semuanya berfungsi secara lokal menggunakan Antigravity CLI.

Langkah berikutnya

• Coba kasus penggunaan Knowledge Catalog lainnya.