Construyendo un Agente Auxiliar de Código de IA con el Marco Mastra e Integración con Telex.im

Construyendo un Agente Auxiliar de Código de IA con el Marco Mastra e Integración con Telex.im

En este artículo relato mi experiencia desarrollando un asistente de código potenciado por IA durante la etapa 3 del HNG Internship. El objetivo no era crear otra aplicación de base de datos, sino diseñar un agente inteligente que aporte valor real a desarrolladores: analizar código, detectar errores, recomendar mejoras y señalar riesgos de seguridad en múltiples lenguajes.

Resumen del proyecto: el resultado fue Code Helper Agent, un asistente capaz de interpretar fragmentos de código, localizar fallos, sugerir optimizaciones y comunicar hallazgos en formato markdown profesional. Tecnologías clave: el marco Mastra para la arquitectura de agentes, Google Gemini para el análisis inteligente, Express.js como servidor backend, Telex.im para la conectividad A2A y Railway para el despliegue en la nube. Esta solución demuestra cómo combinar agentes IA con prácticas de despliegue profesional para ofrecer servicios de calidad.

Toma de decisiones y funcionalidades principales: escogí centrarme en un analizador de código porque resuelve un reto cotidiano de los desarrolladores, evidencia capacidades de IA y tiene utilidad medible. Las funcionalidades críticas incluyeron interpretación de código, detección de errores, soporte multilenguaje y salida en markdown. Como mejoras añadidas se implementaron detección de vulnerabilidades, recomendaciones de rendimiento y buenas prácticas de industria.

Fundación del proyecto y problemas iniciales: la configuración del entorno implicó crear una estructura modular con carpetas para agentes, configuración, rutas y la instancia de Mastra. Surgieron retos significativos al instalar dependencias: Mastra exigía una versión moderna de Node.js y banderas para dependencias legacy. La solución pasó por actualizar Node.js y usar la instalación con las opciones adecuadas para resolver conflictos.

Desarrollo del agente Mastra: Mastra estructura la solución alrededor de agentes, herramientas y workflows. Un reto relevante fue entender que Mastra espera una instancia de modelo y no un simple identificador de cadena. Integrar Gemini requirió proporcionar un objeto de modelo válido y ajustar las instrucciones del agente con un equilibrio entre dirección clara y flexibilidad para que el asistente ofreciera respuestas útiles sin ser demasiado rígido.

Integración con Google Gemini: la autenticación y la correcta gestión de variables de entorno fueron críticas. Crear un archivo de variables de entorno, validar la presencia de la clave GEMINI y encapsular la obtención del modelo permitieron un acceso robusto a la API de Gemini. También fue necesario personalizar el método de generación del agente para invocar Gemini directamente, manteniendo la implementación original como respaldo y preservando manejo de errores.

Servidor Express y sanidad de respuestas: el endpoint A2A expone la ruta para que Telex.im invoque el agente. Fueron habituales problemas de formato de salida con secuencias de escape visibles; se resolvió mediante funciones de sanitización que normalizan saltos de línea, encabezados y bloques de código para que la presentación en Telex sea limpia y legible.

Implementación del protocolo A2A en Telex.im: Telex usa un modelo sencillo basado en POST con JSON. Hubo que admitir tanto campos message como text y ofrecer una respuesta de bienvenida cuando el usuario activaba el agente sin proporcionar código. Además se ajustaron prompts para reducir latencias y evitar timeouts, lo que mejoró la experiencia en la plataforma.

Estrategia de pruebas y despliegue: se implementaron tests locales con curl para validar distintos escenarios: sintaxis básica, detección de errores, vulnerabilidades SQL y bloques multilínea. Para el despliegue se escogió Railway por su integración con GitHub y manejo de variables de entorno. Fue indispensable enlazar el puerto dinámico de Railway y bindear a 0.0.0.0 para evitar errores de enlace.

Monitoreo y optimización: el monitoreo de logs de Telex y Railway permitió identificar patrones de uso, métricas de rendimiento y errores. Al optimizar los prompts de Gemini se redujeron los tiempos de respuesta de 8+ segundos a 2-3 segundos. Planes futuros incluyen caching para reducir consumo de IA y mejorar latencias.

Principales retos y aprendizajes: se enfrentaron conflictos de dependencias, problemas de escape en el texto, configuración de puertos y respuestas lentas; cada uno se resolvió con mejoras en la configuración, limpieza de respuestas, binding adecuado y optimización de prompts. Lecciones clave: documentar bien la configuración, probar de forma exhaustiva y construir de forma incremental.

Ventajas técnicas observadas: Mastra facilita la abstracción de agentes y la integración con modelos; Gemini mostró comprensión de código y salida en markdown; Telex A2A resultó un canal HTTP sencillo y seguro para integrar agentes. Estas piezas en conjunto permitieron crear un servicio que podría integrarse con productos profesionales, por ejemplo en soluciones de ia para empresas y proyectos de automatización.

Oportunidades de mejora y hoja de ruta: documentar más ejemplos, añadir soporte TypeScript, mejorar plantillas de despliegue y extender funciones: formateo automático de código, memoria conversacional para análisis multi-turn, generación de pruebas y evaluación de complejidad algorítmica. También se planea incorporar analytics de uso y límites de consumo para prevenir abusos.

Impacto para empresas y servicios de Q2BSTUDIO: este proyecto es un ejemplo práctico de cómo una empresa especializada puede ofrecer productos avanzados en inteligencia artificial, ciberseguridad y servicios cloud. En Q2BSTUDIO combinamos experiencia en desarrollo de aplicaciones a medida y software a medida con capacidades en servicios cloud aws y azure, ciberseguridad, agentes IA y soluciones de inteligencia de negocio como power bi. Podemos ayudar a integrar agentes IA en flujos de trabajo corporativos, optimizar seguridad y desplegar en infraestructuras escalables.

Resultados y métricas iniciales: tras optimizaciones la latencia media quedó en torno a 2.8 segundos, disponibilidad cercana al 99% y tasa de éxito superior al 98%. Se analizaron miles de líneas de código y se comprobó la utilidad práctica del agente para identificar bugs, vulnerabilidades SQL y problemas de rendimiento.

Conclusión: construir el Code Helper Agent fue una experiencia de aprendizaje intensa que consolidó competencias en Mastra, integración de IA y protocolos A2A. Recomiendo comenzar con una base simple, iterar de forma rápida, monitorizar activamente y documentar cada decisión. En Q2BSTUDIO estamos listos para convertir estas capacidades en soluciones empresariales a medida en inteligencia artificial, ciberseguridad, servicios cloud aws y azure, agentes IA y Business Intelligence con power bi.

Contacto y recursos: para explorar cómo integrar agentes IA o desarrollar software a medida, póngase en contacto con Q2BSTUDIO y descubra nuestras soluciones en inteligencia artificial y desarrollo de aplicaciones corporativas.