Membangun agen dukungan pelanggan yang didukung AI menggunakan Firebase AI Logic

1. Pengantar

Dalam codelab ini, Anda akan menambahkan widget chat dukungan pelanggan pintar ke toko e-commerce perlengkapan luar ruangan bernama Rugged Terrain Guide. Anda akan menggunakan Firebase AI Logic untuk membangun agen ini, dan Anda akan mempelajari cara mengonfigurasi template perintah sisi server (product-agent) yang menangani persona AI, aturan anggaran penyesuaian 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

  1. Di terminal, clone repositori awal:
    git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
  2. Buka direktori kode dan instal dependensi:
    cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab
npm install

3. Menyiapkan project Firebase

Membuat project Firebase

  1. Login ke Firebase console menggunakan Akun Google Anda.
  2. Klik tombol untuk membuat project baru, lalu masukkan nama project (misalnya, rugged-terrain-ai).
  3. Klik Lanjutkan.
  4. Jika diminta, tinjau dan setujui persyaratan Firebase, lalu klik Continue.
  5. (Opsional) Aktifkan bantuan AI di Firebase console (disebut "Gemini di Firebase").
  6. Untuk codelab ini, Anda tidak memerlukan Google Analytics, jadi nonaktifkan opsi Google Analytics.
  7. Klik Buat project, tunggu hingga project Anda disediakan, lalu klik Lanjutkan.

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.
  • 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.
  • Jika Anda melakukan codelab ini sebagai bagian dari acara, tanyakan kepada penyelenggara apakah ada kredit Cloud yang tersedia.

Untuk mengupgrade project Anda ke paket Blaze, ikuti langkah-langkah berikut:

  1. Di Firebase console, pilih upgrade your plan.
  2. Pilih paket Blaze. Ikuti petunjuk di layar untuk menautkan akun Penagihan Cloud ke project Anda.
    Jika perlu membuat akun Penagihan Cloud sebagai bagian dari upgrade ini, Anda mungkin perlu kembali ke alur upgrade di Firebase console untuk menyelesaikan upgrade.

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.

  1. Di Firebase console, buka Databases & Storage > Storage.
  2. Klik Get started.
  3. Pilih lokasi untuk bucket Storage default Anda.
    Bucket di US-WEST1, US-CENTRAL1, dan US-EAST1 dapat memanfaatkan paket"Selalu Gratis" untuk Google Cloud Storage. Bucket di semua lokasi lainnya mengikuti harga dan penggunaan Google Cloud Storage.
  4. Klik Mode produksi. Pada langkah-langkah di bawah, Anda akan memperbarui Aturan Keamanan ini agar spesifik untuk codelab ini.
  5. Klik Buat.
  6. Perbarui Aturan Keamanan Anda:
    1. Setelah bucket disediakan, buka tab Aturan.
    2. Salin, lalu tempel aturan berikut:
      rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /products.txt {
      allow read;
    }
  }
}
    3. Klik Publikasikan.
  7. Upload deskripsi produk dari kode awal:
    1. Klik tab File untuk bucket Storage Anda.
    2. Klik Upload File, lalu upload file products.txt dari 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.

  1. Di Firebase console, buka AI Services > AI Logic.
  2. Klik Get started.
  3. Pada kartu Vertex AI 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 Vertex AI Gemini API.
  4. (Opsional) Pilih untuk Aktifkan pemantauan AI agar Anda dapat mengamati berbagai metrik dan penggunaan tingkat aplikasi untuk mendapatkan visibilitas komprehensif ke dalam permintaan Anda melalui Firebase AI Logic.

Menghubungkan kode ke project Firebase Anda

Sebagai bagian dari penyiapan Firebase AI Logic, Anda akan diminta untuk membuat Aplikasi Web Firebase dan menambahkan konfigurasi ke kode sumber.

  1. Saat diminta dalam alur penyiapan Firebase AI Logic, klik ikon Web () untuk mendaftarkan aplikasi web baru.
  2. Beri nama aplikasi (misalnya, Rugged Web).
  3. Salin objek firebaseConfig dari petunjuk penyiapan.

Selanjutnya, perbarui kode awal:

  1. Di editor kode, buka src/firebase.ts.
  2. Ganti firebaseConfig yang ada dengan firebaseConfig yang Anda salin dari Firebase console.

File Anda akan terlihat seperti ini:

import { getAI, getTemplateGenerativeModel, VertexAIBackend } 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 VertexAIBackend() });

5. Membuat template perintah sisi server

Daripada melakukan hardcode perintah AI yang kompleks di aplikasi klien, Anda akan menggunakan sintaksis Dotprompt untuk mengelola petunjuk secara aman di server.

Hal ini mencegah pengguna akhir melihat aturan "Anggaran Kompensasi" rahasia.

  1. Di Firebase console, buka bagian Vertex AI atau Prompt Management.
  2. Buat template perintah baru, lalu beri nama product-agent.
  3. Tetapkan model ke gemini-2.5-flash.
  4. Tentukan skema input persis seperti berikut:
    input:
  schema:
    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
  5. Salin konten agent-product.prompt dari direktori root ke kolom Perintah dan petunjuk sistem opsional. Hal ini secara aman menginstruksikan model tentang cara berperilaku sebagai "Operator Tangguh" dan menyuntikkan katalog produk.
  6. Di Firebase console, simpan dan publikasikan template product-agent.

6. Panggil model AI

Setelah template ditentukan dengan aman di server, Anda hanya perlu memanggilnya dari frontend aplikasi.

  1. Di editor kode, kembali ke src/firebase.ts.
  2. Di bawah inisialisasi, gunakan getTemplateGenerativeModel untuk 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 bermanfaat, 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 memanggil model generatif Vertex AI, sehingga memblokir bot dan klien yang tidak sah.

  1. Di Firebase console, buka Build > App Check.
  2. Klik tab Aplikasi, luaskan aplikasi web Anda (Rugged Web), lalu klik penyedia reCAPTCHA Enterprise.
  3. Pilih Buat kunci reCAPTCHA Enterprise baru dan isi perintah:
    • Nama: Codelab Key
    • Domain: Tambahkan localhost dan 127.0.0.1 agar server Vite lokal Anda diizinkan untuk membuat permintaan.
  4. Klik Simpan untuk mendaftarkan aplikasi.
  5. Setelah terdaftar, Firebase console akan menampilkan Kunci Situs Anda. Salin string ini.
  6. Di editor kode, buka src/firebase.ts lagi.
  7. Tambahkan impor berikut di bagian atas:
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  8. Tambahkan inisialisasi App Check tepat setelah panggilan initializeApp(firebaseConfig), dan tempelkan kunci situs yang Anda salin:
    // Initialize App Check
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
  useLimitedUseAppCheckTokens: true
});
  9. Perbarui panggilan fungsi getAI() untuk menggunakan token ini. Buat perubahan berikut:
    const ai = getAI(app, { backend: new VertexAIBackend(), useLimitedUseAppCheckTokens: true });
    Dengan menyetel nilai useLimitedUseAppCheckTokens ke 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.

  1. Di terminal Anda, jalankan server pengembangan Vite:
    npm run dev
  2. Buka URL lokal yang disediakan (biasanya http://localhost:5173/).
  3. Klik Tombol Tindakan Mengambang (FAB) Dukungan Taktis di sudut kanan bawah.
  4. Coba ajukan pertanyaan tentang produk, misalnya:
    • "Saya mencari jaket luar tahan cuaca"
    • "Topi kupluk di bawah nol derajat saya rusak, apa yang dapat 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.

  1. Buka Firebase console.
  2. Pilih project rugged-terrain-ai.
  3. Buka Project settings (ikon roda gigi).
  4. Scroll ke bagian bawah, lalu klik Hapus project.
  5. Ikuti petunjuk di layar untuk mengonfirmasi penghapusan.

10. Selamat!

🎊 Misi Selesai! Anda telah berhasil mengintegrasikan agen dukungan pelanggan AI berbasis template yang andal.

Yang telah Anda capai:

  • Menginisialisasi Firebase dan backend Vertex AI 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?