Tworzenie agenta obsługi klienta opartego na AI za pomocą Firebase AI Logic

1. Wprowadzenie

W tym ćwiczeniu dodasz inteligentny widżet czatu obsługi klienta do sklepu e-commerce z odzieżą outdoorową o nazwie Rugged Terrain Guide. Do utworzenia tego agenta użyjesz Firebase AI Logic i dowiesz się, jak skonfigurować szablon promptu po stronie serwera (product-agent), który obsługuje personę AI, rygorystyczne reguły budżetu na rekompensaty i dynamicznie wykorzystuje katalog produktów jako kontekst.

Co musisz zrobić:

  • Pobierz kod startowy aplikacji internetowej na potrzeby tego ćwiczenia.
  • Skonfiguruj projekt w Firebase.
  • Skonfiguruj i zainicjuj usługi Firebase (takie jak Firebase AI Logic) w aplikacji internetowej.
  • Skonfiguruj szablon promptu po stronie serwera w konsoli Firebase.
  • Uzyskaj dostęp do szablonu z wywołania usługi generatywnej AI z frontendu TypeScript podobnego do React.

Co będzie Ci potrzebne

  • Przeglądarka internetowa, np. Chrome.
  • Podstawowa znajomość TypeScript i Node.js.
  • Wybrane IDE lub edytor tekstu. Dobrym wyborem jest Antigravity.

2. Pobieranie kodu startowego

  1. W terminalu skopiuj repozytorium startowe:
    git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
  2. Przejdź do katalogu kodu i zainstaluj zależności:
    cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab
npm install

3. Konfigurowanie projektu w Firebase

Tworzenie projektu w Firebase

  1. Zaloguj się w konsoli Firebase za pomocą konta Google.
  2. Kliknij przycisk, aby utworzyć nowy projekt, a następnie wpisz jego nazwę (np. rugged-terrain-ai).
  3. Kliknij Dalej.
  4. Jeśli pojawi się prośba, zapoznaj się z warunkami korzystania z Firebase i zaakceptuj je, a następnie kliknij Dalej.
  5. (Opcjonalnie) Włącz pomoc AI w konsoli Firebase (nazywaną „Gemini w Firebase”).
  6. W tym ćwiczeniu nie potrzebujesz Google Analytics, więc wyłącz tę opcję.
  7. Kliknij Utwórz projekt, poczekaj na utworzenie projektu, a następnie kliknij Dalej.

Uaktualnianie abonamentu Firebase

Aby korzystać z usług Firebase w tym ćwiczeniu, Twój projekt w Firebase musi być objęty abonamentem z płatnością według wykorzystania (Blaze), co oznacza, że jest połączony z kontem rozliczeniowym Cloud.

Aby przenieść projekt na abonament Blaze, wykonaj te czynności:

  1. W konsoli Firebase wybierz, aby uaktualnić abonament.
  2. Wybierz abonament Blaze. Postępuj zgodnie z instrukcjami wyświetlanymi na ekranie, aby połączyć konto rozliczeniowe Cloud z projektem.
    • Jeśli w tym ćwiczeniu używasz środków Google Cloud, konto rozliczeniowe prawdopodobnie będzie się nazywać Google Cloud Platform Trial Billing Account lub My Billing Account.
    • Jeśli w ramach tego uaktualnienia musisz utworzyć konto rozliczeniowe Cloud, może być konieczne powrócenie do procesu uaktualniania w konsoli Firebase, aby go dokończyć.

4. Konfigurowanie usług Firebase i łączenie aplikacji

W tym ćwiczeniu musisz skonfigurować w projekcie w Firebase Cloud Storage dla Firebase i Firebase AI Logic. Musisz też połączyć kod źródłowy aplikacji z projektem w Firebase.

Konfigurowanie Cloud Storage dla Firebase

W tym ćwiczeniu do przechowywania opisów produktów używamy Cloud Storage dla Firebase.

  1. W konsoli Firebase otwórz Bazy danych i miejsce na dane > Miejsce na dane.
  2. Kliknij Rozpocznij.
  3. Wybierz lokalizację domyślnego zasobnika na dane.
    Zasobniki w lokalizacjach US-WEST1, US-CENTRAL1 i US-EAST1 mogą korzystać z warstwy „Zawsze bezpłatnie” w Google Cloud Storage. W przypadku zasobników w pozostałych lokalizacjach obowiązują ceny i zasady użytkowania Google Cloud Storage.
  4. Kliknij Tryb produkcyjny. W krokach opisanych poniżej zaktualizujesz te reguły zabezpieczeń, aby były specyficzne dla tego ćwiczenia.
  5. Kliknij Utwórz.
  6. Zaktualizuj reguły zabezpieczeń:
    1. Po utworzeniu zasobnika otwórz kartę Reguły.
    2. Skopiuj i wklej te reguły:
      rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /products.txt {
      allow read;
    }
  }
}
    3. Kliknij Opublikuj.
  7. Prześlij opisy produktów z kodu startowego:
    1. Kliknij kartę Pliki w zasobniku na dane.
    2. Kliknij Prześlij plik, a następnie prześlij plik products.txt z kodu startowego. Ten plik znajdziesz w katalogu src/data/products.txt.

Konfigurowanie Firebase AI Logic

Firebase AI Logic to główna usługa Firebase, której będziesz używać w tym ćwiczeniu.

  1. W konsoli Firebase otwórz Usługi AI > AI Logic.
  2. Kliknij Rozpocznij.
  3. Na karcie Agent Platform Gemini API kliknij Rozpocznij korzystanie z tego interfejsu API i postępuj zgodnie z instrukcjami wyświetlanymi na ekranie. Ten proces włączy wymagane interfejsy API, aby można było używać Firebase AI Logic z Agent Platform Gemini API.
  4. (Opcjonalnie) Kliknij Włącz monitorowanie wykorzystania AI , aby móc obserwować różne wskaźniki i wykorzystanie na poziomie aplikacji, co pozwoli Ci uzyskać pełną widoczność w żądaniach za pomocą Firebase AI Logic.

Łączenie kodu z projektem w Firebase

W ramach konfigurowania Firebase AI Logic pojawi się prośba o utworzenie aplikacji internetowej Firebase i dodanie konfiguracji do kodu źródłowego.

  1. Gdy w procesie konfigurowania Firebase AI Logic pojawi się prośba, kliknij ikonę Internet (), aby zarejestrować nową aplikację internetową.
  2. Nazwij aplikację (np. Rugged Web).
  3. Skopiuj obiekt firebaseConfig z instrukcji konfiguracji.

Następnie zaktualizuj kod startowy:

  1. W edytorze kodu otwórz plik src/firebase.ts.
  2. Zastąp istniejący obiekt firebaseConfig obiektem skopiowanym z konsoli Firebase.

Plik powinien wyglądać tak:

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. Tworzenie szablonu promptu po stronie serwera

Zamiast na stałe kodować złożone prompty AI w aplikacji klienckiej, będziesz używać składni Dotprompt do bezpiecznego zarządzania instrukcjami na serwerze.

Dzięki temu użytkownicy nie będą widzieć tajnych reguł „Budżetu na rekompensaty”.

  1. W konsoli Firebase otwórz kartę Usługi AI > AI Logic > Szablony promptów.
  2. Kliknij Utwórz szablon i wybierz Pusty szablon.
  3. Ustaw nazwę szablonu na Product Agent, a identyfikator na product-agent.
  4. Ustaw model na gemini-3.1-flash-lite (lub najnowszą dostępną wersję).
  5. W kodzie startowym udostępnionym na potrzeby tego ćwiczenia skopiuj zawartość pliku product-agent.prompt (znajduje się on w katalogu głównym). Następnie wklej tę zawartość w konsoli Firebase w polu Prompt i (opcjonalne) instrukcje systemowe szablonu promptu po stronie serwera. Ta zawartość bezpiecznie instruuje model, jak ma się zachowywać jako „Rugged Operator” i jak ma odwoływać się do katalogu produktów.
  6. W polu Dane testowe zdefiniuj schemat danych wejściowych dokładnie w ten sposób:
    {
  "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. Kliknij Zapisz szablon , aby zapisać i opublikować szablon product-agent.

6. Wywoływanie modelu AI

Teraz, gdy szablon jest bezpiecznie zdefiniowany na serwerze, wystarczy go wywołać z frontendu aplikacji.

  1. W edytorze kodu wróć do pliku src/firebase.ts.
  2. Poniżej inicjowania użyj getTemplateGenerativeModel, aby połączyć się z szablonem:
    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. Zabezpieczanie agenta za pomocą funkcji Sprawdzanie aplikacji Firebase

Modele AI są zaawansowane, ale mogą też być nadużywane, jeśli publiczne punkty końcowe pozostaną niezabezpieczone. Zawsze używaj funkcji Sprawdzanie aplikacji Firebase, aby mieć pewność, że tylko Twoja rzeczywista aplikacja internetowa może wysyłać żądania do interfejsu Gemini API, blokując boty i nieautoryzowanych klientów.

  1. W konsoli Google Cloud otwórz Zabezpieczenia > Fraud Defense
  2. Kliknij Utwórz klucz i wypełnij pola:
    • Nazwa wyświetlana: Codelab Key
    • Typ aplikacji: internet
    • Lista domen: dodaj localhost i 127.0.0.1, aby lokalny serwer Vite mógł wysyłać żądania.
  3. Kliknij Utwórz klucz , aby zarejestrować klucz.
  4. U góry strony szczegółów klucza Fraud Defense skopiuj do schowka identyfikator klucza witryny.
  5. W konsoli Firebase otwórz Zabezpieczenia > Sprawdzanie aplikacji.
  6. Kliknij kartę Aplikacje , rozwiń aplikację internetową (Rugged Web) i kliknij dostawcę reCAPTCHA Enterprise.
  7. W polu Klucz witryny reCAPTCHA Enterprise wklej identyfikator klucza witryny ze strony szczegółów klucza Fraud Defense i kliknij Zapisz.
  8. W edytorze kodu ponownie otwórz plik src/firebase.ts.
  9. U góry dodaj te instrukcje importu:
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  10. Dodaj inicjowanie funkcji Sprawdzanie aplikacji bezpośrednio po wywołaniu initializeApp(firebaseConfig) i wklej skopiowany identyfikator klucza witryny:
    // Initialize App Check
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
  isTokenAutoRefreshEnabled: true
});
  11. Zaktualizuj wywołanie funkcji getAI(), aby używać tych tokenów. Wprowadź tę zmianę:
    const ai = getAI(app, { backend: new AgentPlatformBackend(), useLimitedUseAppCheckTokens: true });
    Ustawiając wartość useLimitedUseAppCheckTokens na true, zapewniasz, że będą stosowane krótkotrwałe tokeny, które pomogą ograniczyć nadużycia, jakie może otrzymywać Twój backend.

8. Uruchamianie aplikacji

Po skonfigurowaniu Firebase i podłączeniu widżetu czatu obsługi klienta możesz uruchomić aplikację.

  1. W terminalu uruchom serwer programistyczny Vite:
    npm run dev
  2. Otwórz podany adres URL (zwykle http://localhost:5173/).
  3. W prawym dolnym rogu kliknij pływający przycisk polecenia (FAB) Pomoc taktyczna.
  4. Spróbuj zadać pytania o produkty, na przykład:
    • „Szukam kurtki odpornej na warunki atmosferyczne”.
    • „Moja czapka Sub-Zero jest uszkodzona. Co mogę zrobić?”
    • Naciskaj dalej, aby uruchomić logikę „Budżetu na rekompensaty” AI.

9. (Opcjonalnie) Zwalnianie miejsca zajmowanego przez zasoby z ćwiczenia

Aby uniknąć ewentualnych opłat na koncie rozliczeniowym Cloud, możesz usunąć zasoby utworzone podczas tego ćwiczenia.

  1. W konsoli Firebase otwórz kartę Ustawienia > Ogólne.
  2. Upewnij się, że wyświetlany projekt to projekt, którego używasz w tym ćwiczeniu. Jeśli nie jest to projekt ćwiczenia, możesz zmienić projekt za pomocą menu selektora projektów w lewym górnym rogu.
  3. Przewiń stronę w dół i kliknij Usuń projekt.
  4. Aby potwierdzić usunięcie, postępuj zgodnie z instrukcjami wyświetlanymi na ekranie.

10. Gratulacje!

🎊 Misja zakończona! Udało Ci się zintegrować solidnego agenta obsługi klienta opartego na AI i szablonach.

Co udało Ci się osiągnąć:

  • Zainicjowano Firebase i backend Agent Platform w aplikacji klienckiej.
  • Skonfigurowano bezpieczny szablon promptu po stronie serwera za pomocą Handlebars i rygorystycznych schematów danych wejściowych, aby zdefiniować złożone zachowanie agenta.
  • Dynamicznie wywołano LLM , bezpiecznie przekazując historię czatu i kontekstowe identyfikatory produktów bez ujawniania klientowi wewnętrznej logiki promptu.

Co dalej?