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 ze sprzętem turystycznym o nazwie Rugged Terrain Guide. Do utworzenia tego agenta użyjesz Firebase AI Logic. Dowiesz się, jak skonfigurować szablon prompta po stronie serwera (product-agent), który obsługuje personę AI, ścisłe reguły budżetu na rekompensaty i dynamicznie wykorzystuje katalog produktów jako kontekst.

Co musisz zrobić:

  • Pobierz kod startowy aplikacji internetowej z tego laboratorium.
  • Skonfiguruj projekt w Firebase.
  • Skonfiguruj i zainicjuj usługi Firebase (np. Firebase AI Logic) w aplikacji internetowej.
  • Skonfiguruj szablon prompta po stronie serwera w konsoli Firebase.
  • Dostęp do szablonu można uzyskać w ramach wywołania usługi generatywnej AI z poziomu frontendu TypeScript podobnego do React.

Co będzie Ci potrzebne

  • przeglądarka, np. Chrome;
  • Podstawowa znajomość TypeScriptu i Node.js.
  • Wybrane środowisko IDE lub edytor tekstu. Antygrawitacja to dobry wybór.

2. Pobieranie kodu startowego

  1. W terminalu sklonuj repozytorium początkowe:
    git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
    
  2. Przejdź do katalogu z kodem 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, korzystając ze swojego konta Google.
  2. Kliknij przycisk, aby utworzyć nowy projekt, a potem wpisz jego nazwę (np. rugged-terrain-ai).
  3. Kliknij Dalej.
  4. Jeśli pojawi się odpowiedni komunikat, przeczytaj i zaakceptuj warunki korzystania z Firebase, a potem kliknij Dalej.
  5. (Opcjonalnie) Włącz w konsoli Firebase pomoc AI (nazywaną „Gemini w Firebase”).
  6. W tym samouczku nie potrzebujesz Google Analytics, więc wyłącz opcję Google Analytics.
  7. Kliknij Utwórz projekt, poczekaj, aż projekt zostanie udostępniony, a następnie kliknij Dalej.

Przechodzenie na wyższy pakiet cenowy Firebase

Aby korzystać z usług Firebase w tym ćwiczeniu, musisz mieć projekt w Firebase w abonamencie z płatnością według wykorzystania (Blaze), co oznacza, że musi on być połączony z kontem rozliczeniowym Cloud.

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

  1. W konsoli Firebase wybierz przejście na wyższy abonament.
  2. Wybierz pakiet Blaze. Postępuj zgodnie z instrukcjami wyświetlanymi na ekranie, aby połączyć konto rozliczeniowe Cloud z projektem.
    • Jeśli w tym laboratorium korzystasz z kredytó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 konieczne było utworzenie konta rozliczeniowego Cloud, może być potrzebny powrót do procesu uaktualniania w konsoli Firebase, aby dokończyć uaktualnienie.

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żywana jest usługa Cloud Storage dla Firebase.

  1. W konsoli Firebase kliknij Bazy danych i miejsce na dane > Miejsce na dane.
  2. Kliknij Rozpocznij.
  3. Wybierz lokalizację domyślnego zasobnika Storage.
    Zasobniki w lokalizacjach US-WEST1, US-CENTRAL1 i US-EAST1 mogą korzystać z bezpłatnego poziomu Google Cloud Storage. Zasobniki w pozostałych lokalizacjach podlegają cennikowi i zasadom użytkowania Google Cloud Storage.
  4. Kliknij Tryb produkcyjny. W krokach poniżej zaktualizujesz te reguły bezpieczeństwa, aby były dostosowane do tego laboratorium.
  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 lokalizacji: 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 > Logika AI.
  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 umożliwić Ci korzystanie z Firebase AI Logic z interfejsem Agent Platform Gemini API.
  4. (Opcjonalnie) wybierz Włącz monitorowanie AI, aby obserwować różne dane i sposoby użycia na poziomie aplikacji i uzyskać pełny wgląd w swoje żądania 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 konfiguracji Firebase AI Logic pojawi się odpowiedni komunikat, 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 src/firebase.ts.
  2. Zastąp istniejący klucz firebaseConfig kluczem 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, możesz używać składni Dotprompt, aby bezpiecznie zarządzać instrukcjami na serwerze.

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

  1. W konsoli Firebase otwórz Usługi AI > Logika AI > karta 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. Skopiuj zawartość pliku product-agent.prompt z kodu startowego udostępnionego w tym ćwiczeniu (znajdziesz go w katalogu głównym). Następnie wklej tę treść w polu Prompt i (opcjonalne) instrukcje systemowe w szablonie promptu serwera w konsoli Firebase. Te treści bezpiecznie instruują model, jak ma się zachowywać jako „Rugged Operator” i jak korzystać z katalogu produktów.
  6. W polu Dane wejściowe testu zdefiniuj schemat danych wejściowych 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. Aby zapisać i opublikować szablon product-agent, kliknij Zapisz szablon.

6. Wywołaj model AI

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

  1. W edytorze kodu wróć do src/firebase.ts.
  2. Pod inicjalizacją 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ą potężne, ale mogą być też wykorzystywane w nieodpowiedni sposób, jeśli publiczne punkty końcowe nie są chronione. Zawsze używaj funkcji Sprawdzanie aplikacji Firebase, aby mieć pewność, że tylko Twoja prawdziwa 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 Bezpieczeństwo > Fraud Defense.
  2. Kliknij Utwórz klucz i wypełnij pola:
    • Nazwa wyświetlana: Codelab Key
    • Typ aplikacji: internetowa
    • Lista domen: dodaj localhost i 127.0.0.1, aby lokalny serwer Vite mógł wysyłać żądania.
  3. Aby zarejestrować klucz, kliknij Utwórz klucz.
  4. U góry strony Szczegóły klucza Fraud Defense skopiuj identyfikator klucza witryny do schowka.
  5. W konsoli Firebase otwórz Bezpieczeństwo > 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óły klucza ochrony przed oszustwami i kliknij Zapisz.
  8. W edytorze kodu ponownie otwórz src/firebase.ts.
  9. U góry dodaj te instrukcje importu:
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
    
  10. Dodaj inicjację Sprawdzania aplikacji bezpośrednio po wywołaniu funkcji 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”, masz pewność, że krótkotrwałe tokeny są stosowane w celu ograniczenia nadużyć, które mogą dotyczyć Twojego backendu.

8. Uruchamianie aplikacji

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

  1. W terminalu uruchom serwer programistyczny Vite:
    npm run dev
    
  2. Otwórz podany lokalny adres URL (zwykle http://localhost:5173/).
  3. W prawym dolnym rogu kliknij pływający przycisk polecenia (FAB) Wsparcie taktyczne.
  4. Spróbuj zadać pytania dotyczące produktów, na przykład:
    • „Szukam kurtki przeciwdeszczowej”
    • „Moja czapka zimowa jest wadliwa. Co mogę zrobić?”
    • Naciskaj dalej, aby uruchomić logikę „Budżetu na uspokojenie” AI.

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

Aby uniknąć obciążenia konta rozliczeniowego Google Cloud opłatami, możesz usunąć zasoby utworzone podczas tego ćwiczenia.

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

10. Gratulacje!

🎊 Misja ukończona! Udało Ci się zintegrować solidnego agenta obsługi klienta opartego na AI, który korzysta z szablonów.

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

  • Zainicjowano Firebase i backend Platformy agentów w aplikacji klienta.
  • Skonfigurowano bezpieczny szablon prompta po stronie serwera przy użyciu Handlebars i ścisłych schematów danych wejściowych, aby zdefiniować złożone zachowanie agenta.
  • Dynamiczne wywoływanie LLM z bezpiecznym przekazywaniem historii czatu i kontekstowych identyfikatorów produktów bez ujawniania klientowi wewnętrznej logiki promptów.

Co dalej?