1. Pengantar
Dalam codelab ini, Anda akan menambahkan widget chat dukungan pelanggan pintar ke toko e-commerce perlengkapan outdoor bernama Rugged Terrain Guide. Anda akan menggunakan Firebase AI Logic untuk membuat agen ini, dan Anda akan mempelajari cara mengonfigurasi template perintah sisi server (product-agent) yang menangani persona AI, aturan anggaran kompensasi yang ketat, dan menggunakan katalog produk secara dinamis sebagai konteks.
Yang akan Anda lakukan:
- Dapatkan kode awal untuk aplikasi web codelab ini.
- Siapkan project Firebase.
- Siapkan dan lakukan inisialisasi layanan Firebase (seperti Firebase AI Logic) di aplikasi web.
- Konfigurasi template perintah sisi server di Firebase console.
- Akses template dari panggilan ke layanan AI generatif dari frontend TypeScript seperti React.
Hal-hal yang Anda butuhkan:
- Browser web seperti Chrome.
- Pemahaman dasar tentang TypeScript dan Node.js.
- IDE atau editor teks pilihan Anda. Antigravitasi adalah pilihan yang baik.
2. Mendapatkan kode awal
- Di terminal, clone repositori awal:
git clone https://github.com/GoogleCloudPlatform/devrel-demos.git - Buka direktori kode dan instal dependensi:
cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab npm install
3. Menyiapkan project Firebase
Membuat project Firebase
- Login ke Firebase console menggunakan Akun Google Anda.
- Klik tombol untuk membuat project baru, lalu masukkan nama project (misalnya,
rugged-terrain-ai).
- Klik Lanjutkan.
- Jika diminta, tinjau dan setujui persyaratan Firebase, lalu klik Lanjutkan.
- (Opsional) Aktifkan bantuan AI di Firebase console (disebut "Gemini di Firebase").
- Untuk codelab ini, Anda tidak memerlukan Google Analytics, jadi nonaktifkan opsi Google Analytics.
- Klik Create project, tunggu hingga project Anda disediakan, lalu klik Continue.
Mengupgrade paket harga Firebase Anda
Untuk menggunakan layanan Firebase dalam codelab ini, project Firebase Anda harus menggunakan paket harga bayar sesuai penggunaan (Blaze), yang berarti project tersebut ditautkan ke akun Penagihan Cloud.
- Akun Penagihan Cloud memerlukan metode pembayaran, seperti kartu kredit.
- Selama promosi khusus atau jika Anda melakukan codelab ini sebagai bagian dari acara, mungkin ada kredit Google Cloud yang tersedia.
- Jika Anda baru menggunakan Firebase dan Google Cloud, periksa apakah Anda memenuhi syarat untuk mendapatkan kredit sebesar$300 dan akun Penagihan Cloud Uji Coba Gratis.
Untuk mengupgrade project Anda ke paket Blaze, ikuti langkah-langkah berikut:
- Di Firebase console, pilih upgrade your plan.
- Pilih paket Blaze. Ikuti petunjuk di layar untuk menautkan akun Penagihan Cloud ke project Anda.
- Jika Anda menggunakan kredit Google Cloud untuk codelab ini, akun penagihan kemungkinan bernama
Google Cloud Platform Trial Billing AccountatauMy Billing Account. - Jika perlu membuat akun Penagihan Cloud sebagai bagian dari upgrade ini, Anda mungkin perlu kembali ke alur upgrade di Firebase console untuk menyelesaikan upgrade.
- Jika Anda menggunakan kredit Google Cloud untuk codelab ini, akun penagihan kemungkinan bernama
4. Menyiapkan layanan Firebase dan menghubungkan aplikasi Anda
Untuk codelab ini, Anda perlu menyiapkan Cloud Storage for Firebase dan Firebase AI Logic di project Firebase Anda. Anda juga perlu menghubungkan kode sumber aplikasi ke project Firebase.
Menyiapkan Cloud Storage for Firebase
Codelab ini menggunakan Cloud Storage for Firebase untuk menyimpan deskripsi produk.
- Di Firebase console, buka Databases & Storage > Storage.
- Klik Get started.
- Pilih lokasi untuk bucket Storage default Anda.
Bucket diUS-WEST1,US-CENTRAL1, danUS-EAST1dapat memanfaatkan paket"Selalu Gratis" untuk Google Cloud Storage. Bucket di semua lokasi lainnya mengikuti harga dan penggunaan Google Cloud Storage. - Klik Mode produksi. Pada langkah-langkah di bawah, Anda akan memperbarui Aturan Keamanan ini agar spesifik untuk codelab ini.
- Klik Buat.
- Perbarui Aturan Keamanan Anda:
- Setelah bucket disediakan, buka tab Rules.
- Salin, lalu tempel aturan berikut:
rules_version = '2'; service firebase.storage { match /b/{bucket}/o { match /products.txt { allow read; } } } - Klik Publikasikan.
- Upload deskripsi produk dari kode awal:
- Klik tab Files untuk bucket Storage Anda.
- Klik Upload File, lalu upload file
products.txtdari kode awal. File ini dapat ditemukan di:src/data/products.txt.
Mengonfigurasi Firebase AI Logic
Firebase AI Logic adalah layanan Firebase utama yang akan Anda gunakan dalam codelab ini.
- Di Firebase console, buka AI Services > AI Logic.
- Klik Get started.
- Di kartu Agent Platform Gemini API, klik Mulai menggunakan API ini dan ikuti petunjuk di layar. Alur ini akan mengaktifkan API yang diperlukan agar Anda dapat menggunakan Firebase AI Logic dengan Agent Platform Gemini API.
- (Opsional) Pilih untuk Aktifkan pemantauan AI agar Anda dapat mengamati berbagai metrik dan penggunaan tingkat aplikasi untuk mendapatkan visibilitas yang komprehensif ke dalam permintaan Anda melalui Firebase AI Logic.
Menghubungkan kode Anda ke project Firebase
Sebagai bagian dari penyiapan Firebase AI Logic, Anda akan diminta untuk membuat Aplikasi Web Firebase dan menambahkan konfigurasi ke kode sumber.
- Saat diminta dalam alur penyiapan Firebase AI Logic, klik ikon Web (
) untuk mendaftarkan aplikasi web baru. - Beri nama aplikasi (misalnya,
Rugged Web). - Salin objek
firebaseConfigdari petunjuk penyiapan.
Selanjutnya, perbarui kode awal:
- Di editor kode, buka
src/firebase.ts. - Ganti
firebaseConfigyang ada dengan yang Anda salin dari Firebase console.
File Anda akan terlihat seperti ini:
import { getAI, getTemplateGenerativeModel, AgentPlatformBackend } from "firebase/ai";
import { initializeApp } from "firebase/app";
// Your web app's Firebase configuration
const firebaseConfig = {
apiKey: "YOUR_API_KEY",
authDomain: "YOUR_PROJECT_ID.firebaseapp.com",
projectId: "YOUR_PROJECT_ID",
storageBucket: "YOUR_PROJECT_ID.firebasestorage.app",
messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
appId: "YOUR_APP_ID"
};
// Initialize Firebase
export const app = initializeApp(firebaseConfig);
const ai = getAI(app, { backend: new AgentPlatformBackend() });
5. Buat template perintah sisi server
Daripada membuat kode perintah AI yang rumit secara hardcode di aplikasi klien, Anda akan menggunakan sintaksis Dotprompt untuk mengelola petunjuk secara aman di server.
Tindakan ini mencegah pengguna akhir melihat aturan "Anggaran Kompensasi" rahasia.
- Di Firebase console, buka AI Services > AI Logic > Prompt templates tab.
- Klik Buat template, lalu pilih Template kosong.
- Tetapkan nama template ke
Product Agentdan ID keproduct-agent. - Tetapkan model ke
gemini-3.1-flash-lite(atau versi terbaru yang tersedia). - Dari kode awal yang disediakan untuk codelab ini, salin konten
product-agent.prompt(temukan file ini di direktori root). Kemudian, tempel konten ini ke kolom Perintah dan (opsional) petunjuk sistem pada template perintah server di Firebase console. Konten ini secara aman menginstruksikan model tentang cara berperilaku sebagai "Operator Tangguh" dan merujuk katalog produk. - Di kolom Test input, tentukan skema input persis seperti berikut:
{ "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "the customers ask of the robot" }, "productId": { "type": "string", "description": "the product the customer is looking at right now" }, "history": { "type": "array", "description": "list of previous history between the user and system", "items": { "type": "object", "required": [ "role", "contents" ], "properties": { "role": { "type": "string" }, "contents": { "type": "string" } } } } } } - Klik Simpan template untuk menyimpan dan memublikasikan template
product-agent.
6. Panggil model AI
Setelah template ditentukan dengan aman di server, Anda hanya perlu memanggilnya dari frontend aplikasi.
- Di editor kode, kembali ke
src/firebase.ts. - Di bawah inisialisasi, gunakan
getTemplateGenerativeModeluntuk terhubung ke template:const model = getTemplateGenerativeModel(ai); export const callCustomerSupportModel = async (query: string, productId?: string, history?: { role: string, contents: string }[]) => { // Generate content using the published 'product-agent' template const result = await model.generateContent('product-agent', { query, productId, history, }); return result.response.text(); }
7. Mengamankan agen dengan Firebase App Check
Model AI sangat canggih, tetapi juga dapat disalahgunakan jika endpoint publik tidak dilindungi. Anda harus selalu menggunakan Firebase App Check untuk memastikan hanya aplikasi web Anda yang sebenarnya yang dapat membuat permintaan yang berhasil ke Gemini API, sehingga memblokir bot dan klien yang tidak sah.
- Di konsol Google Cloud, buka Security > Fraud Defense
- Klik Create Key dan isi kolom:
- Nama tampilan:
Codelab Key - Jenis Aplikasi: Web
- Daftar domain: Tambahkan
localhostdan127.0.0.1agar server Vite lokal Anda diizinkan untuk membuat permintaan.
- Nama tampilan:
- Klik Buat kunci untuk mendaftarkan kunci.
- Dari bagian atas halaman Detail Kunci Fraud Defense, salin ID kunci situs ke papan klip Anda.
- Di Firebase console, buka Security > App Check.
- Klik tab Aplikasi, luaskan aplikasi web Anda (
Rugged Web), lalu klik penyedia reCAPTCHA Enterprise. - Di kolom kunci situs reCAPTCHA Enterprise, tempelkan ID kunci situs dari halaman Detail Kunci Fraud Defense, lalu klik Simpan.
- Di editor kode, buka
src/firebase.tslagi. - Tambahkan impor berikut di bagian atas:
import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check"; - Tambahkan inisialisasi App Check tepat setelah panggilan
initializeApp(firebaseConfig), dan tempelkan ID kunci situs yang Anda salin:// Initialize App Check const appCheck = initializeAppCheck(app, { provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'), isTokenAutoRefreshEnabled: true }); - Perbarui panggilan fungsi
getAI()Anda untuk menggunakan token ini. Buat perubahan berikut: Dengan menyetel nilaiconst ai = getAI(app, { backend: new AgentPlatformBackend(), useLimitedUseAppCheckTokens: true });useLimitedUseAppCheckTokenske benar (true), Anda memastikan bahwa token yang berumur pendek diterapkan untuk membantu membatasi penyalahgunaan yang mungkin diterima backend Anda.
8. Menjalankan aplikasi
Setelah konfigurasi Firebase Anda disiapkan dan widget chat dukungan terhubung, saatnya menjalankan aplikasi.
- Di terminal Anda, jalankan server pengembangan Vite:
npm run dev - Buka URL lokal yang disediakan (biasanya
http://localhost:5173/). - Klik Tombol Tindakan Mengambang (FAB) Dukungan Taktis di sudut kanan bawah.
- Coba ajukan pertanyaan tentang produk, misalnya:
- "Saya mencari jaket luar tahan cuaca"
- "Topi sub-zero saya rusak, apa yang bisa saya lakukan?"
- Terus tolak untuk memicu logika "Anggaran Peredaan" AI.
9. (Opsional) Membersihkan resource dari codelab
Untuk menghindari kemungkinan biaya pada akun Penagihan Google Cloud Anda, Anda dapat menghapus resource yang dibuat selama codelab ini.
- Di Firebase console, buka tab Settings > General.
- Pastikan project yang Anda lihat adalah project yang Anda gunakan untuk codelab ini. Jika bukan project codelab Anda, Anda dapat menggunakan dropdown pemilih project di sudut kiri atas untuk mengubah project.
- Buka bagian bawah halaman, lalu klik Hapus project.
- Ikuti petunjuk di layar untuk mengonfirmasi penghapusan.
10. Selamat!
🎊 Misi Selesai! Anda telah berhasil mengintegrasikan agen dukungan pelanggan AI berbasis template yang andal.
Yang Anda capai:
- Menginisialisasi Firebase dan backend Agent Platform di aplikasi klien.
- Mengonfigurasi template perintah sisi server yang aman menggunakan Handlebars dan skema input yang ketat untuk menentukan perilaku kompleks agen.
- Memanggil LLM secara dinamis dengan aman, meneruskan histori percakapan dan ID produk kontekstual tanpa mengekspos logika perintah internal ke klien.
Apa langkah selanjutnya?
- Firebase App Check: Amankan endpoint AI Anda dari penyalahgunaan.