Compila un agente de atención al cliente potenciado por IA con Firebase AI Logic

1. Introducción

En este codelab, agregarás un widget de chat de atención al cliente inteligente a una tienda de comercio electrónico de equipo para actividades al aire libre llamada Rugged Terrain Guide. Usarás Firebase AI Logic para compilar este agente y aprenderás a configurar una plantilla de instrucciones del lado del servidor (product-agent) que controla la personalidad de la IA, las reglas estrictas del presupuesto de compensación y usa de forma dinámica el catálogo de productos como contexto.

Actividades:

  • Obtén el código de partida de la app web de este codelab.
  • Configura un proyecto de Firebase.
  • Configurar e inicializar los servicios de Firebase (como Firebase AI Logic) en una app web
  • Configura una plantilla de instrucciones del servidor en Firebase console.
  • Accede a la plantilla desde una llamada al servicio de IA generativa desde un frontend de TypeScript similar a React.

Requisitos:

  • Un navegador web, como Chrome
  • Conocimientos básicos de TypeScript y Node.js
  • Un IDE o editor de texto de tu elección Antigravity es una buena opción.

2. Obtén el código de partida

  1. En tu terminal, clona el repositorio de inicio:
    git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
    
  2. Navega al directorio de código y luego instala las dependencias:
    cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab
    npm install
    

3. Configura un proyecto de Firebase:

Crea un proyecto de Firebase

  1. Accede a la consola de Firebase con tu Cuenta de Google.
  2. Haz clic en el botón para crear un proyecto nuevo y, luego, ingresa un nombre (por ejemplo, rugged-terrain-ai).
  3. Haz clic en Continuar.
  4. Si se te solicita, revisa y acepta las Condiciones de Firebase y, luego, haz clic en Continuar.
  5. (Opcional) Habilita la asistencia de IA en Firebase console (llamada "Gemini en Firebase").
  6. Para este codelab, no necesitas Google Analytics, por lo que debes desactivar la opción de Google Analytics.
  7. Haz clic en Crear proyecto, espera a que se aprovisione y, luego, haz clic en Continuar.

Actualiza tu plan de precios de Firebase

Para usar los servicios de Firebase en este codelab, tu proyecto de Firebase debe tener el plan de precios de pago por uso (Blaze), lo que significa que está vinculado a una cuenta de Facturación de Cloud.

  • Una cuenta de Facturación de Cloud requiere una forma de pago, como una tarjeta de crédito.
  • Durante las promociones especiales o si realizas este codelab como parte de un evento, es posible que haya créditos de Google Cloud disponibles.
  • Si es la primera vez que usas Firebase y Google Cloud, verifica si cumples con los requisitos para obtener un crédito de USD 300 y una cuenta de Facturación de Cloud de prueba gratuita.

Para actualizar tu proyecto al plan Blaze, sigue estos pasos:

  1. En Firebase console, selecciona la opción para actualizar tu plan.
  2. Selecciona el plan Blaze. Sigue las instrucciones en pantalla para vincular una cuenta de Facturación de Cloud a tu proyecto.
    • Si usas créditos de Google Cloud para este codelab, es probable que la cuenta de facturación se llame Google Cloud Platform Trial Billing Account o My Billing Account.
    • Si necesitas crear una cuenta de Facturación de Cloud como parte de esta actualización, es posible que debas volver al flujo de actualización en Firebase console para completar la actualización.

4. Configura los servicios de Firebase y conecta tu app

Para este codelab, debes configurar Cloud Storage para Firebase y Firebase AI Logic en tu proyecto de Firebase. También debes conectar el código fuente de tu app a tu proyecto de Firebase.

Configura Cloud Storage para Firebase

En este codelab, se usa Cloud Storage para Firebase para almacenar descripciones de productos.

  1. En Firebase console, ve a Bases de datos y almacenamiento > Storage.
  2. Haz clic en Comenzar.
  3. Selecciona una ubicación para tu bucket de Storage predeterminado.
    Los buckets de US-WEST1, US-CENTRAL1 y US-EAST1 pueden aprovechar el nivel “Siempre gratuito” para Google Cloud Storage. Los buckets de todas las demás ubicaciones siguen los precios y el uso de Google Cloud Storage.
  4. Haz clic en Modo de producción. En los pasos que se indican a continuación, actualizarás estas reglas de seguridad para que sean específicas de este codelab.
  5. Haz clic en Crear.
  6. Actualiza tus reglas de seguridad:
    1. Una vez que se aprovisione el bucket, ve a la pestaña Reglas.
    2. Copia y pega las siguientes reglas:
      rules_version = '2';
      service firebase.storage {
        match /b/{bucket}/o {
          match /products.txt {
            allow read;
          }
        }
      }
      
    3. Haz clic en Publicar.
  7. Sube las descripciones de los productos desde el código de partida:
    1. Haz clic en la pestaña Archivos de tu bucket de Storage.
    2. Haz clic en Subir archivo y, luego, sube el archivo products.txt del código de partida. Este archivo se encuentra en src/data/products.txt.

Configura Firebase AI Logic

Firebase AI Logic es el principal servicio de Firebase que usarás en este codelab.

  1. En Firebase console, ve a AI Services > AI Logic.
  2. Haz clic en Comenzar.
  3. En la tarjeta API de Gemini en Agent Platform, haz clic en Comenzar a usar esta API y sigue las instrucciones en pantalla. Este flujo habilitará las APIs necesarias para que uses Firebase AI Logic con la API de Gemini de Agent Platform.
  4. (Opcional) Selecciona Habilitar la supervisión de IA para observar varias métricas y el uso a nivel de la app, y obtener visibilidad integral de tus solicitudes a través de Firebase AI Logic.

Conecta tu código a tu proyecto de Firebase

Como parte de la configuración de Firebase AI Logic, se te pedirá que crees una app web de Firebase y que agregues tu configuración al código fuente.

  1. Cuando se te solicite en el flujo de configuración de Firebase AI Logic, haz clic en el ícono de Web () para registrar una nueva app web.
  2. Asigna un nombre a la app (por ejemplo, Rugged Web).
  3. Copia el objeto firebaseConfig de las instrucciones de configuración.

A continuación, actualiza el código de partida:

  1. En el editor de código, abre src/firebase.ts.
  2. Reemplaza el firebaseConfig existente por el que copiaste de Firebase console.

Tu archivo debería verse así:

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 la plantilla de instrucciones del servidor

En lugar de codificar de forma rígida instrucciones complejas de IA en la app cliente, usarás la sintaxis de Dotprompt para administrar instrucciones de forma segura en el servidor.

Esto evita que los usuarios finales vean las reglas secretas del "Presupuesto de compensación".

  1. En Firebase console, ve a la pestaña Plantillas de instrucciones de AI Services > AI Logic.
  2. Haz clic en Crear plantilla y elige Plantilla en blanco.
  3. Establece el nombre de la plantilla en Product Agent y el ID en product-agent.
  4. Establece el modelo en gemini-3.1-flash-lite (o la versión más reciente disponible).
  5. Desde el código de partida proporcionado para este codelab, copia el contenido de product-agent.prompt (encuentra este archivo en el directorio raíz). Luego, pega este contenido en el campo Instrucciones del sistema (opcional) y plantilla de instrucciones de la plantilla de instrucciones del servidor en Firebase console. Este contenido le indica de forma segura al modelo cómo comportarse como "Operador resistente" y hacer referencia al catálogo de productos.
  6. En el campo Entrada de prueba, define el esquema de entrada exactamente de la siguiente manera:
    {
      "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. Haz clic en Guardar plantilla para guardar y publicar la plantilla de product-agent.

6. Llama al modelo de IA

Ahora que la plantilla está definida de forma segura en el servidor, solo debes llamarla desde el frontend de tu app.

  1. En tu editor de código, vuelve a src/firebase.ts.
  2. Debajo de la inicialización, usa getTemplateGenerativeModel para conectarte a la plantilla:
    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. Protege el agente con la Verificación de aplicaciones de Firebase

Los modelos de IA son potentes, pero también se pueden usar de forma inadecuada si los extremos públicos no están protegidos. Siempre debes usar la Verificación de aplicaciones de Firebase para asegurarte de que solo tu app web real pueda realizar solicitudes exitosas a la API de Gemini, lo que bloqueará los bots y los clientes no autorizados.

  1. En la consola de Google Cloud, ve a Seguridad > Fraud Defense.
  2. Haz clic en Crear clave y completa los campos:
    • Nombre visible: Codelab Key
    • Tipo de aplicación: Web
    • Lista de dominios: Agrega localhost y 127.0.0.1 para que tu servidor local de Vite pueda realizar solicitudes.
  3. Haz clic en Crear clave para registrarla.
  4. En la parte superior de la página Detalles de la clave de Fraud Defense, copia el ID de la clave del sitio en el portapapeles.
  5. En Firebase console, ve a Seguridad > Verificación de aplicaciones.
  6. Haz clic en la pestaña Apps, expande tu app web (Rugged Web) y haz clic en el proveedor de reCAPTCHA Enterprise.
  7. En el campo Clave de sitio de reCAPTCHA Enterprise, pega el ID de la clave de sitio de la página de detalles de la clave de Fraud Defense y haz clic en Guardar.
  8. En el editor de código, vuelve a abrir src/firebase.ts.
  9. Agrega las siguientes importaciones en la parte superior:
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
    
  10. Agrega la inicialización de App Check justo después de la llamada a initializeApp(firebaseConfig) y pega el ID de la clave del sitio que copiaste:
    // Initialize App Check
    const appCheck = initializeAppCheck(app, {
      provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
      isTokenAutoRefreshEnabled: true
    });
    
  11. Actualiza la llamada a la función getAI() para usar estos tokens. Realiza el siguiente cambio:
    const ai = getAI(app, { backend: new AgentPlatformBackend(), useLimitedUseAppCheckTokens: true });
    
    Si configuras el valor de useLimitedUseAppCheckTokens como verdadero, te aseguras de que se apliquen tokens de corta duración para ayudar a limitar el abuso que podría recibir tu backend.

8. Ejecuta la app

Con la configuración de Firebase establecida y el widget de chat de asistencia conectado, es hora de ejecutar la app.

  1. En tu terminal, ejecuta el servidor de desarrollo de Vite:
    npm run dev
    
  2. Abre la URL local proporcionada (por lo general, http://localhost:5173/).
  3. Haz clic en el botón de acción flotante (BAF) Tactical Support en la esquina inferior derecha.
  4. Intenta hacer preguntas sobre los productos, por ejemplo:
    • "Busco una carcasa resistente a la intemperie".
    • "Mi gorro Sub-Zero está defectuoso. ¿Qué puedo hacer?"
    • Sigue rechazando la oferta para activar la lógica del "Presupuesto de compensación" de la IA.

9. Limpia los recursos del codelab (opcional)

Para evitar posibles cargos en tu cuenta de Facturación de Cloud, puedes borrar los recursos que creaste durante este codelab.

  1. En Firebase console, ve a la pestaña Configuración > General.
  2. Asegúrate de que el proyecto que estás viendo sea el que usaste para este codelab. Si no es el proyecto de tu codelab, puedes usar el menú desplegable del selector de proyectos en la esquina superior izquierda para cambiar de proyecto.
  3. Ve a la parte inferior de la página y, luego, haz clic en Borrar proyecto.
  4. Sigue las instrucciones en pantalla para confirmar la eliminación.

10. ¡Felicitaciones!

🎊 ¡Misión cumplida! Integraste correctamente un agente de asistencia al cliente potenciado por IA sólido y basado en plantillas.

Qué lograste:

  • Firebase inicializado y el backend de Agent Platform en una app cliente
  • Configuramos una plantilla de instrucciones segura del servidor con Handlebars y esquemas de entrada estrictos para definir el comportamiento complejo del agente.
  • Llama de forma dinámica a un LLM y pasa de forma segura el historial de chat y los IDs de productos contextuales sin exponer la lógica de instrucciones interna al cliente.

Próximos pasos