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 lado del servidor (product-agent) que controla la personalidad de la IA, las reglas estrictas de 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 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. Configura 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. En 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 el 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.
  • 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$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 a la actualización. en Firebase console para completar la actualización.

4. Configura los servicios de Firebase y conecta tu app

En 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 > Almacenamiento.
  2. Haz clic en Comenzar.
  3. Selecciona una ubicación para tu bucket de almacenamiento 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. 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 almacenamiento.
    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 API de Gemini de Agent Platform, haz clic en Comenzar con 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 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 a tu 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. Nombra 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 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, 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 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 esta manera, se evita que los usuarios finales vean las reglas secretas de "Presupuesto de apaciguamiento".

  1. En Firebase console, ve a la pestaña Servicios de IA > AI Logic > Plantillas de instrucciones.
  2. Haz clic en Crear plantilla y elige Plantilla en blanco.
  3. Establece el nombre de la plantilla como Product Agent y el ID como product-agent.
  4. Establece el modelo como gemini-3.1-flash-lite (o la versión más reciente disponible).
  5. En 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 de la instrucción 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 Probar entrada , 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 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 aplicación web real pueda realizar solicitudes correctas a la API de Gemini, bloqueando bots y 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 registrar la clave.
  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 aplicación web (Rugged Web) y haz clic en el proveedor reCAPTCHA Enterprise.
  7. En el campo Clave del sitio de reCAPTCHA Enterprise, pega el ID de la clave del sitio de la página de detalles de Fraud Defense y haz clic en Guardar.
  8. En tu 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 la Verificación de aplicaciones justo después de la llamada 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 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 (BAF) 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 de lana para temperaturas bajo cero está defectuoso. ¿Qué puedo hacer?"
    • Sigue presionando para activar la lógica de "Presupuesto de apaciguamiento" de la IA.

9. (Opcional) Limpia los recursos del codelab

Para evitar posibles cargos en tu cuenta de Facturación de Cloud, puedes borrar los recursos creados 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 del 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 de IA sólido basado en plantillas.

Logros:

  • Inicializaste Firebase y el backend de Agent Platform 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