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 attività all'aperto chiamato Rugged Terrain Guide. Utilizzerai Firebase AI Logic per creare questo agente e imparerai a configurare un modello di prompt lato server (product-agent) che gestisce il ruolo dell'AI, regole rigorose per il 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, quindi 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.

Eseguire l'upgrade del piano tariffario Firebase

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

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 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 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 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 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 Vertex AI Gemini, 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 Vertex AI Gemini.
  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.

Collegare 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.

Poi 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, 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. Crea il modello 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 sezione Vertex AI o Gestione prompt.
  2. Crea un nuovo modello di prompt e chiamalo product-agent.
  3. Imposta il modello su gemini-2.5-flash.
  4. Definisci lo schema di input esattamente come segue:
    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. Copia i contenuti di agent-product.prompt dalla directory principale nel campo Prompt e istruzioni di sistema facoltative. In questo modo, il modello viene istruito in modo sicuro su come comportarsi come "operatore robusto" e viene inserito il catalogo dei prodotti.
  6. Nella console Firebase, salva e pubblica 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 chiamare il modello generativo Vertex AI, bloccando bot e client non autorizzati.

  1. Nella console Firebase, vai a Build > App Check.
  2. Fai clic sulla scheda App, espandi la tua app web (Rugged Web) e fai clic sul provider reCAPTCHA Enterprise.
  3. Seleziona Crea nuova chiave reCAPTCHA Enterprise e compila la richiesta:
    • Nome: Codelab Key
    • Domini: aggiungi localhost e 127.0.0.1 in modo che il server Vite locale possa effettuare richieste.
  4. Fai clic su Salva per registrare l'app.
  5. Una volta registrata, la console Firebase mostrerà la chiave del sito. Copia questa stringa.
  6. Nell'editor di codice, apri di nuovo src/firebase.ts.
  7. Aggiungi le seguenti importazioni nella parte superiore:
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  8. Aggiungi l'inizializzazione di App Check subito dopo la chiamata initializeApp(firebaseConfig) e incolla la chiave del sito che hai copiato:
    // Initialize App Check
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
  useLimitedUseAppCheckTokens: true
});
  9. Aggiorna la chiamata di funzione getAI() per utilizzare questi token. Apporta la seguente modifica:
    const ai = getAI(app, { backend: new VertexAIBackend(), 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 pulsante di azione rapida (FAB) Supporto tattico nell'angolo in basso a destra.
  4. Prova a fare domande sui prodotti, ad esempio:
    • Cerco una giacca esterna impermeabile
    • Il mio berretto per temperature sotto zero è difettoso. 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. Vai alla Console Firebase.
  2. Seleziona il progetto rugged-terrain-ai.
  3. Vai a Impostazioni progetto (l'icona a forma di ingranaggio).
  4. Scorri fino in fondo e fai clic su Elimina progetto.
  5. 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:

  • Inizializzato Firebase e il backend Vertex AI in un'app client.
  • Configurato un modello 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