Membangun produk data dengan kemampuan agen

Panduan ini menjelaskan cara menggunakan kemampuan agen Cortex Framework khusus—yang disediakan langsung di repositori GitHub—dengan asisten coding AI (seperti Gemini yang dipasangkan dengan framework pengembangan agen Antigravity) untuk membangun produk data kustom yang mengikuti praktik terbaik Cortex Framework.

Dengan kemampuan ini, Anda dapat menggunakan bahasa alami untuk meminta produk data baru berdasarkan persyaratan bisnis tertentu. Misalnya, Anda dapat meminta produk data konsumsi Utang Usaha untuk mendapatkan insight tentang total jatuh tempo, jumlah jatuh tempo, dan perputaran. Hasilnya adalah produk data Cortex Framework yang terintegrasi sepenuhnya—yang dibuat berdasarkan persyaratan dan data khusus pelanggan Anda—yang siap untuk dieksekusi.

Ringkasan

Builder produk data agen mengotomatiskan siklus proses pengembangan produk data end-to-end dalam Cortex Framework. Dengan menginstruksikan asisten AI untuk menjalankan alur kerja pengembangan terstruktur, Anda tidak perlu membuat struktur file secara manual, menavigasi skema SAP yang kompleks, mengonfigurasi lapisan dasar, mengelola namespace kustom, dan menulis kode Dataform SQLX boilerplate.

Asisten AI mengelola tugas inti berikut:

  • Pemetaan perencanaan dan persyaratan: Menerjemahkan persyaratan bisnis konkret ke dalam rencana pengembangan dan pemodelan data yang dapat ditindaklanjuti.
  • Pencarian skema langsung: Menjalankan skrip yang mengkueri tabel SAP Data Dictionary (DDIC) yang direplikasi untuk memberikan informasi konteks khusus pelanggan, seperti kolom Z kustom.
  • Scaffolding boilerplate: Membuat semua file konfigurasi, metadata, dan artefak kode SQLX atau JavaScript yang diperlukan secara otomatis.
  • Gerbang kualitas data: Memvalidasi produk data dengan menjalankan build lokal, mengompilasi kode SQL, menjalankan pengujian unit dan integrasi, serta memverifikasi kepatuhan terhadap standar penamaan.
  • Pembuatan dokumentasi: Membuat aset dokumentasi secara otomatis, termasuk memvisualisasikan diagram hubungan entitas (ER) dan kunci utama modul produk data Anda.

Mengembangkan produk data dengan kemampuan agen ini adalah proses iteratif. Anda dapat memulai dengan sasaran awal, meninjau rencana penerapan yang diusulkan agen termasuk diagram dan skema ER, dan meminta asisten AI untuk menyempurnakan logika secara percakapan saat Anda melanjutkan. Meskipun agen mempercepat pengembangan, Anda tetap memiliki kontrol penuh untuk meninjau dan menyetujui semua kode yang dihasilkan sebelum melakukan commit ke repositori Anda. Selain itu, karena skrip agen ini dijalankan secara lokal menggunakan kredensial yang diautentikasi, skrip ini secara inheren mematuhi batas akses Google Cloud dan BigQuery yang ada.

Prasyarat

Sebelum menggunakan kemampuan agen, pastikan lingkungan pengembangan Anda memenuhi persyaratan berikut untuk mengaktifkan kueri skema langsung, kompilasi data, dan validasi otomatis:

  1. Google Cloud SDK (gcloud): Instal dan autentikasi CLI (gcloud) dengan akun pengguna Anda. Untuk mengetahui informasi selengkapnya, lihat dokumentasi deployment

  2. Kredensial Default Aplikasi (ADC): Konfigurasi ADC lokal dan target project Anda sehingga alat kompilasi lokal dan rangkaian pytest dapat berkomunikasi dengan BigQuery. Untuk mengetahui informasi selengkapnya, lihat menyiapkan default Google Cloud project

  3. Tabel SAP Data Dictionary (DDIC) yang Direplikasi: Untuk mengizinkan agen melakukan pemeriksaan skema yang tidak peka huruf besar/kecil dan memverifikasi panjang kolom secara akurat, replikasi tabel metadata SAP berikut dalam set data BigQuery target mentah Anda:

    • DD03L (Kolom Tabel)
    • DD04T (Teks Elemen Data)
    • DD08L (Hubungan Antartabel)
    • DD01L (Domain)
    • DD07L (Nilai Domain - opsional)
    • DD07T (Teks Nilai Domain - opsional)

  4. Lingkungan Python Lokal: Instal dependensi lokal dan jalankan alat sinkronisasi menggunakan uv untuk memastikan library validasi dan pengujian unit berfungsi dengan benar. Untuk mengetahui informasi selengkapnya, lihat dokumentasi.

Penyiapan dan Konfigurasi IDE

Sebelum memulai, lihat dokumentasi asisten coding AI pilihan Anda untuk mengetahui petunjuk penginstalan dan penyiapan (misalnya, Antigravity).

  1. Kumpulkan artefak penginstalan yang diperlukan dan clone repositori. Untuk mengetahui informasi selengkapnya, lihat Artefak Penginstalan.

  2. Buka footprint kode sumber Google Cloud Cortex Framework yang di-clone dalam asisten coding AI yang ditentukan.

Google Cloud Cortex Framework mengekspos kemampuan agennya melalui serangkaian kemampuan khusus yang terletak di direktori .agents/skills/ repositori. Anda dapat menggunakan kemampuan ini di beberapa lingkungan pengembangan:

  • Framework Antigravity: Antigravity otomatis menemukan, mengindeks, dan mengaktifkan semua kemampuan ruang kerja saat startup. Tidak diperlukan konfigurasi tambahan. Untuk memverifikasi, tanyakan kepada asisten:

    "Kemampuan apa yang Anda miliki?"

  • VSCode dengan Gemini Code Assist:

    1. Instal ekstensi Gemini Code Assist dari VS Code Marketplace.
    2. Buka folder cortex-framework-core sebagai ruang kerja. Asisten akan otomatis memindai dan memuat kemampuan dari direktori .agents/skills/.

  • **Alat CLI AI Lainnya **: Referensikan direktori kemampuan secara native dalam perintah instruksi Anda. Misalnya, > "Baca kemampuan create-data-product di dalam direktori .agents/skills/ dan buat scaffolding...".

Membuat produk data kustom

Langkah-langkah berikut menguraikan alur kerja developer terstruktur untuk menggunakan kemampuan agen guna membuat produk data kustom.

Langkah 1: Langkah 1: Memberikan persyaratan dan konteks

Menggunakan antarmuka chat asisten coding AI Anda, berikan perintah yang menjelaskan persyaratan data spesifik Anda. Contoh:

Buat produk data Cortex Framework untuk Insight Utang Usaha yang ditargetkan untuk SAP S/4HANA dan ECC. Gunakan namespace: custom_finance. Persyaratan bisnis utama adalah melacak total jatuh tempo dan jumlah jatuh tempo di seluruh vendor kami, serta menghitung rasio perputaran utang usaha kami berdasarkan kode perusahaan.

Perhatikan bahwa Anda juga dapat mereferensikan dokumen persyaratan atau spesifikasi yang ada langsung dalam perintah Anda. Dokumen ini (yang dapat berupa Markdown atau format terstruktur lainnya) memberikan konteks penting kepada agen, seperti:

  • Konteks dan domain bisnis: Tujuan mendetail, cerita pengguna, dan konsumen target.
  • Spesifikasi data input: Daftar tabel sumber (misalnya, LFA1, BSIK, BSEG ,Z...), detail pembuatan versi (ECC versus S/4HANA), aturan pengecualian, kolom kustom, dan lainnya.
  • Logika transformasi dan aturan bisnis: Batasan pemetaan inti, pemfilteran klien (mandt), penghapusan sementara (loekz), penanganan pemetaan indikator blokir pembayaran (zlspr), dan aturan rekonsiliasi (misalnya, mengecualikan transaksi vendor antarkelompok untuk menghindari rasio perputaran yang tidak akurat).
  • Integritas data dan pernyataan pengujian: Skenario verifikasi (misalnya, memverifikasi keunikan butir dan memastikan bahwa jumlah jumlah invoice yang belum dibayar dalam output akhir sama persis dengan tabel sumber mentah).

Langkah 2: Meninjau rencana penerapan

Setelah Anda menguraikan persyaratan, agen akan menggunakan beberapa kemampuan—seperti kemampuan query-sap-ddic untuk mengkueri tabel metadata DDIC BigQuery mentah Anda. Hal ini memungkinkan agen mengidentifikasi dan memvalidasi tabel sumber yang diperlukan, sehingga memastikan jenis dan hubungan kolom akurat. Agen juga dapat memanggil kemampuan lain untuk memastikan persyaratan Anda selaras dengan praktik terbaik Cortex Framework.

Sebelum memulai penerapan, agen akan memberikan rencana penerapan singkat untuk Anda tinjau. Rencana ini mencakup tabel sumber, pemetaan, dan struktur arsitektur produk data yang diidentifikasi. Tinjau rencana ini dan minta penyesuaian apa pun sebelum mengonfirmasi.

Langkah 3: Membuat produk data

Setelah Anda mengonfirmasi rencana penerapan, agen akan menggunakan kemampuan create-data-product untuk membuat scaffolding struktur direktori. Hal ini mengisolasi pengembangan kustom baru Anda dari update platform inti di bawah namespace kustom yang ditentukan:

src/data_modules/<custom_namespace>/products/<dataproductname>/
├── manifest.yaml
├── table_settings.default.yaml
├── README.md
├── definitions/
│   └── [ecc|s4]/
│       └── <product_name>.js
└── annotations/
    └── [ecc|s4]/
        └── <product_name>.yaml

Untuk mengetahui informasi selengkapnya tentang struktur folder dan file individual, lihat dokumentasi Panduan Ekstensibilitas.

Selama fase ini, Anda juga dapat meminta agen untuk memvisualisasikan hubungan secara otomatis menggunakan kemampuan generate-er-diagram, atau membuat scaffolding pernyataan menggunakan kemampuan create-python-tests.

Langkah 4: Menjalankan gerbang kualitas dan memverifikasi data

Bergantung pada izin yang diberikan, agen akan otomatis menjalankan gerbang validasi wajib berikut atau meminta Anda untuk menjalankannya. Selama proses ini, agen akan membuat laporan status terperinci sehingga Anda dapat meninjau hasilnya:

  1. Validasi build: Menjalankan uv run cortex-build --config config/config.yaml untuk memastikan semua model SQL yang dihasilkan berhasil dikompilasi, sehingga menghasilkan ringkasan build.
  2. Eksekusi Pytest: Menjalankan rangkaian lengkap pengujian unit Python, yang menghasilkan laporan eksekusi pengujian yang memverifikasi logika dan pernyataan bisnis inti Anda.
  3. Linter dan audit: Memanfaatkan kemampuan validate-data-product untuk melakukan pemeriksaan paritas kolom yang ketat dan memverifikasi kepatuhan konvensi penamaan, yang diakhiri dengan laporan kesiapan mendetail.

Langkah 5: Men-deploy dan menjalankan

Setelah meninjau laporan validasi dan menyetujui kode yang dihasilkan, Anda siap men-deploy aset produk data.

  • Men-deploy aset: Kirim definisi produk data yang dikompilasi ke ruang kerja Dataform yang dikonfigurasi dengan menjalankan skrip deployment secara lokal (misalnya, uv run cortex-deploy --config config/config.yaml).
  • Mewujudkan data: Selesaikan alur kerja pasca-deployment akhir untuk menjalankan pipeline Dataform yang dihasilkan, mewujudkan tabel dan tampilan baru Anda langsung di BigQuery.
  • Memberikan insight: Setelah diwujudkan, produk data kustom Anda sepenuhnya siap untuk terhubung ke aplikasi analisis hilir—seperti Gemini Enterprise—untuk memberikan jawaban cerdas dan dapat ditindaklanjuti atas pertanyaan bisnis asli Anda.

Memperbarui produk data yang ada

Setelah produk data kustom Anda dibuat, Anda tidak perlu memulai dari awal untuk melakukan perubahan. Anda dapat memanfaatkan kemampuan update-data-product untuk menambahkan kolom baru secara iteratif, menyesuaikan logika bisnis, atau mengintegrasikan tabel sumber yang benar-benar baru. Contoh:

Perbarui produk data utang usaha custom_finance saya. Tambahkan kolom persyaratan pembayaran (ZTERM) dari tabel sumber LFA1, dan pastikan kolom tersebut dipetakan dengan benar ke tampilan output akhir. Jalankan validasi build setelah selesai.

Agen akan menemukan konfigurasi, mengkueri BigQuery DDIC untuk persyaratan kolom yang tepat, memperbarui kode Dataform Anda, dan menjalankan pemeriksaan build yang diperlukan untuk memverifikasi perubahan.

Praktik terbaik dan batasan

  • Kegagalan kueri skema: Jika agen gagal mengambil skema metadata SAP, pastikan Kredensial Default Aplikasi (ADC) lokal Anda aktif dan memiliki peran IAM BigQuery Data Viewer untuk set data mentah target.
  • Batas konteks: Jika Anda membuat produk data yang sangat besar yang melibatkan puluhan tabel, agen mungkin akan kehilangan konteks. Perluas rasio keberhasilan Anda dengan memberikan petunjuk yang lebih kecil dan atomik (misalnya, instruksikan agen untuk membuat dimensi tingkat header terlebih dahulu, lalu tambahkan fakta tingkat item dalam perintah lanjutan yang terpisah).