Membangun agen dukungan pelanggan yang didukung AI menggunakan Firebase AI Logic

1. Pengantar

Dalam codelab ini, Anda akan menambahkan widget chat dukungan pelanggan smart ke toko e-commerce perlengkapan outdoor yang disebut 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 kompensasi yang ketat, dan menggunakan katalog produk secara dinamis sebagai konteks.

Yang akan Anda lakukan:

  • Mendapatkan kode awal untuk aplikasi web codelab ini.
  • Menyiapkan project Firebase.
  • Menyiapkan dan melakukan inisialisasi layanan Firebase (seperti Firebase AI Logic) di aplikasi web.
  • Mengonfigurasi template perintah sisi server di Firebase console.
  • Mengakses 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. Antigravity adalah pilihan yang tepat.

2. Mendapatkan kode awal

  1. Di terminal Anda, 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 Lanjutkan.
  5. (Opsional) Aktifkan bantuan AI di Firebase console (disebut "Gemini di Firebase").
  6. Untuk codelab ini, Anda tidak memerlukan Google Analytics. Oleh karena itu, 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.
  • 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:

  1. Di Firebase console, pilih untuk upgrade your plan.
  2. 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 akan disebut Google Cloud Platform Trial Billing Account atau My Billing Account.
    • Jika Anda 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

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

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 Mulai.
  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 Rules.
    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 Files 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 Mulai.
  3. Di kartu Agent Platform Gemini API, klik Get started with this API dan ikuti petunjuk di layar. Alur ini akan mengaktifkan API yang diperlukan agar Anda dapat menggunakan Firebase AI Logic dengan Agent Platform Gemini API.
  4. (Opsional) Pilih Enable AI monitoring 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 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. Membuat template perintah sisi server

Daripada melakukan hardcode pada perintah AI yang kompleks 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.

  1. Di Firebase console, buka tab AI Services > AI Logic > Prompt templates.
  2. Klik Create template, lalu pilih Blank template.
  3. Tetapkan nama template ke Product Agent dan ID ke product-agent.
  4. Tetapkan model ke gemini-3.1-flash-lite (atau versi terbaru yang tersedia).
  5. Dari kode awal yang disediakan untuk codelab ini, salin konten product-agent.prompt (temukan file ini di direktori utama). Kemudian, tempelkan konten ini ke kolom Prompt and (optional) system instructions dari template perintah server di Firebase console. Konten ini secara aman menginstruksikan model cara berperilaku sebagai "Rugged Operator" dan mereferensikan katalog produk.
  6. 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"
          }
        }
      }
    }
  }
}
  7. Klik Save template untuk menyimpan dan memublikasikan template product-agent.

6. Memanggil model AI

Setelah template ditentukan secara 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 canggih, tetapi juga dapat disalahgunakan jika endpoint publik tidak dilindungi. Anda harus selalu menggunakan Firebase App Check untuk memastikan bahwa hanya aplikasi web Anda yang sebenarnya dapat membuat permintaan yang berhasil ke Gemini API, memblokir bot dan klien yang tidak sah.

  1. Di Konsol Google Cloud, buka Security > Fraud Defense
  2. Klik Create Key dan isi kolom:
    • Display name: Codelab Key
    • Application Type: Web
    • Daftar domain: Tambahkan localhost dan 127.0.0.1 agar server Vite lokal Anda diizinkan untuk membuat permintaan.
  3. Klik Create key untuk mendaftarkan kunci.
  4. Dari bagian atas halaman detail Fraud Defense Key, salin ID kunci situs ke papan klip Anda.
  5. Di Firebase console, buka Security > App Check.
  6. Klik tab Apps, luaskan aplikasi web Anda (Rugged Web), lalu klik penyedia reCAPTCHA Enterprise.
  7. Di kolom reCAPTCHA Enterprise site key , tempelkan ID kunci situs dari halaman detail Fraud Defense Key, lalu klik Save.
  8. Di editor kode, buka src/firebase.ts lagi.
  9. Tambahkan impor berikut di bagian atas:
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  10. 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
});
  11. Perbarui panggilan fungsi getAI() untuk menggunakan token ini. Buat perubahan berikut:
    const ai = getAI(app, { backend: new AgentPlatformBackend(), useLimitedUseAppCheckTokens: true });
    Dengan menetapkan nilai useLimitedUseAppCheckTokens ke benar (true), Anda memastikan bahwa token berdurasi singkat diterapkan untuk membantu membatasi penyalahgunaan yang mungkin diterima backend Anda.

8. Menjalankan aplikasi

Setelah konfigurasi Firebase Anda diterapkan 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) Tactical Support di sudut kanan bawah.
  4. Coba ajukan pertanyaan tentang produk, misalnya:
    • "I'm looking for a weatherproof shell"
    • "My sub-zero beanie is defective, what can I do?"
    • Terus ajukan pertanyaan untuk memicu logika "Anggaran Kompensasi" AI.

9. (Opsional) Mengosongkan resource dari codelab

Untuk menghindari kemungkinan biaya pada akun Penagihan Google Cloud Anda, Anda dapat menghapus resource yang dibuat selama codelab ini.

  1. Di Firebase console, buka tab Settings > General.
  2. 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.
  3. Buka bagian bawah halaman, lalu klik Delete project.
  4. Ikuti petunjuk di layar untuk mengonfirmasi penghapusan.

10. Selamat!

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

Yang telah Anda capai:

  • Melakukan inisialisasi 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 meneruskan histori chat dan ID produk kontekstual secara aman tanpa mengekspos logika perintah internal ke klien.

Apa langkah selanjutnya?