
Text-to-SQL: cómo construir un agente de IA fiable
Text-to-SQL en la práctica: lo que hemos aprendido al conectar agentes de IA a bases de datos de empresa. Trampas en producción, seguridad y make or buy.
Conectar un agente de IA a una base de datos, lo que se conoce como text-to-SQL, le permite responder a muchas más preguntas. En nuestros clientes, el ejemplo típico es un agente de resolución de incidencias sobre un producto complejo. Cuando la documentación técnica no basta, busca en la base de tickets un caso parecido al del usuario y le ayuda a resolver su problema. Después puede redactar la actualización de la documentación y enviarla a una persona que la valida.
El modelo traduce la pregunta a una consulta SQL, la plataforma la ejecuta y el modelo lee el resultado. Aunque se puede programar rápido un agente capaz de consultar una base de datos, en realidad obtener buenas respuestas en producción, sobre un gran número de preguntas, exige una inversión importante, como ocurre con un RAG entre el POC y la producción.
Lo aprendimos iterando durante meses sobre este tipo de agente, con clientes que aportaban cada uno sus casos de uso, sus esquemas y sus motores, en particular MariaDB y PostgreSQL, a veces sobre bases de varios cientos de tablas. En uno de ellos, tras varias iteraciones, alrededor del 84 % de las llamadas a nuestra herramienta de base de datos tenían éxito. Desde el paso a un enfoque agéntico, en el que el agente trabaja en varias etapas, más del 99 % de las consultas salen bien a la primera. Para un departamento de TI, ese es el camino que hay que presupuestar antes de lanzar un proyecto propio: meses de iteraciones para pasar de la demo a una herramienta fiable, y después un mantenimiento que no se acaba nunca.
Esto es lo que hace nuestro agente, en 40 segundos. Después repasamos las trampas una por una y, al final, las opciones entre construir y comprar.
Dos LLM que tienen que entenderse
En la mayoría de las arquitecturas trabajan dos modelos juntos:
- el agente principal conversa con el usuario, decide cuándo consultar la base y después redacta la respuesta;
- un generador de SQL, al que se llama como a una herramienta, recibe una pregunta y la estructura de la base, y escribe la consulta; la plataforma la ejecuta y devuelve el resultado al agente principal.
El reparto es lógico: el agente principal no necesita conocer 600 columnas para conversar, y el generador puede ser un modelo rápido y especializado.
Pero cada paso de uno a otro añade fricción. El agente principal reformula la pregunta del usuario antes de transmitirla, y a veces la reformula mal. Sobre todo, a veces inventa nombres de columnas verosímiles («filtra por tipo_contrato = 'Premium'») que el generador da por buenos, cuando la columna se llama nivel_contrato y el valor es PREMIUM.
Lo que cuestan las idas y vueltas
Cuando la consulta falla, el error sube al agente principal, que reformula y vuelve a llamar al generador, que reescribe, y la base vuelve a ejecutar. Cada vuelta añade varios segundos de espera y consume llamadas al modelo.
Si el error devuelto no ayuda a corregirse, el bucle gira en vacío. Por ejemplo, con un fallo que tuvimos en uno de nuestros clientes, una sola pregunta encadenó una veintena de llamadas fallidas: con cada error de columna, devolvíamos al modelo las columnas de otra tabla...
Eso es lo que nos llevó al enfoque agéntico. En lugar de hacer pasar cada intento por el agente principal, un analista de datos lleva él mismo la investigación, con la estructura real de la base a la vista, y solo devuelve el control con un resultado. En el cliente citado más arriba, pasamos de casi tres llamadas a la herramienta por respuesta a poco más de una.
Mantener la descripción de la base
Para escribir un SQL correcto, y rápido, el generador tiene que conocer la base: las tablas, las columnas y, sobre todo, lo que significan. En una base real, la columna del cliente facturado se llama cd_cli_2, el estado vale 1 o 2, y la facturación «se entiende sin abonos».
Lo habitual es que un administrador redacte una descripción de la base, que se pasa al generador con cada pregunta. Funciona, pero lleva mucho tiempo escribirla, y solo dos o tres personas en la empresa saben hacerlo. Sobre todo, es difícil de mantener: cada campo añadido, renombrado o eliminado deja la descripción desfasada, sin que nadie reciba aviso. Y en una base grande, la descripción completa ya no cabe en lo que se puede enviar al modelo con cada pregunta. Hay que elegir qué mostrar.
Cuando la descripción es errónea o incompleta, el modelo se equivoca sin saberlo. Escribe una consulta válida, sobre la columna equivocada, y la respuesta mostrada es falsa, con un modelo totalmente seguro de sí mismo. No aparece ningún error, y nadie se da cuenta hasta que un usuario ve una cifra que no cuadra.
La solución consiste en leer con regularidad la estructura en la propia base: la lista real de tablas y columnas, y los comentarios que tus equipos a veces ya han escrito en ella. Este diccionario de datos se actualiza cuando la base cambia, y las personas solo completan lo que falta.
Resultados de consultas que no caben en la respuesta
Una consulta que devuelve 5.000 filas no se puede enviar tal cual al modelo. Hay que guardar el resultado aparte, mostrarle solo una vista previa y permitirle recorrerlo página a página. En nuestro caso, el modelo ve como máximo 20 filas del resultado y lee el resto cuando lo necesita.
Este troceado crea un riesgo muy concreto: el modelo calcula sobre la vista previa. Se le muestran 20 filas, cuenta, hace una media y anuncia con aplomo una cifra falsa. Hay que prohibirle de forma explícita calcular sobre una muestra y remitirle a la base para cualquier agregado (COUNT, SUM, AVG sobre la tabla entera).
Después llegan las expectativas de los usuarios, que no quieren una tabla en bruto en el chat:
- un gráfico legible, construido a partir del conjunto de datos correcto;
- una exportación a Excel completa (en nuestro caso, hasta 50.000 filas), no solo las filas visibles;
- repreguntas sobre el mismo resultado («¿y solo para Andalucía?») sin volver a consultar la base para nada.
Cada una de estas funciones parece sencilla. Juntas, forman un pequeño producto.
La seguridad: un agente que solo debe leer
El riesgo de un agente que escribe SQL es que modifique tus datos: por error, o porque alguien lo manipula, con una instrucción colada en la pregunta de un usuario o en un contenido que lee. El caso del servidor MCP Postgres muestra que una protección que parece sólida puede ceder.
El MCP permite conectar una base a Claude, ChatGPT o Cursor con unas pocas líneas de configuración. El servidor Postgres de referencia envolvía cada consulta en una transacción de solo lectura. Datadog mostró en agosto de 2025 que bastaba un simple COMMIT; seguido de otra instrucción para salir de ella y ejecutar cualquier comando. El servidor se declaró obsoleto y se archivó.
La lección vale para todos los proyectos:
- el acceso de solo lectura debe venir de una cuenta de base de datos sin permisos de escritura, no de un filtro puesto por encima;
- cada consulta debe validarse antes de ejecutarse: una sola instrucción, nada de escritura, nada de tablas del sistema;
- el modelo no debe poder saltarse estas reglas, aunque un usuario se lo pida.
Los permisos de acceso: no todo el mundo debe verlo todo
Otro asunto que se descubre a menudo tarde: un comercial del sur no debe ver la facturación del norte, y un técnico no tiene por qué leer los salarios.
Con un servidor MCP o un script propio, el agente se conecta con una sola cuenta: cualquier usuario que hable con él ve todo lo que ve esa cuenta. Restringir por usuario supone conocer la identidad de la persona que hace la pregunta, transmitirla hasta la consulta y filtrar en consecuencia. Es factible, pero es una pieza de arquitectura en sí misma, que afecta a la autenticación de tu aplicación.
Construirlo uno mismo: lo que tu departamento de TI tendrá que mantener
Para quien quiera construirlo por su cuenta, Vanna es una de las bibliotecas open source de referencia en text-to-SQL. La versión 2.0, con licencia MIT, se reescribió en torno a un agente, con permisos por usuario y salidas en tablas y gráficos.
Pero la preparación sigue siendo cosa tuya: para que responda bien, hay que «entrenarla» con la estructura de la base, documentación de negocio y ejemplos de preguntas acompañados de la consulta SQL correcta. También hay que alojarla, integrarla con tu autenticación, conectarla a tus documentos y mantenerla con cada cambio de la base o de los modelos. Es un buen punto de partida, siempre que haya un equipo dedicado a ello de forma duradera.
Porque el desarrollo inicial es solo el principio. Una vez el agente en producción, alguien de tus equipos tendrá que, de forma permanente:
- seguir el esquema: cada tabla añadida o columna renombrada debe reflejarse en la descripción, si no el agente responde mal;
- seguir los modelos: los proveedores sacan nuevas versiones cada pocos meses y retiran las antiguas, y cambiar de modelo puede cambiar la forma en que el agente escribe su SQL;
- vigilar los errores: revisar las consultas fallidas y las respuestas discutidas, entender por qué, corregir;
- volver a pasar un juego de preguntas de referencia tras cada modificación, para comprobar que nada ha empeorado;
- mantener al día las salvaguardas: cuenta de solo lectura, validación de las consultas, permisos por usuario.
Un ejemplo: a mediados de octubre, un proveedor cambió de un día para otro la forma en que uno de sus modelos respetaba un formato de respuesta impuesto, y una de nuestras piezas tuvo que pasar a otro proveedor. Es nuestro oficio, así que nos ocupamos. En un departamento de TI, tus equipos dedicarán más tiempo a mantener un sistema de IA que a innovar en tu actividad principal, y ese tiempo casi nunca figura en el presupuesto del proyecto.
Desplegar sin desarrollar: Ask This Guy
Hemos construido lo que nos habría gustado encontrar: es el agente del vídeo del principio del artículo. Una base se conecta sin desarrollo, en unos minutos, y cada trampa descrita más arriba tiene su respuesta:
- Al conectarse, el agente lee las tablas, las vistas y las columnas, y recupera los comentarios ya presentes en la base. Tus equipos solo aclaran los códigos oscuros («
cd_cli_2es el cliente facturado»), sin escribir documentación, y el diccionario sigue los cambios de la base. - En modo agéntico, investiga en varias etapas: busca qué significa la pregunta, lee las columnas útiles, comprueba los valores y después lanza sus consultas, dentro de límites fijos (45 segundos, seis consultas como máximo). Cada etapa se muestra en la conversación.
- Solo lee: cuenta de solo lectura, una instrucción por consulta, tablas del sistema rechazadas.
- Sus resultados siguen siendo utilizables: conjuntos de datos conservados en la conversación, gráficos, exportación a Excel.
- El mismo agente busca en tus documentos (SharePoint, Notion, sitios web) y consulta tus bases en la misma respuesta.
El mantenimiento corre de nuestra cuenta: seguimiento de los modelos, salvaguardas, evolución del producto. Tus equipos, por tu parte, se ocupan de las preguntas de negocio.
Si tienes un proyecto en el que un agente debe acceder a tus datos, puedes reservar una cita: en unos clics configuramos el agente sobre tus propios datos y ves enseguida si es el enfoque adecuado. Para el panorama completo, están nuestra página Talk to Data y el artículo Tus bases de datos son una mina de oro.
Preguntas frecuentes
¿Qué es el text-to-SQL?
El text-to-SQL consiste en traducir una pregunta formulada en lenguaje natural a una consulta SQL, gracias a un modelo de lenguaje (LLM). La consulta se ejecuta sobre la base de datos y el resultado se reformula como respuesta. Es la técnica que permite «hablar con tus datos» sin saber SQL.
¿Por qué un agente text-to-SQL da respuestas erróneas?
Casi siempre porque no entiende la base: nombres de columnas oscuros, códigos sin explicación, descripción de las tablas incompleta o desfasada. El modelo escribe entonces una consulta válida sobre la columna equivocada, y la respuesta es falsa sin que aparezca ningún error. Calcular un total a partir de una simple vista previa del resultado es la otra causa frecuente.
¿Basta un servidor MCP Postgres para un uso en la empresa?
Para explorar los propios datos, sí. Para decenas de empleados, falta lo esencial: un acceso de solo lectura garantizado por una cuenta sin permisos de escritura, permisos por usuario, la comprensión de negocio de la base, la gestión de los resultados grandes y el cruce con los documentos.
¿Conviene construir el propio agente text-to-SQL o usar una solución existente?
Construir tiene sentido si cuentas con un equipo para mantener de forma duradera el motor, la descripción de la base, las salvaguardas y la interfaz. Hay que contar con meses para que el agente sea fiable y, después, con un mantenimiento continuo que ocupa a desarrolladores en lugar de dejarles trabajar en la actividad principal. Si tus preguntas cruzan varias bases y tus documentos, o si quieres un resultado en unos días, una solución existente te evita redescubrir una a una las trampas de la producción.
Para quien lance el proyecto por su cuenta, dos cosas van antes del primer prompt: crear una cuenta de base de datos de solo lectura y hacer la lista de las columnas que nadie del equipo sabe explicar. La cuenta te protege, y la longitud de la lista te dirá cuánto trabajo de descripción te espera.


