Construye tu primer agente de IA en TypeScript

Hasta hace poco pensaba que crear agentes IA era demasiado complejo, pero la realidad es que empezar es bastante accesible. En este artículo explico paso a paso cómo construir un agente IA meteorológico usando TypeScript y Node.js, y cómo convertirlo en una herramienta útil que responde la hora actual, consulta el clima y sugiere actividades según la situación.

Requisitos previos: instala Node.js y TypeScript. Necesitarás una clave de API para el modelo de lenguaje que hará funcionar tu agente. Una opción práctica es Gemini si tienes una cuenta de Google, aunque también puedes usar modelos de OpenAI o Claude siguiendo su documentación para generar una API key. Añade tu clave al archivo .env como valor de la variable GOOGLE_GENERATIVE_AI_API_KEY.

Scaffold del proyecto: usa el SDK Mastra para JavaScript y TypeScript. Un ejemplo de comando para crear el proyecto es npx create-mastra@latest --project-name weather-ai --example --components tools,agents,workflows --llm google. El proyecto generado incluye un agente y una herramienta de ejemplo para el clima. Ejecuta npm run dev y abre la interfaz local en https://localhost:4111 para probar el playground.

Arquitectura y estructura: la convención de Mastra separa la lógica en tres carpetas principales agents, tools y workflows. El archivo weather-agent.ts define el agente meteorológico con su modelo, instrucciones de sistema y las herramientas que puede usar. Las instrucciones del agente actúan como el prompt de sistema que guía su comportamiento: pedir ubicación si falta, traducir nombres de lugar cuando no estén en inglés, incluir detalles relevantes como humedad y viento, y sugerir actividades si el usuario lo solicita.

Herramientas y cómo funcionan: las tools permiten que el cerebro del LLM interactúe con el mundo. Por ejemplo, weatherTool consulta servicios de geocodificación y usa la API de open-meteo para obtener temperatura, sensación térmica, humedad, velocidad de viento, rachas y código de condiciones. Mastra permite definir esquemas de entrada y salida con Zod para validar los datos que pasan entre agente y herramienta.

Ampliando capacidades con nuevas tools: para hacer al agente más inteligente añade un timeTool que devuelva la fecha y la hora según una zona horaria. Crea un archivo src/mastra/tools/time-tool.ts que implemente una herramienta que formatee la fecha, la hora y devuelva un timestamp. Luego importa timeTool en la definición del agente y añádelo a la lista de tools para que el agente pueda invocarlo.

Integración y comportamiento: actualiza las instrucciones del agente para indicar que, cuando el usuario pida actividades, el agente debe usar timeTool para obtener la hora local y sugerir opciones adecuadas según la hora del día y el pronóstico. Con esto el agente no solo comunica el estado del clima, sino que propone planes como salir a caminar, ir a la playa, llevar paraguas o actividades nocturnas según la hora y el clima.

Prácticas recomendadas: experimenta con las instrucciones de sistema para ajustar el estilo y la concisión del agente, valida siempre las respuestas de las herramientas con esquemas y gestiona memoria si quieres que el agente recuerde conversaciones pasadas. Añadir más tools, como búsquedas web o integraciones con APIs externas, amplía enormemente las posibilidades.

En Q2BSTUDIO somos expertos en desarrollo de software a medida y aplicaciones a medida, y podemos ayudarte a crear agentes IA personalizados para tu negocio. Ofrecemos servicios en inteligencia artificial, ia para empresas, ciberseguridad y servicios cloud aws y azure para desplegar soluciones escalables y seguras. También trabajamos servicios inteligencia de negocio e implementaciones con power bi para transformar datos en decisiones accionables.

Si buscas software a medida o aplicaciones a medida que integren agentes IA con capacidades concretas, Q2BSTUDIO te acompaña desde el diseño hasta la puesta en producción. Nuestras competencias en inteligencia artificial y ciberseguridad garantizan implementaciones fiables, mientras que nuestros servicios cloud aws y azure aseguran escalabilidad y disponibilidad.

Conclusión: construir un agente IA en TypeScript es un proceso directo cuando se siguen los pasos adecuados: preparar el entorno, crear el proyecto con Mastra, definir agents y tools, y ajustar las instrucciones del sistema. Con habilidades adicionales en inteligencia artificial, integración con servicios cloud y análisis de datos con power bi puedes potenciar soluciones reales para empresas. Si quieres desarrollar un agente IA, mejorar tu software a medida o implementar servicios de inteligencia de negocio, contacta con Q2BSTUDIO para una consultoría especializada en agentes IA, ia para empresas y soluciones seguras con enfoque en ciberseguridad y cloud.