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

1. Introduzione

In questo codelab, aggiungerai un widget di chat di assistenza clienti intelligente a un negozio di e-commerce di attrezzature per esterni 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 di budget di compensazione rigorose e utilizza dinamicamente il catalogo dei prodotti come contesto.

Passaggi:

  • Recupera il codice di avvio per l'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.
  • Una conoscenza di base di TypeScript e Node.js.
  • Un IDE o un editor di testo a tua scelta. Antigravity è un'ottima scelta.

2. Recupera il codice di avvio

  1. Nel terminale, clona il repository di avvio:
    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 del progetto (ad esempio, rugged-terrain-ai).
  3. Fai clic su Continua.
  4. Se ti viene richiesto, esamina e accetta i termini di Firebase, quindi fai clic su Continua.
  5. (Facoltativo) Abilita 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, quindi fai clic su Continua.

Esegui l'upgrade del piano tariffario di 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 le 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 i crediti Google Cloud per questo codelab, l'account di fatturazione è probabilmente denominato 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 completare l'upgrade.

4. Configura i servizi Firebase e connetti 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 dell'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 spazio di archiviazione > Spazio di archiviazione.
  2. Fai clic su Inizia.
  3. Seleziona una località 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 riportati di seguito, 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 di archiviazione.
    2. Fai clic su Carica file, quindi carica il file products.txt dal codice di avvio. Questo file è disponibile 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 abiliterà le API richieste per utilizzare Firebase AI Logic con l'API Gemini di Agent Platform.
  4. (Facoltativo) Seleziona Abilita il monitoraggio AI per poter osservare varie metriche e l'utilizzo a livello di app per ottenere una visibilità completa delle richieste tramite Firebase AI Logic.

Collega il codice al tuo 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.

Poi, aggiorna il codice di avvio:

  1. Nell'editor di codice, apri src/firebase.ts.
  2. Sostituisci l'oggetto 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 rigido 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 vedranno le regole segrete del "Budget di compensazione".

  1. Nella console Firebase, vai alla scheda Servizi AI > AI Logic > 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 la versione più recente disponibile).
  5. Dal codice di avvio fornito per questo codelab, copia i contenuti di product-agent.prompt (trova questo file nella directory principale). Poi, incolla questi contenuti nel campo Template di 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 "Operatore Rugged" 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 dell'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. Proteggi l'agente con Firebase App Check

I modelli di AI sono potenti, ma possono anche essere utilizzati in modo illecito 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 possa 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 della chiave di sito negli appunti.
  5. Nella console Firebase, vai a Sicurezza > App Check.
  6. Fai clic sulla scheda App , espandi l'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 Fraud Defense e fai clic su Salva.
  8. Nell'editor di codice, apri di nuovo src/firebase.ts.
  9. Aggiungi le seguenti importazioni nella parte superiore:
    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 di 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 alla 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 limitare l'utilizzo illecito che il backend potrebbe ricevere.

8. Esegui l'app

Ora che la configurazione di Firebase è a posto 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 (in genere http://localhost:5173/).
  3. Fai clic sul pulsante Azione mobile (FAB) Assistenza tattica nell'angolo in basso a destra.
  4. Prova a porre domande sui prodotti, ad esempio:
    • Cerco una giacca resistente agli agenti atmosferici
    • "Il mio berretto sub-zero è difettoso. Che cosa posso fare?"
    • Continua a insistere per attivare la logica del "Budget di compensazione" dell'AI.

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

Per evitare possibili addebiti sul 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 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 robusto basato su modelli.

Che cosa hai fatto:

  • Inizializza Firebase e il backend di Agent Platform in un'app client.
  • Configura un template di prompt lato server sicuro utilizzando Handlebars e schemi di input rigorosi per definire il comportamento complesso dell'agente.
  • Chiama dinamicamente un LLM passando in modo sicuro la cronologia delle chat e gli ID prodotto contestuali senza esporre la logica di prompt interna al client.

Passaggi successivi