Créer un agent de service client optimisé par l'IA à l'aide de Firebase AI Logic

1. Introduction

Dans cet atelier de programmation, vous allez ajouter un widget de chat intelligent pour l'assistance client à une boutique en ligne d'articles de plein air appelée Rugged Terrain Guide. Vous utiliserez Firebase AI Logic pour créer cet agent et vous apprendrez à configurer un modèle de prompt côté serveur (product-agent) qui gère le persona de l'IA, des règles strictes de budget d'apaisement et utilise dynamiquement le catalogue de produits comme contexte.

Opérations à effectuer :

  • Obtenir le code de démarrage pour l'application Web de cet atelier de programmation
  • Configurer un projet Firebase
  • Configurer et initialiser les services Firebase (comme Firebase AI Logic) dans une application Web
  • Configurer un modèle de prompt côté serveur dans la console Firebase
  • Accéder au modèle à partir d'un appel au service d'IA générative depuis un frontend TypeScript de type React

Ce dont vous avez besoin :

  • Un navigateur Web tel que Chrome
  • Des connaissances de base en TypeScript et Node.js
  • Un IDE ou un éditeur de texte de votre choix Antigravity est un bon choix.

2. Télécharger le code de démarrage

  1. Dans votre terminal, clonez le dépôt de démarrage :
    git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
  2. Accédez au répertoire de code et installez les dépendances :
    cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab
npm install

3. Configurer un projet Firebase

Créer un projet Firebase

  1. Connectez-vous à la console Firebase avec votre compte Google.
  2. Cliquez sur le bouton pour créer un projet, puis saisissez un nom de projet (par exemple, rugged-terrain-ai).
  3. Cliquez sur Continuer.
  4. Si vous y êtes invité, lisez et acceptez les conditions d'utilisation de Firebase, puis cliquez sur Continuer.
  5. (Facultatif) Activez l'assistance IA dans la console Firebase (appelée "Gemini dans Firebase").
  6. Pour cet atelier de programmation, vous n'avez pas besoin de Google Analytics. Désactivez donc l'option Google Analytics.
  7. Cliquez sur Créer un projet, attendez que votre projet soit provisionné, puis cliquez sur Continuer.

Mettre à niveau votre forfait Firebase

Pour utiliser les services Firebase dans cet atelier de programmation, votre projet Firebase doit être associé au forfait Blaze (paiement à l'utilisation), ce qui signifie qu'il est associé à un compte de facturation Cloud.

  • Un compte de facturation Cloud nécessite un mode de paiement, comme une carte de crédit.
  • Lors de promotions spéciales ou si vous suivez cet atelier de programmation dans le cadre d'un événement, des crédits Google Cloud peuvent être disponibles.
  • Si vous débutez avec Firebase et Google Cloud, vérifiez si vous êtes éligible à un crédit de 300 $ et à un compte de facturation Cloud d'essai sans frais.

Pour passer votre projet au forfait Blaze, procédez comme suit :

  1. Dans la console Firebase, sélectionnez pour mettre à niveau votre forfait.
  2. Sélectionnez le forfait Blaze. Suivez les instructions à l'écran pour associer un compte de facturation Cloud à votre projet.
    • Si vous utilisez des crédits Google Cloud pour cet atelier de programmation, le compte de facturation s'appelle probablement Google Cloud Platform Trial Billing Account ou My Billing Account.
    • Si vous avez dû créer un compte de facturation Cloud dans le cadre de cette mise à niveau, vous devrez peut-être revenir au processus de mise à niveau dans la console Firebase pour terminer la mise à niveau.

4. Configurer les services Firebase et associer votre application

Pour cet atelier de programmation, vous devez configurer Cloud Storage for Firebase et Firebase AI Logic dans votre projet Firebase. Vous devez également associer le code source de votre application à votre projet Firebase.

Configurer Cloud Storage for Firebase

Cet atelier de programmation utilise Cloud Storage for Firebase pour stocker les descriptions de produits.

  1. Dans la console Firebase, accédez à Bases de données et stockage > Stockage.
  2. Cliquez sur Commencer.
  3. Sélectionnez un emplacement pour votre bucket Storage par défaut.
    Les buckets situés dans les régions US-WEST1, US-CENTRAL1, et US-EAST1 peuvent bénéficier du niveau "Toujours sans frais" pour Google Cloud Storage. Les buckets situés dans toutes les autres régions sont soumis aux tarifs et à l'utilisation de Google Cloud Storage.
  4. Cliquez sur Mode production. Dans les étapes ci-dessous, vous allez modifier ces règles de sécurité pour qu'elles soient spécifiques à cet atelier de programmation.
  5. Cliquez sur Créer.
  6. Modifiez vos règles de sécurité :
    1. Une fois le bucket provisionné, accédez à l'onglet Règles.
    2. Copiez les règles suivantes, puis collez-les :
      rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /products.txt {
      allow read;
    }
  }
}
    3. Cliquez sur Publier.
  7. Importez les descriptions de produits à partir du code de démarrage :
    1. Cliquez sur l'onglet Fichiers de votre bucket Storage.
    2. Cliquez sur Importer un fichier, puis importez le fichier products.txt à partir du code de démarrage. Ce fichier se trouve à l'adresse suivante : src/data/products.txt.

Configurer Firebase AI Logic

Firebase AI Logic est le principal service Firebase que vous utiliserez dans cet atelier de programmation.

  1. Dans la console Firebase, accédez à Services d'IA > AI Logic.
  2. Cliquez sur Commencer.
  3. Sur la fiche Agent Platform Gemini API , cliquez sur Commencer avec cette API , puis suivez les instructions à l'écran. Ce processus vous permettra d'activer les API requises pour utiliser Firebase AI Logic avec l'API Agent Platform Gemini.
  4. (Facultatif) Sélectionnez Activer la surveillance de l'IA pour pouvoir observer diverses métriques et utilisations au niveau de l'application afin d'obtenir une visibilité complète sur vos requêtes via Firebase AI Logic.

Associer votre code à votre projet Firebase

Lors de la configuration de Firebase AI Logic, vous serez invité à créer une application Web Firebase et à ajouter votre configuration à votre code source.

  1. Lorsque vous y êtes invité dans le processus de configuration de Firebase AI Logic, cliquez sur l'icône Web () pour enregistrer une nouvelle application Web.
  2. Nommez l'application (par exemple, Rugged Web).
  3. Copiez l'objet firebaseConfig à partir des instructions de configuration.

Ensuite, modifiez le code de démarrage :

  1. Dans votre éditeur de code, ouvrez src/firebase.ts.
  2. Remplacez le firebaseConfig existant par celui que vous avez copié depuis la console Firebase.

Votre fichier devrait se présenter comme suit :

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. Créer le modèle de prompt côté serveur

Au lieu de coder en dur des prompts d'IA complexes dans l'application cliente, vous utiliserez la syntaxe Dotprompt pour gérer les instructions de manière sécurisée sur le serveur.

Cela empêche les utilisateurs finaux de voir les règles secrètes du "budget d'apaisement".

  1. Dans la console Firebase, accédez à l'onglet Services d'IA > AI Logic > Modèles de prompts.
  2. Cliquez sur Créer un modèle, puis sélectionnez Modèle vide.
  3. Définissez le nom du modèle sur Product Agent et l'ID sur product-agent.
  4. Définissez le modèle sur gemini-3.1-flash-lite (ou la dernière version disponible).
  5. À partir du code de démarrage fourni pour cet atelier de programmation, copiez le contenu de product-agent.prompt (recherchez ce fichier dans le répertoire racine). Collez ensuite ce contenu dans le champ Prompt et instructions système (facultatif) du modèle de prompt du serveur dans la console Firebase. Ce contenu indique de manière sécurisée au modèle comment se comporter en tant qu'"opérateur Rugged" et comment référencer le catalogue de produits.
  6. Dans le champ Test input (Tester l'entrée), définissez le schéma d'entrée exactement comme suit :
    {
  "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. Cliquez sur Enregistrer le modèle pour enregistrer et publier le modèle product-agent.

6. Appeler le modèle d'IA

Maintenant que le modèle est défini de manière sécurisée sur le serveur, il vous suffit de l'appeler depuis le frontend de votre application.

  1. Dans votre éditeur de code, revenez à src/firebase.ts.
  2. Sous l'initialisation, utilisez getTemplateGenerativeModel pour vous connecter au modèle :
    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. Sécuriser l'agent avec Firebase App Check

Les modèles d'IA sont puissants, mais ils peuvent également être utilisés de manière abusive si les points de terminaison publics ne sont pas protégés. Vous devez toujours utiliser Firebase App Check pour vous assurer que seule votre application Web réelle peut envoyer des requêtes à l'API Gemini, en bloquant les robots et les clients non autorisés.

  1. Dans la console Google Cloud, accédez à Sécurité > Fraud Defense
  2. Cliquez sur Créer une clé et remplissez les champs :
    • Display name (Nom à afficher) : Codelab Key
    • Application Type (Type d'application) : Web
    • Liste de domaines : ajoutez localhost et 127.0.0.1 pour que votre serveur Vite local soit autorisé à envoyer des requêtes.
  3. Cliquez sur Créer une clé pour enregistrer la clé.
  4. En haut de la page d'informations Fraud Defense Key Details, copiez l'ID de la clé de site dans votre presse-papiers.
  5. Dans la console Firebase, accédez à Sécurité > App Check.
  6. Cliquez sur l'onglet Applications, développez votre application Web (Rugged Web), puis cliquez sur le fournisseur reCAPTCHA Enterprise.
  7. Dans le champ reCAPTCHA Enterprise site key (Clé de site reCAPTCHA Enterprise), collez l'ID de la clé de site de la page "Fraud Defense Key Details" (Détails de la clé Fraud Defense), puis cliquez sur Enregistrer.
  8. Dans votre éditeur de code, ouvrez à nouveau src/firebase.ts.
  9. Ajoutez les importations suivantes en haut :
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  10. Ajoutez l'initialisation d'App Check juste après votre appel initializeApp(firebaseConfig), puis collez l'ID de la clé de site que vous avez copié :
    // Initialize App Check
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
  isTokenAutoRefreshEnabled: true
});
  11. Modifiez votre appel de fonction getAI() pour utiliser ces jetons. Apportez la modification suivante :
    const ai = getAI(app, { backend: new AgentPlatformBackend(), useLimitedUseAppCheckTokens: true });
    En définissant la valeur de useLimitedUseAppCheckTokens sur "true", vous vous assurez que des jetons à courte durée de vie sont appliqués pour limiter les utilisations abusives que votre backend pourrait recevoir.

8. Exécuter l'application

Maintenant que votre configuration Firebase est en place et que le widget de chat d'assistance est configuré, il est temps d'exécuter l'application.

  1. Dans votre terminal, exécutez le serveur de développement Vite :
    npm run dev
  2. Ouvrez l'URL locale fournie (généralement http://localhost:5173/).
  3. Cliquez sur le bouton d'action flottant Tactical Support (Assistance tactique) en bas à droite.
  4. Essayez de poser des questions sur les produits, par exemple :
    • "Je recherche une veste imperméable."
    • "Mon bonnet grand froid est défectueux. Que puis-je faire ?"
    • Continuez à insister pour déclencher la logique de "budget d'apaisement" de l'IA.

9. (Facultatif) Nettoyer les ressources de l'atelier de programmation

Pour éviter d'éventuels frais sur votre compte de facturation Google Cloud, vous pouvez supprimer les ressources créées lors de cet atelier de programmation.

  1. Dans la console Firebase, accédez à l'onglet Paramètres > Général.
  2. Assurez-vous que le projet que vous consultez est celui que vous avez utilisé pour cet atelier de programmation. Si ce n'est pas le cas, vous pouvez utiliser le menu déroulant du sélecteur de projet en haut à gauche pour changer de projet.
  3. Accédez au bas de la page, puis cliquez sur Supprimer le projet.
  4. Suivez les instructions à l'écran pour confirmer la suppression.

10. Félicitations !

🎊 Mission accomplie ! Vous avez intégré un agent d'assistance client d'IA robuste basé sur un modèle.

Ce que vous avez accompli :

  • Initialisation de Firebase et du backend Agent Platform sur une application cliente
  • Configuration d'un modèle de prompt côté serveur sécurisé à l'aide de Handlebars et de schémas d'entrée stricts pour définir le comportement complexe de l'agent
  • Appel dynamique d'un LLM transmettant de manière sécurisée l'historique des chats et les ID de produits contextuels sans exposer la logique de prompt interne au client

Étape suivante

  • Firebase App Check : protégez vos points de terminaison d'IA contre les utilisations abusives.