Membangun produk data dengan keterampilan agen

Ringkasan

Panduan ini menjelaskan cara menggunakan kemampuan agen khusus Cortex Framework yang disediakan langsung oleh Cortex Framework 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.

Cortex Framework menyediakan keahlian agen khusus untuk memperluas kemampuannya, sehingga asisten AI Anda dapat memandu Anda melalui proses pembuatan 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 penggunaan Utang Usaha untuk mendapatkan insight tentang total tagihan, jumlah tagihan yang telah melewati tanggal jatuh tempo, dan perputaran. Hasilnya adalah produk data Cortex Framework yang terintegrasi sepenuhnya—yang dibuat berdasarkan persyaratan dan data khusus pelanggan Anda—yang siap dieksekusi.

Keahlian agen

Keahlian agen adalah format terbuka yang ringan untuk memperluas kemampuan agen AI dengan pengetahuan dan alur kerja khusus. Pada intinya, skill 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. Paket keterampilan mengemas pengetahuan dan konteks prosedural ke dalam folder portabel yang dimuat agen sesuai permintaan, sehingga memberikan keahlian domain dan alur kerja yang dapat diulang. Keterampilan Cortex Framework disimpan di direktori .agent.

Keahlian agen Cortex Framework

Pembangun 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 lagi membuat struktur file secara manual, menjelajahi skema SAP yang kompleks, mengonfigurasi lapisan dasar, mengelola namespace kustom, dan menulis kode SQLX Dataform boilerplate.

Asisten AI mengelola tugas inti berikut:

  • Pemetaan perencanaan dan persyaratan: Menerjemahkan persyaratan bisnis yang 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 keterampilan agentic ini adalah proses iteratif. 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 saat Anda melakukannya. 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 berbasis agen ini dijalankan secara lokal menggunakan kredensial terautentikasi Anda, skrip ini secara inheren mematuhi batas akses Google Cloud dan BigQuery yang ada.

Prasyarat

Sebelum menggunakan kemampuan agentik, 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 pengujian pytest dapat berkomunikasi dengan BigQuery. Untuk mengetahui informasi selengkapnya, lihat menyiapkan project Google Cloud default Anda

  3. Tabel Kamus Data (DDIC) SAP 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 benar. Untuk mengetahui informasi selengkapnya, lihat dokumentasi.

Penyiapan dan Konfigurasi IDE

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

Google Cloud Cortex Framework mengekspos kemampuan agentic-nya melalui serangkaian keterampilan khusus yang berada 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 startup. Tidak diperlukan konfigurasi tambahan. Untuk memverifikasi, tanyakan kepada asisten:

    Keahlian 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 petunjuk Anda. Contoh:

    Baca keterampilan create-data-product di dalam direktori .agents/skills/ dan buat struktur...

Membuat produk data kustom

Langkah-langkah berikut menguraikan alur kerja developer terstruktur untuk menggunakan kemampuan berbasis 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:

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

Perhatikan bahwa Anda juga dapat merujuk persyaratan atau dokumen spesifikasi yang ada secara 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 yang mendetail, skenario 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 pemblokiran pembayaran (zlspr), dan aturan rekonsiliasi (misalnya, mengecualikan transaksi vendor antarperusahaan untuk menghindari rasio omzet yang miring).
  • Integritas data dan pernyataan pengujian: Skenario verifikasi (misalnya, memverifikasi keunikan perincian dan memastikan bahwa jumlah nilai invoice yang belum dibayar dalam output akhir sama persis dengan tabel sumber mentah).

Langkah 2: Tinjau rencana penerapan

Setelah Anda menguraikan persyaratan, agen akan menggunakan beberapa keterampilan, seperti keterampilan query-sap-ddic untuk membuat kueri pada tabel metadata DDIC BigQuery mentah Anda. Dengan demikian, agen dapat mengidentifikasi dan memvalidasi tabel sumber yang diperlukan, sehingga memastikan jenis dan hubungan kolom akurat. Agen juga dapat memanggil keterampilan lain untuk memastikan persyaratan Anda selaras sempurna dengan praktik terbaik Cortex Framework.

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

Langkah 3: Buat produk data

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

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 Ekstensibilitas.

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

Langkah 4: Jalankan gerbang kualitas 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: Mengeksekusi 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 kesamaan kolom yang ketat dan memverifikasi kepatuhan terhadap 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.

  • 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 terwujud, produk data kustom Anda sepenuhnya siap dihubungkan ke aplikasi analisis hilir—seperti Gemini Enterprise—untuk memberikan jawaban 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 kemampuan update-data-product untuk menambahkan kolom baru secara berulang, menyesuaikan logika bisnis, atau mengintegrasikan tabel sumber yang benar-benar baru. Contoh:

Perbarui produk data custom_finance AP 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, membuat kueri DDIC BigQuery untuk mengetahui 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.
  • Batasan konteks: Jika Anda membuat produk data yang sangat besar yang melibatkan puluhan tabel, agen mungkin kehilangan konteks. Perluas tingkat keberhasilan Anda dengan memberikan petunjuk atomik yang lebih kecil (misalnya, instruksikan agen untuk membuat dimensi tingkat header terlebih dahulu, lalu tambahkan fakta tingkat item dalam perintah lanjutan yang terpisah).