Problema
Las librerías de UI y sistemas de diseño suelen requerir que los desarrolladores naveguen manualmente la documentación, entiendan APIs y revisen código fuente para utilizar correctamente los componentes.
Esto genera fricción, especialmente cuando:
- se exploran componentes nuevos
- se intentan entender props y variantes
- o se necesita acceso rápido a la implementación real
Solución
Desarrollé un agente de IA integrado en NachUI que permite consultar el sistema de forma conversacional y obtener respuestas precisas basadas en el contexto real del proyecto.
El agente puede:
- recuperar documentación relevante
- acceder al código fuente real de los componentes
- explicar su uso y detalles de implementación
Todo basado estrictamente en el código y documentación reales de NachUI.
Cómo funciona
- El agente utiliza una arquitectura basada en herramientas (tools)
- Las consultas del usuario se procesan mediante un modelo de Gemini (gemini-2.5-pro, por el momento)
- El agente decide dinámicamente cuándo usar herramientas
- Las tools permiten:
-
- buscar documentación en
.velite/docs.json - leer código de componentes directamente desde el sistema de archivos
- buscar documentación en
- Los resultados se validan y se devuelven como respuestas estructuradas
Stack tecnológico
- Core: TypeScript (paquete monorepo
@repo/ai) - AI SDK: Vercel AI SDK
- Modelo: Google Gemini
- Validación: Zod
- Arquitectura: Agente basado en tools (ToolLoopAgent), Monorepo con paquete dedicado (
@repo/ai)
Decisiones técnicas
- Arquitectura basada en tools: permite acceder a datos reales (docs y código) en lugar de depender solo de prompts
- Uso de Zod: garantiza respuestas tipadas y estructuradas para integrarse con la UI
- Lectura directa del filesystem: asegura precisión al trabajar con código real
- System prompt personalizado: evita alucinaciones y fuerza consistencia con la filosofía de NachUI
- Diseño modular de providers: permite cambiar de modelo (Google, OpenAI, Groq, etc.) sin afectar la lógica principal
- Configuración de baja temperatura: mejora la consistencia y reduce errores
- Separación como paquete dentro del monorepo (
@repo/ai): permite aislar la lógica del agente, reutilizarla en diferentes apps (docs, playground, etc.) y escalar el sistema sin acoplarlo al frontend
Desafíos y aprendizajes
- Evitar alucinaciones en modelos de lenguaje
- Diseñar flujos confiables de tool calling
- Balancear flexibilidad y control en el system prompt
- Estructurar documentación para facilitar su recuperación
- Manejar respuestas en múltiples idiomas