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 asistencia al cliente inteligente a una tienda de comercio electrónico de equipos para exteriores llamada Rugged Terrain Guide. Usarás Firebase AI Logic para compilar este agente y aprenderás a configurar una plantilla de instrucciones del servidor (product-agent) que controla la personalidad de la IA, las reglas estrictas del presupuesto de apaciguamiento y usa de forma dinámica el catálogo de productos como contexto.

Actividades:

  • Obtén el código de partida para la app web de este codelab.
  • Configura un proyecto de Firebase.
  • Configura e inicializa 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
  • Conocimiento básico de TypeScript y Node.js
  • Un IDE o el editor de texto que prefieras Antigravity es una buena opción

2. Obtén el código de partida

  1. En tu terminal, clona el repositorio de partida:
    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. Crea un proyecto de Firebase

Crea un proyecto de Firebase

  1. Accede a la Firebase console con tu Cuenta de Google.
  2. Haz clic en el botón para crear un proyecto nuevo y, luego, ingresa un nombre de proyecto (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 tu proyecto 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.
  • Si es la primera vez que usas Firebase y Google Cloud, verifica si cumples con los requisitos para obtener un crédito de$300 y una cuenta de Facturación de Cloud de prueba gratuita.
  • Si realizas este codelab como parte de un evento, pregúntale al organizador si hay créditos de Cloud disponibles.

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 necesitas crear una cuenta de Facturación de Cloud como parte de esta actualización, es posible que debas volver a la 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

Este codelab usa Cloud Storage para Firebase para almacenar descripciones de productos.

  1. En Firebase console, ve a Bases de datos y almacenamiento > Almacenamiento.
  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 para este codelab.
  5. Haz clic en Crear.
  6. Actualiza tus reglas de seguridad:
    1. Después de 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 desde el código de partida. Este archivo se puede encontrar en: src/data/products.txt.

Configura Firebase AI Logic

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

  1. En Firebase console, ve a Servicios de IA > AI Logic.
  2. Haz clic en Comenzar.
  3. En la tarjeta Vertex AI Gemini API, haz clic en Comienza a usar esta API y sigue las instrucciones en pantalla. Este flujo habilitará las APIs necesarias para que uses Firebase AI Logic con la Vertex AI Gemini API.
  4. (Opcional) Selecciona Habilitar la supervisión de IA para que puedas observar varias métricas y el uso a nivel de la app para obtener una 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 solicitará que crees una aplicación 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 Web () para registrar una nueva aplicación web.
  2. Asigna un nombre a la app (por ejemplo, Rugged Web).
  3. Copia el objeto firebaseConfig de las instrucciones de configuración.

Luego, actualiza el código de partida:

  1. En tu 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, 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 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 las instrucciones de forma segura en el servidor.

De este modo, se evita que los usuarios finales vean las reglas secretas del "presupuesto de apaciguamiento".

  1. En Firebase console, navega a la sección Vertex AI o Administración de instrucciones.
  2. Crea una plantilla de instrucciones nueva y asígnale el nombre product-agent.
  3. Establece el modelo en gemini-2.5-flash.
  4. Define el esquema de entrada exactamente de la siguiente manera:
    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 el contenido de agent-product.prompt del directorio raíz en el campo Instrucciones del sistema opcionales y de instrucciones. Esto le indica de forma segura al modelo cómo comportarse como "operador resistente" y cómo insertar el catálogo de productos.
  6. En Firebase console, guarda y publica la plantilla product-agent.

6. Llama al modelo de IA

Ahora que la plantilla se define 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 llamar al modelo generativo de Vertex AI, bloquear bots y clientes no autorizados.

  1. En Firebase console, navega a Compilación > Verificación de aplicaciones.
  2. Haz clic en la pestaña Apps , expande tu app web (Rugged Web) y haz clic en el proveedor reCAPTCHA Enterprise.
  3. Selecciona Crear clave nueva de reCAPTCHA Enterprise y completa la solicitud:
    • Nombre: Codelab Key
    • Dominios: Agrega localhost y 127.0.0.1 para que tu servidor local de Vite pueda realizar solicitudes.
  4. Haz clic en Guardar para registrar la app.
  5. Una vez registrada, Firebase console mostrará tu clave del sitio. Copia esta cadena.
  6. En tu editor de código, vuelve a abrir src/firebase.ts.
  7. Agrega las siguientes importaciones en la parte superior:
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  8. Agrega la inicialización de la Verificación de aplicaciones justo después de la llamada a initializeApp(firebaseConfig) y pega la clave del sitio que copiaste:
    // Initialize App Check
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
  useLimitedUseAppCheckTokens: true
});
  9. Actualiza la llamada a la función getAI() para usar estos tokens. Realiza el siguiente cambio:
    const ai = getAI(app, { backend: new VertexAIBackend(), useLimitedUseAppCheckTokens: true });
    Si estableces el valor de useLimitedUseAppCheckTokens en verdadero, te aseguras de que se apliquen tokens de corta duración para ayudar a limitar el uso inadecuado que podría recibir tu backend.

8. Ejecuta la app

Con la configuración de Firebase en su lugar 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 (FAB) Asistencia táctica en la esquina inferior derecha.
  4. Intenta hacer preguntas sobre los productos, por ejemplo:
    • "Busco una carcasa resistente a la intemperie".
    • "Mi gorro para temperaturas bajo cero está defectuoso. ¿Qué puedo hacer?"
    • Sigue presionando para activar la lógica del "presupuesto de apaciguamiento" de la IA.

9. (Opcional) Limpia los recursos del codelab

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

  1. Dirígete a la Firebase console.
  2. Selecciona el proyecto rugged-terrain-ai.
  3. Ve a Configuración del proyecto (el ícono de ajustes).
  4. Desplázate hasta la parte inferior y haz clic en Borrar proyecto.
  5. Sigue las instrucciones en pantalla para confirmar la eliminación.

10. ¡Felicitaciones!

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

Logros:

  • Inicializaste Firebase y el backend de Vertex AI en una app cliente.
  • Configuraste una plantilla de instrucciones segura del servidor con Handlebars y esquemas de entrada estrictos para definir el comportamiento complejo del agente.
  • Llamaste de forma dinámica a un LLM pasando 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