Vivimos una etapa en la que todos quieren aplicar IA en todas partes. Si trabajas con Total.js Flow, seguro que alguna vez te has preguntado si puedes incorporar IA a tus flujos. En esta guía práctica te explico paso a paso cómo crear un componente que conecte Google Gemini con Flow para procesar texto y devolver resultados útiles, reescribiendo y traduciendo el contenido original al español, y añadiendo recomendaciones profesionales basadas en la experiencia de Q2BSTUDIO.
Instalación de Flow
Si ya usas Total.js Flow, puedes saltarte esta parte. En caso contrario, instala Flow siguiendo la documentación oficial. El objetivo aquí es centrarnos en el componente que hablará con Gemini.
Creación del componente
En el editor de Flow, pulsa el botón verde de añadir y crea un nuevo componente. Flow genera una plantilla con la estructura básica, compuesta por metadatos, configuración, entradas y salidas, y la función principal de ejecución.
Metadatos y configuración
Define un id único como geminiapi. Asigna un name descriptivo como Gemini API, un icon, author y version. Usa group para clasificarlo dentro de Services u otra categoría que te ayude a organizar el panel izquierdo.
En config define los parámetros que el usuario podrá ajustar sin tocar código. Para este caso necesitas tres claves: apikey para autenticar llamadas contra Google, model para seleccionar el modelo de Gemini que se usará por defecto como gemini-1.5-flash, y output para decidir si el componente devolverá la respuesta completa del API o solo el texto procesado. Esta configuración te permite reutilizar el componente con distintas credenciales y comportamientos en un mismo Flow.
Lógica del componente
La función principal se implementa en instance.message. El flujo recomendado es:
1. Validar entradas. Comprueba que llegan datos. Acepta tanto un string directo como un objeto con la propiedad text. Si el formato no es válido, envía el error por la salida error. 2. Validar la clave. Si no existe apikey en la configuración, detén la ejecución y avisa por la salida error. 3. Normalizar el input. Si llega un objeto con text, extrae el valor y trabaja siempre con un string.
Construir el payload para Gemini
Convierte el texto de entrada en el formato que espera la API de Google Gemini. Estructura un objeto con la propiedad contents que contenga un array de mensajes y dentro de parts un único elemento con el texto a procesar. Este formato sigue la especificación de la API REST de Gemini.
Invocar la API con RESTBuilder
Usa RESTBuilder con método POST hacia la ruta de models y la operación generateContent. La URL incluye el nombre del modelo y la clave. Añade la cabecera Content-Type application json, y un timeout generoso como 60000 para peticiones que puedan tardar. En el callback maneja dos escenarios:
1. Error de red o de API. Envía el error a la salida error. 2. Respuesta correcta. Si config.output es text, extrae del primer candidato el primer part y toma su text para devolver solo el contenido generado. Si prefieres la respuesta completa, reenvía el objeto tal cual por la salida output. Este enfoque te permite alternar entre un resultado mínimo y un resultado detallado con metadatos, según lo necesites.
Configuración desde la UI
En el formulario de configuración del componente agrega campos para apikey con validación obligatoria y ayuda para generar la clave en Google, un selector de model con opciones como gemini-1.5-flash y gemini-1.5-pro, y un selector de output para elegir entre respuesta completa o solo texto. Así cualquier usuario del flujo puede ajustar el comportamiento sin modificar el código.
Readme del componente
Documenta el uso de forma clara. Indica que el componente recibe texto y devuelve texto o el objeto completo de la API. Acepta dos formatos de entrada: un string directo o un objeto con la propiedad text. Explica brevemente los parámetros de configuración y qué hace cada salida output y error.
Ejemplo de uso
Crea un flujo mínimo con un Trigger que envía un texto como Hola, como estas, conecta el componente de Gemini y termina en un Print. Configura el modelo como Gemini 1.5 Flash y el output como texto. Al disparar el flujo verás en consola la respuesta generada por la IA. Puedes duplicar el componente y alternar entre salida completa y solo texto para comparar.
Consejos prácticos
1. Gestión de errores. Encapsula siempre el envío a la salida error, y añade mensajes claros que faciliten el diagnóstico. 2. Seguridad. No hardcodees la clave en el código. Usa el config del componente o variables de entorno y controla los permisos de edición en Flow. 3. Reintentos. Para escenarios productivos, considera lógica de reintento con backoff cuando la API devuelva estados temporales. 4. Observabilidad. Añade métricas simples como tiempos de respuesta y tasa de errores, y, si procede, logs minimizados sin datos sensibles. 5. Versionado. Incrementa version cuando cambies comportamiento, y refleja el cambio en el Readme.
Cómo encaja esto en una estrategia de negocio
Integrar Google Gemini en Total.js Flow acelera prototipos de agentes IA, asistentes internos, clasificación de tickets o enriquecimiento de datos. En Q2BSTUDIO ayudamos a convertir estas pruebas en soluciones reales con aplicaciones a medida y software a medida, cubriendo extremo a extremo la arquitectura, la integración con APIs corporativas, la seguridad y la puesta en producción. Si buscas impulsar proyectos de ia para empresas con un enfoque estratégico, consulta nuestros servicios de inteligencia artificial para empresas.
Por qué Q2BSTUDIO
Somos una empresa de desarrollo de software especializada en aplicaciones a medida, ciberseguridad, servicios cloud aws y azure, servicios inteligencia de negocio con power bi, y despliegue de agentes IA. Diseñamos soluciones escalables, seguras y mantenibles, optimizando costes y tiempos de entrega. Si necesitas un equipo experto en integración con plataformas low code y orquestación de flujos, descubre cómo abordamos proyectos de aplicaciones a medida.
Cierre
Hemos visto cómo crear un componente de Google Gemini para Total.js Flow con validaciones, configuración flexible y manejo de respuestas. Con esta base, puedes enriquecer tus flujos con plantillas de prompts, memoria de conversaciones mediante contexto y controles de coste por modelo. Si deseas asesoría para llevar esta integración a producción con mejores prácticas de ciberseguridad, observabilidad y gobierno del dato, el equipo de Q2BSTUDIO estará encantado de ayudarte.