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 Rolle der KI, strenge Regeln für Kulanzleistungen und den Produktkatalog dynamisch 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 aus 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 gegebenenfalls die Firebase-Nutzungsbedingungen und klicken Sie dann auf Weiter.
  5. (Optional) Aktivieren Sie die KI-Unterstützung in der Firebase Console (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 aktualisieren

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 aktualisieren Sie Ihr Projekt auf den Blaze-Tarif:

  1. Wählen Sie in der Firebase Console die Option zum Aktualisieren Ihres Tarifs aus.
  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 für dieses Codelab Google Cloud-Guthaben verwenden, heißt das Rechnungskonto wahrscheinlich Google Cloud Platform Trial Billing Account oder My Billing Account.
    • 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 Anwendung 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 Anwendung mit Ihrem Firebase-Projekt verbinden.

Cloud Storage for Firebase einrichten

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

  1. Wechseln Sie in der Firebase Console zu Datenbanken und Speicher > Speicher.
  2. Klicken Sie auf Jetzt starten.
  3. Wählen Sie einen Standort für Ihren Standard-Storage-Bucket aus.
    Für Buckets in US-WEST1, US-CENTRAL1 und US-EAST1 kann der kostenlose Tarif für 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. Wechseln Sie in der Firebase Console zu KI-Dienste > AI Logic.
  2. Klicken Sie auf Jetzt starten.
  3. Klicken Sie auf der Karte Agent Platform 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 Agent Platform Gemini API verwenden können.
  4. (Optional) Wählen Sie KI-Monitoring 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 zum Quellcode hinzuzufügen.

  1. Klicken Sie bei der entsprechenden Aufforderung im Einrichtungsworkflow von Firebase AI Logic auf das Symbol Web (), um eine neue Webanwendung zu registrieren.
  2. Geben Sie der Anwendung 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 Codeeditor 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, 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. 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 Kulanzbudget sehen.

  1. Wechseln Sie in der Firebase Console zur Registerkarte KI-Dienste > AI Logic > Prompt-Vorlagen.
  2. Klicken Sie auf Vorlage erstellen und wählen Sie Leere Vorlage aus.
  3. Legen Sie den Vorlagennamen auf Product Agent und die ID auf product-agent fest.
  4. Legen Sie das Modell auf gemini-3.1-flash-lite (oder die neueste verfügbare Version) fest.
  5. Kopieren Sie aus dem für dieses Codelab bereitgestellten Startcode den Inhalt von product-agent.prompt (diese Datei befindet sich im Stammverzeichnis). Fügen Sie diesen Inhalt dann in der Firebase Console in das Feld Prompt und (optionale) Systemanweisungen der Server-Prompt-Vorlage ein. Dieser Inhalt weist das Modell sicher an, wie es sich als „Rugged Operator“ verhalten und auf den Produktkatalog verweisen soll.
  6. Definieren Sie im Feld Testeingabe das Eingabeschema genau so:
    {
  "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. Klicken Sie auf Vorlage speichern , um die Vorlage product-agent zu speichern und zu veröffentlichen.

6. KI-Modell aufrufen

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

  1. Kehren Sie in Ihrem Codeeditor 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 erfolgreiche Anfragen an die Gemini API senden kann. Bots und nicht autorisierte Clients werden blockiert.

  1. Wechseln Sie in der Google Cloud Console zu Sicherheit > Fraud Defense
  2. Klicken Sie auf Schlüssel erstellen und füllen Sie die Felder aus:
    • Anzeigename: Codelab Key
    • Anwendungstyp: Web
    • Domainliste: Fügen Sie localhost und 127.0.0.1 hinzu, damit Ihr lokaler Vite-Server Anfragen senden darf.
  3. Klicken Sie auf Schlüssel erstellen , um den Schlüssel zu registrieren.
  4. Kopieren Sie oben auf der Seite mit den Details zum Fraud Defense-Schlüssel die ID des Websiteschlüssels in die Zwischenablage.
  5. Wechseln Sie in der Firebase Console zu Sicherheit > App Check.
  6. Klicken Sie auf den Tab Apps , maximieren Sie Ihre Webanwendung (Rugged Web) und klicken Sie auf den Anbieter reCAPTCHA Enterprise.
  7. Fügen Sie im Feld reCAPTCHA Enterprise-Websiteschlüssel die ID des Websiteschlüssels von der Seite mit den Details zum Fraud Defense-Schlüssel ein und klicken Sie auf Speichern.
  8. Öffnen Sie in Ihrem Codeeditor noch einmal src/firebase.ts.
  9. Fügen Sie oben die folgenden Importe hinzu:
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  10. Fügen Sie die App Check-Initialisierung direkt nach dem Aufruf von initializeApp(firebaseConfig) hinzu und fügen Sie die kopierte ID des Websiteschlüssels ein:
    // Initialize App Check
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
  isTokenAutoRefreshEnabled: true
});
  11. Aktualisieren Sie den Aufruf der Funktion getAI(), um diese Tokens zu verwenden. Nehmen Sie die folgende Änderung vor:
    const ai = getAI(app, { backend: new AgentPlatformBackend(), 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 Kulanzbudget 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 Ressourcen löschen, die während dieses Codelabs erstellt wurden.

  1. Wechseln Sie in der Firebase Console zur Registerkarte Einstellungen > Allgemein.
  2. Achten Sie darauf, dass das angezeigte Projekt das Projekt ist, das Sie für dieses Codelab verwendet haben. Wenn es sich nicht um das Projekt Ihres Codelabs handelt, können Sie das Projekt über die Projektauswahl oben links ändern.
  3. Scrollen Sie zum Ende der Seite und klicken Sie auf Projekt löschen.
  4. 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-Kundensupportagenten eingebunden.

Ergebnisse:

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

Nächste Schritte