Cada pocas semanas, alguien del área de negocios preguntaba lo mismo: «¿Puedo simplemente escribir mi pregunta y obtener los datos?». Después de escucharlo suficientes veces, construimos un agente Text-to-SQL en Databricks y terminamos comparando dos caminos muy diferentes: Genie Spaces y Mosaic AI Agent Framework.

El concepto suena sencillo. Un usuario escribe una pregunta en lenguaje natural. El agente descifra lo que quiere decir, escribe el SQL, lo ejecuta en Databricks y devuelve una respuesta. En una demostración, parece casi mágico. En un entorno gobernado real con datos empresariales concretos, la historia es diferente.

Lo primero que aprendimos es que la generación de SQL es la parte fácil. La pregunta más difícil es si el agente puede entender su modelo de datos, operar dentro de sus reglas de seguridad y devolver respuestas que realmente sean válidas cuando alguien actúe en base a ellas.

Eso nos llevó a una decisión importante: ¿usar una experiencia gestionada de Databricks o construir el agente nosotros mismos?

Por un lado, Genie Spaces, la experiencia de análisis conversacional gestionada de Databricks, parecía el camino más rápido. Por otro lado, Mosaic AI Agent Framework, el framework propietario de Databricks para construir aplicaciones de agente personalizadas en Python, ofrecía control sobre cada capa. Más potente, pero también significativamente más trabajo.

Probamos ambos con el mismo conjunto de datos y las mismas preguntas de negocio, no solo para ver cuál producía un SQL mejor, sino para entender lo que cada enfoque realmente requería.

¿Qué es un agente Text-to-SQL? Genie Spaces y Mosaic AI explicados

Antes de entrar en lo que construimos, es útil definir las tres piezas principales.

Un agente Text-to-SQL es un sistema de IA que toma una pregunta en lenguaje natural y la convierte en SQL ejecutable. En una demostración parece sencillo: un usuario escribe «¿Cuál es el saldo actual de la cuenta 1001?» y el agente produce SELECT balance FROM accounts WHERE account_id = 1001. En un entorno gobernado real, la misma pregunta también requiere que el agente sepa a qué tabla se mapea «accounts», si el usuario actual tiene permiso para ver esa fila y qué significa «balance» en su esquema.

Genie Spaces son la opción gestionada de Databricks para esta experiencia. Se configura un Espacio sobre tablas, vistas y metadatos de Unity Catalog seleccionados, se añaden instrucciones y ejemplos, se conecta un SQL Warehouse y se obtiene una interfaz conversacional funcional sin necesidad de construir la capa de aplicación. De serie: generación de SQL, ejecución de consultas, presentación de respuestas, permisos de Unity Catalog y una forma de añadir contexto de negocio. La contrapartida es el control: se puede guiar a Genie, pero no se posee el flujo de razonamiento, la orquestación de herramientas, la memoria o la lógica de validación.

Mosaic AI Agent Framework es el framework propietario de Databricks para construir aplicaciones de agente personalizadas. No es una biblioteca genérica de código abierto. Es una parte nativa de la plataforma Databricks, diseñada para que los equipos puedan definir el modelo, las herramientas, los prompts, la lógica de orquestación, la evaluación y el despliegue dentro del mismo entorno gobernado donde residen sus datos.

La primera conclusión: la generación de SQL no era suficiente

Esto era obvio en retrospectiva, pero se necesitaron algunas consultas fallidas para entenderlo realmente.

Un agente Text-to-SQL no es útil solo porque pueda generar SQL. Una consulta puede ser sintácticamente perfecta y aun así estar equivocada:

• Puede unirse a través de una relación obsoleta.
• Puede interpretar erróneamente lo que significa «cuenta activa» en su contexto.
• Puede extraer un campo que debería estar enmascarado.
• Puede devolver datos que un usuario en particular no debería ver.

Así que el verdadero trabajo no fue construir el agente. Fue construir el contexto que el agente necesitaba para razonar correctamente: qué representa cada tabla, qué significa cada columna en términos de negocio, cómo se relacionan las entidades entre sí, qué filtros están aprobados, quién puede acceder a qué y qué funciones de Unity Catalog deben invocarse como herramientas controladas.

Antes de comparar las herramientas, necesitábamos una base común

Antes de comparar Genie y Mosaic, teníamos que asegurarnos de que ambos partieran de la misma base. De lo contrario, no estaríamos comparando las herramientas, sino dos versiones diferentes del problema.

Eso significó documentar tablas y columnas, codificar reglas de negocio que antes solo existían en la mente de las personas, validar permisos, configurar el enmascaramiento y la seguridad a nivel de fila, y encapsular la lógica reutilizable en funciones de Unity Catalog. Llevó más tiempo de lo esperado. Pero también hizo que todo lo que vino después fuera mucho más honesto.

En un entorno de producción, un agente no puede depender de una indicación ingeniosa para compensar la falta de contexto. Necesita una base de datos que haya sido realmente preparada para ello. Esa preparación es donde reside la mayor parte del trabajo real, independientemente de la herramienta que elijas.

El desafío compartido: hacer que las funciones de Unity Catalog funcionen para ambos agentes

Una vez establecida la base, necesitábamos una forma de exponer la lógica de negocio reutilizable a ambos agentes de manera consistente. Las funciones de Unity Catalog eran el mecanismo natural; en lugar de dejar que cada agente redescubriera la misma lógica en cada llamada, podríamos definir funciones controladas para tareas específicas.

Aquí es donde las cosas se volvieron más matizadas de lo esperado.

Un desarrollador puede leer documentación, explorar un esquema, preguntar a un colega. Un agente decide si usar una función basándose casi por completo en su nombre y descripción. Esa única diferencia cambia lo que significa «bien diseñado».

Para el uso del agente, las funciones deben ser:

• Nombradas claramente y autoexplicativas
• De alcance limitado, para que el agente pueda asociarlas a la tarea correcta
• Documentadas a nivel de parámetro, para que el agente sepa qué valores pasar
• De salida predecible, para que el agente pueda razonar sobre el resultado
• Con los permisos adecuados
• No estructuradas como un procedimiento almacenado amplio que hace varias cosas a la vez

Esto fue un requisito de diseño, no un efecto secundario de querer que las funciones funcionaran en dos herramientas. Las funciones que se leían como interfaces de producto funcionaron. Las funciones que se leían como atajos internos de SQL no.

Cómo funciona Genie Spaces para Text-to-SQL en Databricks

Empezamos con Genie porque era la ruta más directa: una interfaz conversacional sobre datos gobernados, sin tener que escribir todo el stack del agente desde cero.

La configuración es sencilla. Crear un Space, seleccionar tablas o vistas, añadir instrucciones y ejemplos, definir relaciones, conectar un SQL Warehouse, empezar a hacer preguntas. Para un caso de uso de análisis de autoservicio dirigido a analistas de negocio, este es un punto de partida realmente sólido.

Donde Genie mostró sus límites

Los límites se hicieron evidentes cuando fuimos más allá de las preguntas sencillas. No porque Genie fallara, sino porque guiar el comportamiento a través de la configuración es diferente de controlarlo mediante código. Puedes añadir instrucciones y ejemplos, pero no controlas el bucle de razonamiento directamente.

Probando Genie a través de la API

También probamos la API y la ruta de Python para ver si la configuración podía ser versionada y automatizada. Sí, es posible, pero requiere mucha estructura previa. Tablas, instrucciones, ejemplos, uniones y contexto semántico, todo debe definirse explícitamente. Esto lo hace muy adecuado para un Space que ya es estable y necesita ser puesto en operación. Es una experiencia complicada si todavía estás averiguando cómo debería ser el Space.

Así es como lo vemos: usa la interfaz de usuario mientras descubres la configuración adecuada, cambia a la API una vez que el Space sea estable y quieras automatizarlo o versionarlo.

Una cosa más a tener en cuenta: Genie puede ser llamado desde fuera de Databricks a través de APIs, pero el propio Space sigue ejecutándose dentro de la plataforma Databricks. Una aplicación externa puede enviar preguntas a un Space existente, pero no aloja ni reemplaza el entorno de ejecución.

Creación de un agente Text-to-SQL personalizado con el framework de agentes de Mosaic AI

Pasar a Mosaic fue como ir de un producto configurado a un proyecto de ingeniería en toda regla.

En lugar de añadir instrucciones a un Space, estábamos escribiendo Python. Controlábamos:

• La selección de LLM y el diseño del prompt del sistema
• Qué herramientas exponer y cómo las selecciona el agente
• La gestión de errores y la evaluación de respuestas
• El registro de trazas y el despliegue del agente

Ese nivel de control es el punto clave de Mosaic. No es una versión más flexible de Genie, es una categoría completamente diferente, un framework para construir una aplicación agéntica personalizada. Los casos de uso que tienen sentido aquí son aquellos en los que el agente necesita hacer cosas que un Space gestionado no puede:

• Llamar a APIs externas
• Combinar datos de Databricks con documentos
• Activar flujos de trabajo
• Seguir una lógica de orquestación demasiado compleja para expresarla mediante configuración.

El costo de ese control es la responsabilidad de ingeniería. Alguien tiene que diseñar el agente, mantener el código, probar el comportamiento de la herramienta, evaluar los resultados y supervisar la producción. Eso no es una razón para evitar Mosaic, pero es un factor real a la hora de determinar si un equipo está preparado para ello.

Al final de este camino, la comparación había dejado de centrarse en las características. Se había convertido en dos formas diferentes de trabajar.

Donde la comparación se hizo real

Lo más difícil no fue construir cada agente. Fue hacerlos realmente comparables.

Para compararlos de manera justa, ambos necesitaban partir de la misma base: las mismas tablas de Unity Catalog, las mismas definiciones de negocio, las mismas reglas de seguridad, la misma lógica de enmascaramiento y acceso a nivel de fila, y las mismas funciones de Unity Catalog.

Llegar a ese punto requirió más iteraciones de lo esperado. Algunas funciones tuvieron que simplificarse. Algunos comentarios de columna tuvieron que reescribirse para ser inequívocos. Algunos parámetros necesitaban mejor documentación. Algunos formatos de retorno tuvieron que hacerse más consistentes.

Cada vez que la base compartida mejoraba, ambos agentes mejoraban, no solo uno de ellos. La calidad del agente está determinada en gran medida por la calidad del contexto gobernado que lo respalda, no por el modelo o la interfaz que se encuentra encima.

Costo y propiedad: qué cambió entre ambos caminos

La parada automática es una configuración de SQL Warehouse que apaga el almacén automáticamente después de un período definido de inactividad, evitando costos durante las horas de menor actividad. Para un equipo pequeño o mediano que utiliza el Espacio durante el horario comercial, los costos pueden ser razonablemente predecibles con el tamaño de almacén y la configuración de parada automática adecuados.

La decisión no se trata realmente de qué opción cuesta menos. Se trata del tipo de equipo que tienes y de lo que estás dispuesto a asumir a lo largo del tiempo. En nuestro caso, solo queremos comparar cómo funciona cada agente para un caso simple.

6 lecciones de la construcción de un agente de texto a SQL en Databricks

Seis cosas que nos diríamos a nosotros mismos si volviéramos a empezar.

1. Empieza con el contexto de los datos, no con el modelo. El LLM puede generar SQL. El contexto de Unity Catalog es lo que hace que la respuesta sea correcta. Si los metadatos faltan o son incorrectos, incluso un modelo potente produce consultas de aspecto plausible que en realidad no funcionan.
2. Diseña las funciones de Unity Catalog como interfaces de producto, no como atajos de SQL. El agente descubre herramientas leyendo su nombre y descripción. Una nomenclatura clara, un alcance limitado, parámetros documentados y resultados predecibles importan más que una lógica interna elegante.
3. La API de Genie es mejor para la repetibilidad que para la exploración. Es la herramienta adecuada una vez que un Espacio es estable y quieres versionarlo o automatizarlo. Es una experiencia difícil si todavía estás averiguando cómo debería ser el Espacio.
4. Mosaic ofrece más control, pero la responsabilidad es real. Los flujos de trabajo personalizados, las integraciones externas y el control total de la orquestación son ventajas genuinas, pero conllevan un compromiso de equipo que no debe subestimarse.
5. Pruebe la seguridad como parte del agente, no después de él. Los permisos, el enmascaramiento y la seguridad a nivel de fila no son un paso final de control de calidad. Afectan qué consultas se generan y qué datos se devuelven. Son parte de la implementación desde el primer día.
6. La base importa más que la interfaz. Mejoramos el contexto de Unity Catalog a mitad del experimento, y ambos agentes mejoraron significativamente. Antes de elegir una herramienta, pregúntese si sus datos están realmente listos para que un agente razone sobre ellos.

Conclusión

Ambas herramientas funcionaron. Ninguna de ellas hizo la parte difícil por nosotros.

Genie agilizó la puesta en marcha de una interfaz funcional para los usuarios, pero era menos configurable en sus detalles. Mosaic permitió construir algo que se comportaba exactamente como necesitábamos, aunque complicó cada paso del proceso. Pero en ambos casos, la calidad del resultado dependió de la calidad de los metadatos, la claridad de las reglas de negocio y el diseño de las funciones de Unity Catalog. La herramienta fue casi secundaria.

Comience con Genie cuando el objetivo sea el análisis de autoservicio gobernado y la base de datos sea razonablemente limpia. Pase a Mosaic cuando el caso de uso requiera orquestación personalizada, integraciones externas o un comportamiento que la configuración simplemente no pueda expresar.

Pero antes de tomar esa decisión, dedique tiempo a los datos. La pregunta no es «¿qué herramienta de agente debemos usar?». Es «¿están nuestros datos realmente listos para que un agente razone sobre ellos?». Si acierta en eso, el resto se vuelve mucho más manejable.

Si ya tenemos buenos datos, podemos pensar en lo que buscamos: accesibilidad sin libertad o libertad sin accesibilidad.

Siga leyendo

Si esto le fue útil, escribimos regularmente sobre IA aplicada, ingeniería de datos y la construcción de sistemas reales en plataformas de datos modernas.

Explore más artículos en los blogs de Marvik