Membangun produk data dengan kemampuan agen

Ringkasan

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

Cortex Framework menyediakan keahlian agen khusus untuk memperluas kemampuannya, sehingga asisten AI Anda dapat memandu Anda dalam proses membangun produk data 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 dibangun berdasarkan persyaratan dan data khusus pelanggan Anda—yang siap untuk dieksekusi.

Keahlian agen

Keahlian agen adalah format terbuka yang ringan untuk memperluas kemampuan agen AI dengan pengetahuan dan alur kerja khusus. Pada intinya, keahlian adalah folder yang berisi file SKILL.md (yang mencakup metadata dan petunjuk) beserta skrip, referensi, dan aset opsional yang menginstruksikan agen cara melakukan tugas tertentu. Keahlian mengemas pengetahuan dan konteks prosedural ke dalam folder portabel yang dimuat agen sesuai permintaan, sehingga memberikan keahlian domain dan alur kerja yang dapat diulang. Keahlian Cortex Framework disimpan di direktori .agent.

Keahlian agen Cortex Framework

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

Asisten AI mengelola tugas inti berikut:

  • Perencanaan dan pemetaan persyaratan: Menerjemahkan persyaratan bisnis konkret menjadi 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.
  • Quality gate 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 keterampilan agentic ini adalah proses yang berulang. Anda dapat memulai dengan sasaran awal, meninjau rencana implementasi yang diusulkan agen, termasuk diagram dan skema ER, serta meminta asisten AI untuk menyempurnakan logika secara percakapan seiring berjalannya waktu. Meskipun agen mempercepat pengembangan, Anda tetap memegang kendali penuh untuk meninjau dan menyetujui semua kode yang dihasilkan sebelum melakukan commit ke repositori Anda. Selain itu, karena skrip agentic ini dijalankan secara lokal menggunakan kredensial autentikasi Anda, skrip ini secara inheren mematuhi batas akses Google Cloud dan BigQuery yang ada.

Prasyarat

Sebelum menggunakan kemampuan agentic, 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): Konfigurasikan ADC lokal dan target project Anda agar alat kompilasi lokal dan suite pytest dapat berkomunikasi dengan BigQuery. Untuk mengetahui informasi selengkapnya, lihat menyiapkan project Google Cloud default Anda

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

    • DD03L (Kolom Tabel)
    • DD04T (Teks Elemen Data)
    • DD08L (Hubungan Tabel)
    • 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 baik. Untuk mengetahui informasi selengkapnya, lihat dokumentasi.

Penyiapan dan Konfigurasi IDE

Sebelum memulai, lihat dokumentasi bantuan 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 jejak kode sumber Google Cloud Cortex Framework yang di-clone dalam asisten coding AI yang Anda tentukan.

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

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

    Keterampilan 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 skill dari direktori .agents/skills/.
  • Alat CLI AI Lainnya: Referensi direktori keterampilan secara native dalam perintah instruksi Anda. Contoh:

    Read the create-data-product skill inside the .agents/skills/ directory and scaffold...


Membuat produk data kustom

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

Langkah 1: Berikan persyaratan dan konteks

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

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

Perhatikan bahwa Anda juga dapat merujuk ke 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 target konsumen.
  • 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 blok pembayaran (zlspr), dan aturan rekonsiliasi (misalnya, mengecualikan transaksi vendor antarperusahaan untuk menghindari tingkat perputaran yang tidak akurat).
  • Integritas data dan pernyataan pengujian: Skenario verifikasi (misalnya, memverifikasi keunikan perincian dan memastikan bahwa 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 keterampilan, seperti keterampilan 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 implementasi, agen akan memberikan rencana implementasi singkat untuk Anda tinjau. Rencana ini mencakup tabel sumber yang diidentifikasi, pemetaan, dan struktur arsitektur yang diusulkan untuk produk data. Tinjau rencana ini dan minta penyesuaian sebelum mengonfirmasi.

Langkah 3: Membuat produk data

Setelah Anda mengonfirmasi rencana implementasi, agen akan menggunakan kemampuan create-data-product untuk membuat struktur direktori. Tindakan ini akan mengisolasi pengembangan kustom baru Anda dari update platform inti di namespace kustom yang Anda tentukan:

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 setiap file, lihat dokumentasi Panduan Ekstensi.

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

Langkah 4: Jalankan quality gate dan verifikasi 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 uji yang memverifikasi logika bisnis inti dan pernyataan Anda.
  3. Linter dan audit: Memanfaatkan keterampilan validate-data-product untuk melakukan pemeriksaan paritas kolom yang ketat dan memverifikasi kepatuhan konvensi penamaan, yang diakhiri dengan laporan kesiapan yang mendetail.

Langkah 5: Deploy dan jalankan

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

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

Memperbarui produk data yang ada

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

Perbarui produk data AP 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 Anda selesai.

Agen akan menemukan konfigurasi, mengkueri DDIC BigQuery 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 membangun produk data yang sangat besar dan melibatkan puluhan tabel, agen mungkin kehilangan konteks. Tingkatkan 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 tindak lanjut yang terpisah).