English version: This codelab is also available in English.
En la era de la IA generativa, ya no basta con construir chatbots que solo hablan. El mercado actual demanda agentes de IA: sistemas capaces de razonar, utilizar herramientas externas y seguir reglas de negocio.
En este taller práctico, vamos a construir un asistente de Smart Retail. Utilizaremos Genkit, el framework de Google diseñado para llevar a la IA a entornos de producción con la seguridad y escalabilidad que caracteriza al ecosistema de Firebase.
A lo largo de este codelab, aprenderás a utilizar diferentes LLMs para que actúen como un asistente de compras experto y confiable.
Un asistente inteligente que:
Código Fuente: Puedes encontrar la solución final en workshop-genkit-agents
Primero, preparemos el terreno.
Crear carpeta:
mkdir workshop-genkit-agents-101 && cd workshop-genkit-agents-101
Inicializar el proyecto de Node.js, instalar TypeScript y crear la estructura base con carpetas dedicadas para flujos (src/flows) y herramientas (src/tools):
# Inicializar un nuevo proyecto de Node.js
npm init -y
npm pkg set type=module
# Instalar y configurar TypeScript
npm install -D typescript tsx
npx tsc --init
# Crear la estructura de directorios del código fuente
mkdir -p src/flows src/tools
touch src/genkit.ts src/index.ts
Primero, instala la CLI de Genkit globalmente. Esto te dará acceso a las herramientas de desarrollo locales, incluida la interfaz de usuario para desarrolladores:
npm install -g genkit-cli
A continuación, añade los siguientes paquetes a tu proyecto:
npm install genkit @genkit-ai/google-genai
genkit — Proporciona las funcionalidades principales de Genkit.@genkit-ai/google-genai — Proporciona acceso a los modelos Gemini de Google AI.Genkit puede trabajar con varios proveedores de modelos. Este taller utiliza la API de Gemini, que ofrece un generoso plan gratuito y no requiere tarjeta de crédito para empezar.
Para usarla, necesitarás una clave API de Google AI Studio:
Una vez que tengas tu clave, configura la variable de entorno GOOGLE_GENAI_API_KEY:
export GOOGLE_GENAI_API_KEY=<tu clave API>
Para mantener nuestro proyecto modular y ordenado, centralizaremos la configuración de Genkit en src/genkit.ts. Así todos nuestros flujos y herramientas podrán reutilizar la misma instancia ai.
Añade lo siguiente a src/genkit.ts:
import { googleAI } from '@genkit-ai/google-genai';
import { genkit } from 'genkit';
export const ai = genkit({
plugins: [googleAI()],
model: googleAI.model('gemini-2.5-flash'),
});
Un flujo (Flow) es una función especial de Genkit con observabilidad integrada, seguridad de tipos e integración de herramientas.
Crea el archivo src/flows/basicScoutFlow.ts con lo siguiente:
import { ai } from '../genkit';
export const basicScoutFlow = ai.defineFlow(
{
name: 'basicScoutFlow',
},
async (productType) => {
const { text } = await ai.generate(
`Eres un experto en retail. Dame los detalles de este producto: ${productType}`
);
return text;
}
);
Ahora, regístralo exportándolo en src/index.ts:
export * from './flows/basicScoutFlow';
Este ejemplo de código:
gemini-2.5-flash en src/genkit.ts.src/flows/basicScoutFlow.ts para generar una respuesta basada en su entrada.src/index.ts para que la Developer UI de Genkit lo detecte automáticamente.La interfaz de usuario para desarrolladores es una herramienta local para probar e inspeccionar componentes de Genkit, como flujos, mediante una interfaz visual.
Iniciar la interfaz de usuario para desarrolladores
Se requiere la CLI de Genkit para ejecutar la interfaz de usuario para desarrolladores. Si seguiste los pasos de instalación anteriores, ya la tienes instalada.
Ejecuta el siguiente comando desde la raíz de tu proyecto:
genkit start -- npx tsx --watch src/index.ts
Abre http://localhost:4000 en tu navegador.
En la barra lateral, haz clic en Flows y selecciona basicScoutFlow.
Escribe un producto (ej. "iPhone 15") y presiona Run.
Cuando conectamos un agente a una aplicación web o móvil, necesitamos respuestas en JSON predecibles en lugar de texto libre.
Crea un nuevo archivo src/flows/structuredScoutFlow.ts:
import { z } from 'genkit';
import { ai } from '../genkit';
const ProductDetailsSchema = z.object({
name: z.string(),
brand: z.string(),
features: z.array(z.string()),
recommendation_text: z.string(),
});
export const structuredScoutFlow = ai.defineFlow(
{
name: 'structuredScoutFlow',
inputSchema: z.string(),
outputSchema: ProductDetailsSchema,
},
async (productName) => {
const { output } = await ai.generate({
prompt: `Eres un experto en retail. Dame los detalles de este producto: ${productName}`,
output: { schema: ProductDetailsSchema },
});
if (!output) throw new Error("La IA no pudo generar el formato correcto.");
return output;
}
);
Y expórtalo en tu archivo src/index.ts:
export * from './flows/basicScoutFlow';
export * from './flows/structuredScoutFlow';
output.brand con autocompletado)."recommendation_text" sugieren si el producto te conviene o no.Vuelve a la Developer UI (localhost:4000). Verás que ahora aparece structuredScoutFlow. Al ejecutarlo, notarás que la respuesta ya no es un párrafo, sino un objeto JSON limpio y listo para ser usado en una aplicación de producción.
Los modelos de lenguaje (LLMs) tienen un límite: su conocimiento llega hasta su fecha de entrenamiento. No saben qué hay en tu almacén hoy ni qué precio tiene un producto en este segundo.
Tool Calling permite que la IA use funciones de TypeScript para interactuar con APIs externas. La IA no solo "habla", ahora "actúa".
Vamos a crear una herramienta que realice una búsqueda real en el catálogo de DummyJSON. Genkit utiliza la descripción que escribes para que la IA entienda cuándo debe usar esta función.
Crea el archivo src/tools/searchProductTool.ts y añade este código:
import { z } from 'genkit';
import { ai } from '../genkit';
export const searchProductTool = ai.defineTool(
{
name: 'searchProduct',
description: 'Busca productos en el catálogo oficial de la tienda GenkitStore para obtener precios y stock en tiempo real.',
inputSchema: z.object({ query: z.string() }),
outputSchema: z.any(),
},
async (input) => {
const response = await fetch(`https://dummyjson.com/products/search?q=${input.query}`);
const data = await response.json();
return data.products;
}
);
La magia de Genkit es que tú no llamas a la función manualmente. Se la entregas al modelo y él, basándose en la pregunta del usuario, decide si necesita usarla.
Crea un nuevo archivo src/flows/agentFlow.ts que defina un esquema para una lista de productos y utilice searchProductTool:
import { z } from 'genkit';
import { ai } from '../genkit';
import { searchProductTool } from '../tools/searchProductTool';
const ProductListSchema = z.array(z.object({
name: z.string(),
brand: z.string(),
features: z.array(z.string()),
recommendation_text: z.string(),
}));
export const agentFlow = ai.defineFlow(
{
name: 'agentFlow',
inputSchema: z.string(),
outputSchema: ProductListSchema,
},
async (userInput) => {
const { output } = await ai.generate({
prompt: userInput,
tools: [searchProductTool],
output: { schema: ProductListSchema },
});
if (!output) throw new Error("La IA no pudo generar el formato correcto.");
return output;
}
);
Actualiza src/index.ts para exportar la herramienta y el nuevo flujo:
export * from './flows/basicScoutFlow';
export * from './flows/structuredScoutFlow';
export * from './tools/searchProductTool';
export * from './flows/agentFlow';
searchProduct aparece en la sección Tools y agentFlow en la sección Flows.agentFlow y prueba con una consulta como "Busco un teléfono".searchProduct, consultará la API de DummyJSON en tiempo real y te devolverá la lista estructurada de productos encontrados.Un Guardrail es un límite o regla de control impuesta por el desarrollador que la IA no puede ignorar. En este paso, aprenderás a interceptar los datos de la API y aplicar reglas de negocio para que el asistente sea responsable y confiable.
Vamos a crear un flujo que incluya los campos de precio, rating, advertencia y disponibilidad. Si el rating es menor a 4.0, obligaremos a la IA a incluir un mensaje en warning. Además, clasificaremos el estado del inventario en availability.
Crea el archivo src/flows/guardedScoutFlow.ts:
import { z } from 'genkit';
import { ai } from '../genkit';
import { searchProductTool } from '../tools/searchProductTool';
const GuardedProductSchema = z.array(z.object({
name: z.string(),
brand: z.string(),
price: z.number(),
rating: z.number(),
features: z.array(z.string()),
recommendation_text: z.string(),
warning: z.string().optional(),
availability: z.enum(['En Stock', 'Pocas Unidades', 'Agotado']).optional(),
}));
export const guardedScoutFlow = ai.defineFlow(
{
name: 'guardedScoutFlow',
inputSchema: z.string(),
outputSchema: GuardedProductSchema,
},
async (userInput) => {
const { output } = await ai.generate({
prompt: userInput,
tools: [searchProductTool],
output: { schema: GuardedProductSchema },
system: `
Eres un asistente de compras honesto.
REGLA DE ORO: Si un producto tiene un rating menor a 4.0,
debes llenar el campo 'warning' indicando que la satisfacción
del cliente es baja.
REGLA DE STOCK: Llena el campo 'availability' usando 'Agotado' si stock es 0,
'Pocas Unidades' si stock es menor a 10, o 'En Stock' en caso contrario.
`,
});
if (!output) throw new Error("Error al generar respuesta");
return output;
}
);
Exporta este nuevo flujo en src/index.ts:
export * from './flows/basicScoutFlow';
export * from './flows/structuredScoutFlow';
export * from './tools/searchProductTool';
export * from './flows/agentFlow';
export * from './flows/guardedScoutFlow';
A veces, la regla no es solo un mensaje, sino filtrar la información antes de que la IA la vea. Si un producto supera el presupuesto del usuario, es mejor excluirlo para que la IA no lo recomiende.
Actualiza src/tools/searchProductTool.ts para añadir el filtro de presupuesto máximo:
import { z } from 'genkit';
import { ai } from '../genkit';
export const searchProductTool = ai.defineTool(
{
name: 'searchProduct',
description: 'Busca productos en el catálogo oficial de la tienda GenkitStore para obtener precios y stock en tiempo real.',
inputSchema: z.object({ query: z.string() }),
outputSchema: z.any(),
},
async (input) => {
const response = await fetch(`https://dummyjson.com/products/search?q=${input.query}`);
const data = await response.json();
// Regla de precios: Filtramos productos que superen el presupuesto máximo
const affordableProducts = data.products.filter((p: any) => p.price <= 1900);
return affordableProducts;
}
);
guardedScoutFlow preguntando por: "Estoy buscando laptop".<= 1900), junto con los campos "recommendation_text", "availability" y, cuando aplique, "warning".system prompt para darle reglas de negocio y comportamiento a la IA.¿Alguna vez te has preguntado qué pasa exactamente entre que el usuario hace una pregunta y la IA responde? En el desarrollo tradicional hacemos console.log o usamos el debugger. En Genkit, tenemos Tracing.
Es una vista detallada (como el "Network Tab" de Chrome) que registra cada paso de un Flow:
Para ver un Trace interesante, necesitamos un flujo que haga varias cosas. Asegúrate de tener corriendo tu Developer UI:
genkit start -- npx tsx --watch src/index.ts
guardedScoutFlow."Busco una laptop de menos de 3000 USD que tenga buenas reseñas".Una vez que el flujo termine:
guardedScoutFlow.searchProduct o generate) para inspeccionar qué parámetros envió el modelo a la herramienta, qué JSON exacto devolvió la API tras aplicar el filtro y cómo construyó la respuesta final.Hasta ahora, hemos ejecutado nuestro agente en la Developer UI. En un entorno profesional, necesitamos que nuestro flujo sea accesible a través de una URL segura (HTTPS) para que pueda ser consumido por una app en Angular, React o Flutter.
Si aún no tienes un proyecto de Firebase con Cloud Functions en TypeScript, sigue estos pasos:
npm install -g firebase-tools
firebase login
firebase login --reauth # alternativa, si es necesario
firebase login --no-localhost # si ejecutas en un shell remoto
firebase init
El asistente de inicialización te hará una serie de preguntas. Estas son las respuestas recomendadas:
Pregunta | Respuesta |
Which Firebase features do you want to set up? | Functions: Configure a Cloud Functions directory and its files |
Please select an option | Use an existing project |
Select a default Firebase project | Selecciona tu proyecto (ej. |
What language would you like to use? | TypeScript |
Do you want to use ESLint? | No |
Do you want to install dependencies with npm now? | Yes |
Would you like to install agent skills for Firebase? | No |
Al finalizar, verás el mensaje Firebase initialization complete! y se habrá creado la carpeta functions/ con toda la estructura necesaria.
functions:cd functions
npm install genkit @genkit-ai/google-genai
cd ..
En producción, nunca debemos dejar las API Keys en el código o en archivos .env locales. Usaremos el gestor de secretos de Firebase para que Gemini pueda autenticarse de forma segura.
Ejecuta este comando en tu terminal para subir tu clave de Google AI Studio:
firebase functions:secrets:set GOOGLE_GENAI_API_KEY
Pega tu clave cuando la terminal te lo solicite.
La carpeta functions/ funciona como un paquete independiente para Cloud Functions. Reemplaza el contenido de functions/src/index.ts para consolidar allí la herramienta y el flujo final (guardedScoutFlow), exponiéndolo mediante onCallGenkit:
import { googleAI } from '@genkit-ai/google-genai';
import { genkit, z } from 'genkit';
import { defineSecret } from 'firebase-functions/params';
import { onCallGenkit } from 'firebase-functions/https';
const googleAIapiKey = defineSecret('GOOGLE_GENAI_API_KEY');
const ai = genkit({
plugins: [googleAI()],
model: googleAI.model('gemini-2.5-flash'),
});
export const searchProductTool = ai.defineTool(
{
name: 'searchProduct',
description: 'Busca productos en el catálogo oficial de la tienda GenkitStore para obtener precios y stock en tiempo real.',
inputSchema: z.object({ query: z.string() }),
outputSchema: z.any(),
},
async (input) => {
const response = await fetch(`https://dummyjson.com/products/search?q=${input.query}`);
const data = await response.json();
return data.products.filter((p: any) => p.price <= 1900);
}
);
const GuardedProductSchema = z.array(z.object({
name: z.string(),
brand: z.string(),
price: z.number(),
rating: z.number(),
features: z.array(z.string()),
recommendation_text: z.string(),
warning: z.string().optional(),
availability: z.enum(['En Stock', 'Pocas Unidades', 'Agotado']).optional(),
}));
export const guardedScoutFlow = ai.defineFlow(
{
name: 'guardedScoutFlow',
inputSchema: z.string(),
outputSchema: GuardedProductSchema,
},
async (userInput) => {
const { output } = await ai.generate({
prompt: userInput,
tools: [searchProductTool],
output: { schema: GuardedProductSchema },
system: `
Eres un asistente de compras honesto.
REGLA DE ORO: Si un producto tiene un rating menor a 4.0,
debes llenar el campo 'warning' indicando que la satisfacción
del cliente es baja.
REGLA DE STOCK: Llena el campo 'availability' usando 'Agotado' si stock es 0,
'Pocas Unidades' si stock es menor a 10, o 'En Stock' en caso contrario.
`,
});
if (!output) throw new Error("La IA no pudo generar el formato correcto.");
return output;
}
);
export const generateGuardedScoutFlow = onCallGenkit(
{
cors: '*',
authPolicy: () => true,
secrets: [googleAIapiKey],
},
guardedScoutFlow
);
Asegúrate de haber iniciado sesión con firebase login y de haber seleccionado tu proyecto. Luego ejecuta:
firebase deploy --only functions
Una vez que el despliegue termine, la terminal te entregará una URL similar a:
https://us-central1-tu-proyecto.cloudfunctions.net/generateGuardedScoutFlow
Puedes probarla enviando una petición POST con formato JSON {"data": "..."}:
curl -X POST https://us-central1-tu-proyecto.cloudfunctions.net/generateGuardedScoutFlow \
-H "Content-Type: application/json" \
-d '{"data": "Estoy buscando una laptop"}'
Has pasado de tener un script local a una API de IA generativa con orquestación profesional, conexión real a un catálogo (Tools), contratos de datos garantizados (Zod) y reglas de negocio activas.
Has construido un sistema de IA robusto, tipado y listo para producción.
src/flows/.src/tools/.Si tienes dudas o quieres compartir lo que construiste, ¡escríbeme!