Genkit Dart 1.0: GenkitRouter Gantikan startFlowServer, Apa yang Harus Diubah?

Genkit Dart 1.0.0 sudah stabil dan tersedia sebagai paket publik, dengan dua perubahan yang paling sering dibahas: penyajian HTTP pindah ke inti lewat GenkitRouter, dan startFlowServer digantikan oleh router itu. Selain itu, klien Flutter lama perlu memakai flag khusus agar tetap kompatibel. Bagi proyek Dart dan Flutter yang memakai Genkit untuk fitur AI, ini rilis yang menuntut penyesuaian kode, bukan sekadar menaikkan nomor versi.

TL;DR

• Genkit Dart mencapai versi stabil 1.0.0 dan tersedia di pub.dev.
• Penyajian HTTP dipindahkan ke inti, dengan GenkitRouter sebagai pengganti startFlowServer.
• Klien Flutter lama perlu flag khusus agar tetap kompatibel.
• Ada breaking change pada opsi pemanggilan prompt dan penambahan middleware generasi.
• Untuk proyek baru, mulai langsung dari pola GenkitRouter agar tidak menanggung utang migrasi.

Apa yang baru di Genkit Dart 1.0?

Yang paling menonjol adalah pembekuan API pada versi 1.0.0. Setelah versi stabil, perubahan besar berikutnya seharusnya mengikuti aturan versi mayor, jadi proyek yang mulai sekarang punya dasar yang lebih stabil untuk jangka panjang.

Perubahan kedua adalah pemindahan penyajian HTTP ke inti framework. Sebelumnya, menjalankan flow sebagai layanan HTTP memerlukan penanganan terpisah. Pada 1.0, fungsi itu masuk ke inti lewat GenkitRouter, sehingga cara mendefinisikan dan menyajikan flow menjadi lebih terpusat.

Perubahan ketiga menyentuh cara klien lama berkomunikasi. Menurut catatan rilis, klien Flutter versi lama memerlukan flag khusus agar tetap bekerja dengan server versi baru. Ini penting bagi tim yang mengupgrade sisi server lebih dulu daripada sisi aplikasi.

Apa itu GenkitRouter dan mengapa startFlowServer diganti?

GenkitRouter adalah komponen yang mengambil alih peran startFlowServer. Alih-alih memanggil fungsi penyaji terpisah, Anda mendefinisikan flow pada router, dan router itu yang mengurus penyajiannya. Penggantian ini menyatukan dua hal yang sebelumnya tersebar: definisi flow dan cara flow disajikan.

Alasannya masuk akal dari sisi desain. Kalau penyajian berada di inti, perilakunya bisa diseragamkan dan tidak bergantung pada paket tambahan. Bagi pemakai, konsekuensinya adalah kode yang memanggil startFlowServer harus diubah ke pola router.

Berikut perbedaan bentuk lama dan baru secara ringkas:

Aspek	Sebelum 1.0	Setelah 1.0
Cara menyajikan flow	startFlowServer	GenkitRouter
Letak penyajian HTTP	Di luar inti	Di dalam inti
Kompatibilitas klien lama	Otomatis	Perlu flag khusus
Opsi pemanggilan prompt	Posisional	Parameter bernama

Tabel di atas merangkum perubahan berdasarkan catatan rilis resmi. Rincian tanda tangan fungsi sebaiknya diperiksa langsung di dokumentasi paket sebelum menulis kode.

Apa saja breaking change yang perlu diperhatikan?

Ada dua yang disebut langsung di catatan rilis. Pertama, opsi pemanggilan prompt sekarang diambil sebagai parameter bernama, bukan posisional. Kalau kode Anda mengirim opsi secara berurutan, urutannya harus ditulis ulang memakai nama parameter. Kesalahan seperti ini biasanya muncul sebagai galat kompilasi, jadi cepat terdeteksi, tetapi menyentuh banyak tempat sekaligus.

Kedua, ada penambahan kemampuan mendefinisikan middleware untuk proses generasi. Ini bukan breaking change, melainkan fitur baru yang membuka cara menambahkan logika di sekitar pemanggilan model. Bagi proyek yang sudah punya kebutuhan pencatatan atau penyaringan, kemampuan ini bisa menggantikan lapisan pembungkus buatan sendiri.

Selain dua hal itu, perubahan terbesar tetap pada penggantian startFlowServer. Kode yang memanggil fungsi itu harus dipindahkan ke pola GenkitRouter. Karena ini perubahan pada titik masuk layanan, dampaknya bisa terasa di lebih dari satu berkas, tergantung bagaimana proyek Anda mengorganisasi alur.

Apakah klien Flutter lama masih bisa dipakai?

Bisa, tetapi memerlukan flag khusus. Menurut catatan rilis, klien Flutter versi lama perlu mengaktifkan flag itu agar tetap kompatibel dengan server versi baru. Tanpa flag, komunikasi bisa gagal meskipun kedua sisi tampak berjalan normal.

Implikasi praktisnya adalah urutan upgrade yang penting. Kalau Anda mengupgrade server lebih dulu sementara aplikasi masih memakai klien lama, pastikan flag itu sudah disiapkan sebelum merilis server. Mengabaikannya membuat aplikasi lama berhenti berfungsi tanpa pesan galat yang jelas.

Kalau memungkinkan, upgrade sisi aplikasi dan sisi server dalam jendela waktu yang berdekatan. Ini mengurangi masa transisi yang harus ditopang oleh flag kompatibilitas, dan mengurangi risiko lupa mencabut flag setelah semua klien diperbarui.

Bagaimana urutan migrasi yang aman?

Mulai dengan memastikan versi paket sudah dinaikkan dan proyek bisa dikompilasi. Setelah itu, ganti pemanggilan startFlowServer ke pola GenkitRouter, satu titik masuk pada satu waktu. Karena perubahan ini menyentuh penyajian layanan, mengerjakannya bertahap membuat setiap kegagalan mudah dilacak ke perubahan tertentu.

Langkah berikutnya adalah memperbaiki pemanggilan prompt yang masih memakai opsi posisional. Ubah ke parameter bernama sesuai catatan rilis, lalu jalankan tes yang menyentuh alur AI. Kalau proyek Anda punya tes untuk keluaran model, jalankan juga untuk memastikan perubahan bentuk pemanggilan tidak mengubah perilaku.

Terakhir, siapkan flag kompatibilitas untuk klien lama sebelum merilis server. Setelah semua klien diperbarui, baru cabut flag itu agar kode tidak menyimpan jalur lama yang tidak lagi dipakai. Menyimpan jalur kompatibilitas terlalu lama membuat kode sulit dibaca dan menyembunyikan asumsi yang sudah basi.

Kapan sebaiknya upgrade ke 1.0?

Upgrade setelah versi stabil dirilis, dan itu sudah terjadi untuk 1.0.0. Karena API-nya kini dibekukan, waktu yang tepat adalah saat Anda punya jendela untuk menyentuh kode penyajian layanan. Menunda terlalu lama membuat jarak perubahan makin besar dan biaya migrasinya naik.

Untuk proyek baru, tidak ada alasan memakai pola lama. Mulai langsung dari GenkitRouter dan parameter bernama, supaya tidak menanggung utang migrasi sejak awal. Memilih pola lama pada proyek baru hanya memindahkan pekerjaan ke masa depan tanpa manfaat.

Untuk proyek yang sedang dalam periode rilis, tunda migrasi sampai periode itu selesai. Mengganti cara penyajian layanan di tengah periode sibuk menambah risiko tanpa manfaat langsung. Catat saja pekerjaan itu sebagai tugas terjadwal agar tidak terlupa.

Apa dampaknya buat proyek Flutter yang sudah jalan?

Dampak utamanya ada pada dua tempat: titik masuk layanan dan pemanggilan prompt. Kalau proyek Anda memakai startFlowServer, kode itu perlu diubah. Kalau proyek Anda memanggil prompt dengan opsi posisional, pemanggilan itu perlu disesuaikan ke parameter bernama.

Selain dua tempat itu, perubahan lainnya lebih ringan. Penambahan middleware bersifat opsional, jadi proyek yang tidak membutuhkannya bisa mengabaikannya. Yang perlu dijaga adalah memastikan versi paket di seluruh paket kerja (workspace) tetap seragam, karena campuran versi bisa menimbulkan kegagalan yang membingungkan.

Untuk tim, langkah paling berguna adalah menulis catatan migrasi internal. Cukup berisi tiga hal: apa yang diganti, di berkas mana, dan bagaimana cara mengujinya. Catatan itu menghemat waktu ketika anggota lain menyentuh bagian yang sama beberapa bulan kemudian.

Apakah 1.0 berarti API tidak akan berubah lagi?

Bukan berarti beku selamanya, tetapi ada jaminan yang lebih kuat dibanding versi pra-1.0. Setelah versi mayor 1.0, perubahan yang merusak kompatibilitas seharusnya menunggu versi mayor berikutnya, bukan muncul di rilis minor. Ini memberi dasar yang lebih dapat diandalkan untuk proyek jangka panjang.

Meski begitu, tetap ada ruang untuk penambahan fitur dan perbaikan perilaku di rilis minor. Jadi kunci versi di berkas dependensi tetap praktik yang baik, dan jangan mengasumsikan perilaku detail akan identik selamanya.

Praktik yang aman: kunci versi mayor, jalankan tes setelah setiap pembaruan minor, dan baca catatan rilis sebelum menaikkan versi. Tiga kebiasaan itu menutup sebagian besar kejutan yang biasanya muncul dari pembaruan paket.

Apakah middleware generasi perlu langsung dipakai?

Tidak perlu. Middleware generasi adalah kemampuan tambahan yang berguna kalau Anda butuh menambahkan logika di sekitar pemanggilan model, misalnya pencatatan atau penyaringan. Kalau kebutuhan itu belum ada, melewatkannya tidak menghambat migrasi ke 1.0. Menambahkan lapisan yang belum dibutuhkan hanya menambah kode yang harus dirawat.

Kesalahan apa yang paling sering terjadi saat migrasi?

Kesalahan pertama adalah mengupgrade paket tetapi lupa mengganti pemanggilan startFlowServer, sehingga layanan gagal dijalankan meski kode lain tampak benar. Kesalahan kedua adalah memperbarui server tanpa menyiapkan flag untuk klien lama, sehingga aplikasi yang belum diperbarui berhenti berfungsi. Kesalahan ketiga adalah mencampur versi paket di dalam satu ruang kerja, yang membuat penyebab kegagalan sulit dilacak.

Ketiganya bisa dihindari dengan urutan yang disiplin: naikkan versi, ganti titik masuk, perbaiki pemanggilan prompt, siapkan flag kompatibilitas, jalankan tes, lalu cabut flag setelah semua klien diperbarui. Urutan ini tidak rumit, tetapi melewatkan satu langkah biasanya berujung pada kegagalan yang memakan waktu lebih lama untuk ditelusuri.

Apakah perlu mengubah kode aplikasi, bukan hanya kode server?

Perlu, tetapi cakupannya tergantung pemakaian. Kalau aplikasi hanya memanggil endpoint dan tidak menyentuh detail penyajian flow, perubahan bisa terbatas pada penyesuaian flag kompatibilitas. Kalau aplikasi ikut mendefinisikan flow atau memanggil prompt dengan opsi posisional, maka ada penyesuaian di sisi itu juga.

Cara cepat memetakannya: cari pemakaian startFlowServer dan pemanggilan prompt di seluruh repositori, lalu tandai mana yang berada di sisi server dan mana yang di sisi klien. Dari daftar itu, Anda bisa memperkirakan besar pekerjaan sebelum mulai mengubah kode.

FAQ

Apakah Genkit Dart 1.0 sudah stabil?

Ya. Versi 1.0.0 sudah tersedia sebagai paket stabil di pub.dev, dan pengumumannya dirilis di kanal resmi Genkit, Dart, serta Flutter.

Apa pengganti startFlowServer?

GenkitRouter. Penyajian HTTP dipindahkan ke inti framework, dan router itu yang mengambil alih peran startFlowServer pada versi sebelumnya.

Apakah klien Flutter lama masih jalan?

Masih bisa, tetapi memerlukan flag khusus sesuai catatan rilis. Tanpa flag itu, komunikasi dengan server versi baru bisa gagal meski kedua sisi tampak berjalan.

Apa breaking change terbesarnya?

Penggantian startFlowServer ke GenkitRouter, ditambah perubahan opsi pemanggilan prompt dari posisional menjadi parameter bernama.

Apakah proyek baru sebaiknya memakai pola lama?

Tidak. Proyek baru sebaiknya langsung memakai GenkitRouter dan parameter bernama, agar tidak menanggung utang migrasi sejak awal.

Sumber

• Pengumuman resmi: Announcing Genkit Dart 1.0 (genkit.dev).
• Catatan versi paket: genkit package di pub.dev (pub.dev).
• Blog Dart: Announcing Genkit Dart 1.0 (dart.dev).
• Repositori: firebase/genkit di GitHub (github.com).