KI-basierten Kundensupportagenten mit Firebase AI Logic erstellen

1. Einführung

In diesem Codelab fügen Sie einem E‑Commerce-Shop für Outdoor-Ausrüstung namens Rugged Terrain Guide ein intelligentes Kundensupport-Chat-Widget hinzu. Sie verwenden Firebase AI Logic, um diesen Agenten zu erstellen, und erfahren, wie Sie eine serverseitige Prompt-Vorlage (product-agent) konfigurieren, die die Persona der KI, strenge Regeln für das Entgegenkommen und dynamisch den Produktkatalog als Kontext verwendet.

Aufgaben:

  • Startcode für die Webanwendung dieses Codelabs abrufen
  • Firebase-Projekt einrichten
  • Firebase-Dienste (z. B. Firebase AI Logic) in einer Webanwendung einrichten und initialisieren
  • Serverseitige Prompt-Vorlage in der Firebase Console konfigurieren
  • Über einen Aufruf des generativen KI-Dienstes von einem React-ähnlichen TypeScript-Frontend auf die Vorlage zugreifen

Voraussetzungen:

  • Ein Webbrowser wie Chrome.
  • Grundlegende Kenntnisse in TypeScript und Node.js
  • Eine IDE oder ein Texteditor Ihrer Wahl Antigravity ist eine gute Wahl.

2. Startcode abrufen

  1. Klonen Sie in Ihrem Terminal das Starter-Repository:
    git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
  2. Wechseln Sie zum Codeverzeichnis und installieren Sie die Abhängigkeiten:
    cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab
npm install

3. Firebase-Projekt einrichten

Firebase-Projekt erstellen

  1. Melden Sie sich mit Ihrem Google-Konto in der Firebase Console an.
  2. Klicken Sie auf die Schaltfläche, um ein neues Projekt zu erstellen, und geben Sie dann einen Projektnamen ein (z. B. rugged-terrain-ai).
  3. Klicken Sie auf Weiter.
  4. Überprüfen und akzeptieren Sie bei Aufforderung die Firebase-Nutzungsbedingungen und klicken Sie dann auf Weiter.
  5. (Optional) Aktivieren Sie die KI-Unterstützung in der Firebase Console (genannt „Gemini in Firebase“).
  6. Für dieses Codelab benötigen Sie kein Google Analytics. Deaktivieren Sie daher die Google Analytics-Option.
  7. Klicken Sie auf Projekt erstellen, warten Sie, bis Ihr Projekt bereitgestellt wurde, und klicken Sie dann auf Weiter.

Firebase-Tarif upgraden

Damit Sie die Firebase-Dienste in diesem Codelab verwenden können, muss für Ihr Firebase-Projekt der Pay-as-you-go-Tarif (Blaze) gelten. Das bedeutet, dass es mit einem Cloud-Rechnungskonto verknüpft ist.

So upgraden Sie Ihr Projekt auf den Blaze-Tarif:

  1. Wählen Sie in der Firebase Console aus, dass Sie Ihren Tarif upgraden möchten.
  2. Wählen Sie den Blaze-Tarif aus. Folgen Sie der Anleitung auf dem Bildschirm, um ein Cloud-Rechnungskonto mit Ihrem Projekt zu verknüpfen.
    Wenn Sie im Rahmen dieses Upgrades ein Cloud-Rechnungskonto erstellen mussten, müssen Sie möglicherweise zum Upgrade-Ablauf in der Firebase Console zurückkehren, um das Upgrade abzuschließen.

4. Firebase-Dienste einrichten und App verbinden

Für dieses Codelab müssen Sie Cloud Storage for Firebase und Firebase AI Logic in Ihrem Firebase-Projekt einrichten. Außerdem müssen Sie den Quellcode Ihrer App mit Ihrem Firebase-Projekt verbinden.

Cloud Storage for Firebase einrichten

In diesem Codelab werden Produktbeschreibungen in Cloud Storage for Firebase gespeichert.

  1. Rufen Sie in der Firebase Console Databases & Storage > Storage auf.
  2. Klicken Sie auf Jetzt starten.
  3. Wählen Sie einen Speicherort für Ihren Standard-Storage-Bucket aus.
    Für Buckets in US-WEST1, US-CENTRAL1 und US-EAST1 kann der kostenlose Tarif von Google Cloud Storage genutzt werden. Für Buckets an allen anderen Standorten gelten die Preise und die Nutzung von Google Cloud Storage.
  4. Klicken Sie auf Produktionsmodus. In den folgenden Schritten aktualisieren Sie diese Sicherheitsregeln, damit sie für dieses Codelab spezifisch sind.
  5. Klicken Sie auf Erstellen.
  6. Aktualisieren Sie Ihre Sicherheitsregeln:
    1. Wechseln Sie nach der Bereitstellung des Buckets zum Tab Regeln.
    2. Kopieren Sie die folgenden Regeln und fügen Sie sie ein:
      rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /products.txt {
      allow read;
    }
  }
}
    3. Klicken Sie auf Veröffentlichen.
  7. Laden Sie die Produktbeschreibungen aus dem Startcode hoch:
    1. Klicken Sie für Ihren Storage-Bucket auf den Tab Dateien.
    2. Klicken Sie auf Datei hochladen und laden Sie dann die products.txt Datei aus dem Startcode hoch. Diese Datei finden Sie unter src/data/products.txt.

Firebase AI Logic konfigurieren

Firebase AI Logic ist der wichtigste Firebase-Dienst, den Sie in diesem Codelab verwenden.

  1. Rufen Sie in der Firebase Console AI Services > AI Logic auf.
  2. Klicken Sie auf Jetzt starten.
  3. Klicken Sie auf der Karte Vertex AI Gemini API auf Erste Schritte mit dieser API und folgen Sie der Anleitung auf dem Bildschirm. In diesem Ablauf werden die erforderlichen APIs aktiviert, damit Sie Firebase AI Logic mit der Vertex AI Gemini API verwenden können.
  4. (Optional) Wählen Sie KI-Überwachung aktivieren aus, damit Sie verschiedene Messwerte und die Nutzung auf App-Ebene beobachten können, um umfassende Einblicke in Ihre Anfragen über Firebase AI Logic zu erhalten.

Code mit Firebase-Projekt verbinden

Im Rahmen der Einrichtung von Firebase AI Logic werden Sie aufgefordert, eine Firebase-Webanwendung zu erstellen und Ihre Konfiguration zu Ihrem Quellcode hinzuzufügen.

  1. Klicken Sie bei Aufforderung im Firebase AI Logic-Einrichtungsablauf auf das Symbol Web (), um eine neue Webanwendung zu registrieren.
  2. Geben Sie der App einen Namen (z. B. Rugged Web).
  3. Kopieren Sie das Objekt firebaseConfig aus der Einrichtungsanleitung.

Aktualisieren Sie als Nächstes den Startcode:

  1. Öffnen Sie in Ihrem Code-Editor src/firebase.ts.
  2. Ersetzen Sie die vorhandene firebaseConfig durch die, die Sie aus der Firebase Console kopiert haben.

Ihre Datei sollte nun in etwa so aussehen:

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. Serverseitige Prompt-Vorlage erstellen

Anstatt komplexe KI-Prompts in der Client-App fest zu codieren, verwenden Sie die Dotprompt-Syntax , um Anweisungen sicher auf dem Server zu verwalten.

So wird verhindert, dass Endnutzer die geheimen Regeln für das Entgegenkommen sehen.

  1. Rufen Sie in der Firebase Console den Bereich Vertex AI oder Prompt Management auf.
  2. Erstellen Sie eine neue Prompt-Vorlage und nennen Sie sie product-agent.
  3. Legen Sie das Modell auf gemini-2.5-flash fest.
  4. Definieren Sie das Eingabeschema genau so:
    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. Kopieren Sie den Inhalt von agent-product.prompt aus dem Stammverzeichnis in das Feld Prompt und optionale Systemanweisungen. Dadurch wird das Modell sicher angewiesen, sich als „Rugged Operator“ zu verhalten und den Produktkatalog einzufügen.
  6. Speichern und veröffentlichen Sie in der Firebase Console die Vorlage product-agent.

6. KI-Modell aufrufen

Nachdem die Vorlage sicher auf dem Server definiert wurde, müssen Sie sie nur noch über das Frontend Ihrer App aufrufen.

  1. Kehren Sie in Ihrem Code-Editor zu src/firebase.ts zurück.
  2. Verwenden Sie unter der Initialisierung getTemplateGenerativeModel, um eine Verbindung zur Vorlage herzustellen:
    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. Agent mit Firebase App Check schützen

KI-Modelle sind leistungsstark, können aber auch missbraucht werden, wenn öffentliche Endpunkte ungeschützt bleiben. Sie sollten immer Firebase App Check verwenden, um sicherzustellen, dass nur Ihre tatsächliche Webanwendung das generative Vertex AI-Modell aufrufen kann. Bots und nicht autorisierte Clients werden blockiert.

  1. Rufen Sie in der Firebase Console Build > App Check auf.
  2. Klicken Sie auf den Tab Apps , maximieren Sie Ihre Webanwendung (Rugged Web) und klicken Sie auf den Anbieter reCAPTCHA Enterprise.
  3. Wählen Sie Neuen reCAPTCHA Enterprise-Schlüssel erstellen aus und füllen Sie die Eingabeaufforderung aus:
    • Name: Codelab Key
    • Domains: Fügen Sie localhost und 127.0.0.1 hinzu, damit Ihr lokaler Vite-Server Anfragen senden kann.
  4. Klicken Sie auf Speichern , um die App zu registrieren.
  5. Nach der Registrierung wird in der Firebase Console Ihr Website-Schlüssel angezeigt. Kopieren Sie diese String.
  6. Öffnen Sie in Ihrem Code-Editor noch einmal src/firebase.ts.
  7. Fügen Sie oben die folgenden Importe hinzu:
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  8. Fügen Sie die App Check-Initialisierung direkt nach dem Aufruf von initializeApp(firebaseConfig) ein und fügen Sie den kopierten Website-Schlüssel ein:
    // Initialize App Check
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
  useLimitedUseAppCheckTokens: true
});
  9. Aktualisieren Sie den Aufruf der Funktion getAI(), um diese Tokens zu verwenden. Nehmen Sie die folgende Änderung vor:
    const ai = getAI(app, { backend: new VertexAIBackend(), useLimitedUseAppCheckTokens: true });
    Wenn Sie den Wert von useLimitedUseAppCheckTokens auf „true“ setzen, werden kurzlebige Tokens angewendet, um den Missbrauch Ihres Backends zu begrenzen.

8. Anwendung ausführen

Nachdem Sie die Firebase-Konfiguration eingerichtet und das Support-Chat-Widget verbunden haben, können Sie die Anwendung ausführen.

  1. Führen Sie in Ihrem Terminal den Vite-Entwicklungsserver aus:
    npm run dev
  2. Öffnen Sie die angegebene lokale URL (in der Regel http://localhost:5173/).
  3. Klicken Sie rechts unten auf die Floating Action Button (FAB) Tactical Support.
  4. Stellen Sie Fragen zu den Produkten, z. B.:
    • „Ich suche eine wetterfeste Jacke.“
    • „Meine Sub-Zero-Mütze ist defekt. Was kann ich tun?“
    • Drängen Sie weiter nach, um die Logik für das Entgegenkommen der KI auszulösen.

9. (Optional) Ressourcen aus Codelab bereinigen

Um mögliche Gebühren für Ihr Google Cloud-Rechnungskonto zu vermeiden, können Sie die in diesem Codelab erstellten Ressourcen löschen.

  1. Rufen Sie die Firebase Console auf.
  2. Wählen Sie das Projekt rugged-terrain-ai aus.
  3. Rufen Sie die Projekteinstellungen (Zahnradsymbol) auf.
  4. Scrollen Sie nach unten und klicken Sie auf Projekt löschen.
  5. Folgen Sie der Anleitung auf dem Bildschirm, um das Löschen zu bestätigen.

10. Glückwunsch!

🎊 Aufgabe abgeschlossen! Sie haben einen robusten, vorlagenbasierten KI-Kundensupport-Agenten integriert.

Erreichte Ziele:

  • Firebase und das Vertex AI-Backend in einer Client-App initialisiert.
  • Sichere serverseitige Prompt-Vorlage konfiguriert , mit Handlebars und strengen Eingabeschemas, um das komplexe Verhalten des Agenten zu definieren.
  • LLM dynamisch aufgerufen und Chatverlauf und kontextbezogene Produkt-IDs sicher übergeben, ohne die interne Prompt-Logik für den Client offenzulegen.

Nächste Schritte