Creare un agente di assistenza clienti basato sull'AI utilizzando Firebase AI Logic

1. Introduzione

In questo codelab, aggiungerai un widget di chat intelligente per l'assistenza clienti a un negozio di e-commerce di attrezzature per attività all'aperto chiamato Rugged Terrain Guide. Utilizzerai Firebase AI Logic per creare questo agente e imparerai a configurare un template di prompt lato server (product-agent) che gestisce il ruolo dell'AI, regole rigorose del budget di compensazione e utilizza dinamicamente il catalogo dei prodotti come contesto.

Passaggi:

  • Recupera il codice di avvio dell'app web di questo codelab.
  • Configura un progetto Firebase.
  • Configura e inizializza i servizi Firebase (come Firebase AI Logic) in un'app web.
  • Configura un modello di prompt lato server nella console Firebase.
  • Accedi al modello da una chiamata al servizio di AI generativa da un frontend TypeScript simile a React.

Di che cosa hai bisogno:

  • Un browser web come Chrome.
  • Conoscenza di base di TypeScript e Node.js.
  • Un IDE o un editor di testo a tua scelta. Antigravità è una buona scelta.

2. Recupera il codice di avvio

  1. Nel terminale, clona il repository iniziale:
    git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
    
  2. Vai alla directory del codice e installa le dipendenze:
    cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab
    npm install
    

3. Configura un progetto Firebase

Crea un progetto Firebase

  1. Accedi alla console Firebase utilizzando il tuo Account Google.
  2. Fai clic sul pulsante per creare un nuovo progetto, quindi inserisci un nome per il progetto (ad esempio, rugged-terrain-ai).
  3. Fai clic su Continua.
  4. Se richiesto, leggi e accetta i termini di Firebase e poi fai clic su Continua.
  5. (Facoltativo) Attiva l'assistenza AI nella console Firebase (denominata "Gemini in Firebase").
  6. Per questo codelab, non hai bisogno di Google Analytics, quindi disattiva l'opzione Google Analytics.
  7. Fai clic su Crea progetto, attendi il provisioning del progetto e poi fai clic su Continua.

Esegui l'upgrade del piano tariffario Firebase

Per utilizzare i servizi Firebase in questo codelab, il tuo progetto Firebase deve essere incluso nel piano tariffario con pagamento a consumo (Blaze), il che significa che è collegato a un account di fatturazione Cloud.

  • Un account di fatturazione Cloud richiede un metodo di pagamento, ad esempio una carta di credito.
  • Durante promozioni speciali o se stai svolgendo questo codelab nell'ambito di un evento, potrebbero essere disponibili crediti Google Cloud.
  • Se non hai mai utilizzato Firebase e Google Cloud, verifica se hai diritto a un credito di 300$e a un account di fatturazione Cloud per la prova senza costi.

Per eseguire l'upgrade del progetto al piano Blaze:

  1. Nella console Firebase, seleziona l'opzione per eseguire l'upgrade del piano.
  2. Seleziona il piano Blaze. Segui le istruzioni sullo schermo per collegare un account di fatturazione Cloud al tuo progetto.
    • Se utilizzi crediti Google Cloud per questo codelab, l'account di fatturazione si chiama probabilmente Google Cloud Platform Trial Billing Account o My Billing Account.
    • Se hai dovuto creare un account di fatturazione Cloud nell'ambito di questo upgrade, potresti dover tornare al flusso di upgrade nella console Firebase per completarlo.

4. Configurare i servizi Firebase e connettere l'app

Per questo codelab, devi configurare Cloud Storage for Firebase e Firebase AI Logic nel tuo progetto Firebase. Devi anche connettere il codice sorgente della tua app al tuo progetto Firebase.

Configura Cloud Storage for Firebase

Questo codelab utilizza Cloud Storage for Firebase per archiviare le descrizioni dei prodotti.

  1. Nella console Firebase, vai a Database e archiviazione > Storage.
  2. Fai clic su Inizia.
  3. Seleziona una posizione per il bucket di archiviazione predefinito.
    I bucket in US-WEST1, US-CENTRAL1 e US-EAST1 possono usufruire del livello "Sempre senza costi" per Google Cloud Storage. I bucket in tutte le altre località seguono i prezzi e l'utilizzo di Google Cloud Storage.
  4. Fai clic su Modalità di produzione. Nei passaggi successivi, aggiornerai queste regole di sicurezza in modo che siano specifiche per questo codelab.
  5. Fai clic su Crea.
  6. Aggiorna le regole di sicurezza:
    1. Dopo il provisioning del bucket, vai alla scheda Regole.
    2. Copia e incolla le seguenti regole:
      rules_version = '2';
      service firebase.storage {
        match /b/{bucket}/o {
          match /products.txt {
            allow read;
          }
        }
      }
      
    3. Fai clic su Pubblica.
  7. Carica le descrizioni dei prodotti dal codice di avvio:
    1. Fai clic sulla scheda File per il bucket Storage.
    2. Fai clic su Carica file e poi carica il file products.txt dal codice di avvio. Questo file si trova in: src/data/products.txt.

Configura Firebase AI Logic

Firebase AI Logic è il servizio Firebase principale che utilizzerai in questo codelab.

  1. Nella console Firebase, vai a Servizi AI > AI Logic.
  2. Fai clic su Inizia.
  3. Nella scheda API Gemini di Agent Platform, fai clic su Inizia a utilizzare questa API e segui le istruzioni sullo schermo. Questo flusso attiverà le API richieste per utilizzare Firebase AI Logic con l'API Gemini di Agent Platform.
  4. (Facoltativo) Seleziona per abilitare il monitoraggio AI in modo da poter osservare varie metriche e l'utilizzo a livello di app per ottenere una visibilità completa delle tue richieste tramite Firebase AI Logic.

Connettere il codice al progetto Firebase

Nell'ambito della configurazione di Firebase AI Logic, ti verrà chiesto di creare un'app web Firebase e di aggiungere la configurazione al codice sorgente.

  1. Quando ti viene richiesto nel flusso di configurazione di Firebase AI Logic, fai clic sull'icona Web () per registrare una nuova app web.
  2. Assegna un nome all'app (ad esempio, Rugged Web).
  3. Copia l'oggetto firebaseConfig dalle istruzioni di configurazione.

Successivamente, aggiorna il codice di avvio:

  1. Nell'editor di codice, apri src/firebase.ts.
  2. Sostituisci il valore firebaseConfig esistente con quello copiato dalla console Firebase.

Il file dovrebbe avere il seguente aspetto:

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. Crea il template di prompt lato server

Anziché codificare in modo permanente prompt AI complessi nell'app client, utilizzerai la sintassi Dotprompt per gestire le istruzioni in modo sicuro sul server.

In questo modo, gli utenti finali non vedono le regole segrete del "Budget di compensazione".

  1. Nella console Firebase, vai alla scheda Servizi AI > Logica AI > Modelli di prompt.
  2. Fai clic su Crea modello e scegli Modello vuoto.
  3. Imposta il nome del modello su Product Agent e l'ID su product-agent.
  4. Imposta il modello su gemini-3.1-flash-lite (o l'ultima versione disponibile).
  5. Dal codice di avvio fornito per questo codelab, copia i contenuti di product-agent.prompt (trova questo file nella directory root). Poi, incolla questo contenuto nel campo Prompt e istruzioni di sistema (facoltative) del modello di prompt del server nella console Firebase. Questi contenuti indicano in modo sicuro al modello come comportarsi come "Rugged Operator" e fare riferimento al catalogo dei prodotti.
  6. Nel campo Input di test definisci lo schema di input esattamente come segue:
    {
      "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. Fai clic su Salva modello per salvare e pubblicare il modello product-agent.

6. Chiama il modello di AI

Ora che il modello è definito in modo sicuro sul server, devi solo chiamarlo dal frontend della tua app.

  1. Nell'editor di codice, torna a src/firebase.ts.
  2. Sotto l'inizializzazione, utilizza getTemplateGenerativeModel per connetterti al modello:
    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. Proteggere l'agente con Firebase App Check

I modelli di AI sono potenti, ma possono anche essere usati in modo improprio se gli endpoint pubblici non sono protetti. Devi sempre utilizzare Firebase App Check per assicurarti che solo la tua app web effettiva possa effettuare richieste riuscite all'API Gemini, bloccando bot e client non autorizzati.

  1. Nella console Google Cloud, vai a Sicurezza > Fraud Defense.
  2. Fai clic su Crea chiave e compila i campi:
    • Nome visualizzato: Codelab Key
    • Tipo di applicazione: web
    • Elenco di domini: aggiungi localhost e 127.0.0.1 in modo che il server Vite locale sia autorizzato a effettuare richieste.
  3. Fai clic su Crea chiave per registrare la chiave.
  4. Nella parte superiore della pagina Dettagli chiave Fraud Defense, copia l'ID chiave del sito negli appunti.
  5. Nella console Firebase, vai a Sicurezza > App Check.
  6. Fai clic sulla scheda App, espandi la tua app web (Rugged Web) e fai clic sul provider reCAPTCHA Enterprise.
  7. Nel campo Chiave di sito reCAPTCHA Enterprise, incolla l'ID della chiave di sito dalla pagina dei dettagli di Fraud Defense e fai clic su Salva.
  8. Nell'editor di codice, apri di nuovo src/firebase.ts.
  9. Aggiungi le seguenti importazioni all'inizio:
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
    
  10. Aggiungi l'inizializzazione di App Check subito dopo la chiamata initializeApp(firebaseConfig) e incolla l'ID della chiave del sito che hai copiato:
    // Initialize App Check
    const appCheck = initializeAppCheck(app, {
      provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
      isTokenAutoRefreshEnabled: true
    });
    
  11. Aggiorna la chiamata di funzione getAI() per utilizzare questi token. Apporta la seguente modifica:
    const ai = getAI(app, { backend: new AgentPlatformBackend(), useLimitedUseAppCheckTokens: true });
    
    Se imposti il valore di useLimitedUseAppCheckTokens su true, ti assicuri che i token di breve durata vengano applicati per contribuire a limitare gli abusi che il tuo backend potrebbe ricevere.

8. Esegui l'app

Con la configurazione di Firebase in posizione e il widget di chat di assistenza collegato, è il momento di eseguire l'app.

  1. Nel terminale, esegui il server di sviluppo Vite:
    npm run dev
    
  2. Apri l'URL locale fornito (di solito http://localhost:5173/).
  3. Fai clic sul Floating Action Button (FAB) Supporto tattico nell'angolo in basso a destra.
  4. Prova a fare domande sui prodotti, ad esempio:
    • "Sto cercando un guscio resistente alle intemperie"
    • "Il mio berretto Sub-Zero è difettoso. Che cosa posso fare?"
    • Continua a respingere per attivare la logica del "budget di pacificazione " dell'AI.

9. (Facoltativo) Esegui la pulizia delle risorse del codelab

Per evitare possibili addebiti al tuo account di fatturazione Google Cloud, puoi eliminare le risorse create durante questo codelab.

  1. Nella console Firebase, vai alla scheda Impostazioni > Generali.
  2. Assicurati che il progetto che stai visualizzando sia quello che hai utilizzato per questo codelab. Se non è il progetto del tuo codelab, puoi utilizzare il menu a discesa del selettore di progetti nell'angolo in alto a sinistra per cambiare progetto.
  3. Vai in fondo alla pagina e fai clic su Elimina progetto.
  4. Segui le istruzioni sullo schermo per confermare l'eliminazione.

10. Complimenti!

🎊 Missione completata. Hai integrato correttamente un agente di assistenza clienti AI solido e basato su modelli.

Cosa hai ottenuto:

  • Firebase inizializzato e il backend di Agent Platform in un'app client.
  • Configurato un template di prompt lato server sicuro utilizzando Handlebars e schemi di input rigorosi per definire il comportamento complesso dell'agente.
  • Chiamata dinamica di un LLM che trasmette in modo sicuro la cronologia della chat e gli ID prodotto contestuali senza esporre la logica del prompt interno al client.

Passaggi successivi