Crea un agente SQL con LangChain para consultar MySQL en lenguaje natural

Los datos de una empresa suelen estar detrás de un muro técnico. Sacar algo de ellos implicaba escribir SQL o aprender una herramienta rígida de apuntar y hacer clic. Una interfaz en lenguaje natural elimina esa capa intermedia, de modo que quien toma la decisión puede hacer la pregunta directamente y es su intención, no su habilidad técnica, la que guía el análisis. Un agente SQL construido sobre LangChain es una forma práctica de conseguirlo. A continuación verás qué hace el agente, cómo preparar el entorno y una base de datos MySQL de prueba, cómo montar el ejecutor y qué salvaguardas necesitas antes de que toque algo real.

Cómo se ha ido facilitando el acceso a los datos

Cada generación de herramientas ha ocultado más complejidad:

1. Los clientes de línea de comandos exigían una sintaxis exacta y un buen dominio del álgebra relacional.
2. Los constructores visuales de consultas ayudaron, pero seguías necesitando entender los joins y las relaciones entre tablas.
3. Los dashboards eran fáciles de leer, pero se limitaban a las vistas que alguien había preparado de antemano.
4. Las interfaces en lenguaje natural interpretan el significado, así que nadie necesita conocer el esquema ni un lenguaje de consultas.

Un agente SQL con IA aporta varias ventajas concretas:

• Lee el esquema por sí mismo y encuentra las tablas relevantes, las claves primarias y foráneas y las rutas de join.
• Relaciona las palabras corrientes con entidades de la base de datos y luego escribe y ejecuta consultas complejas sin que nadie intervenga.
• Solo obtiene el esquema de las tablas que importan, lo que reduce el consumo de tokens y el coste y mejora el rendimiento.
• Convierte preguntas vagas como «¿Cómo fueron las ventas el mes pasado?» en SQL determinista, deduciendo el contexto y emparejando entidades.

Eso solo funciona de forma fiable con la infraestructura adecuada alrededor: un framework de orquestación y un entorno aislado.

De qué se compone un agente SQL de LangChain

Un modelo de lenguaje que habla con una base de datos estructurada necesita un intermediario, y LangChain aporta el tejido conector: razonamiento, elección de herramientas y ciclos de ejecución que convierten un prompt en una operación segura sobre la base de datos. Sus agentes se diferencian por el estilo de razonamiento y por los modelos que admiten.

En el centro está el bucle ReAct, abreviatura de reasoning plus acting, es decir, razonar y actuar:

1. Seleccionar: el agente lee el prompt y elige una herramienta, como un ejecutor de SQL.
2. Actuar: ejecuta esa herramienta, por ejemplo lanzando la consulta generada.
3. Revisar: comprueba la salida y decide si basta o si hace falta otra pasada.
4. Repetir: el ciclo continúa hasta tener una respuesta final validada.

También tendrás que elegir entre dos diseños. Un sistema de una sola pasada trata cada pregunta por separado, con menos latencia y una optimización más sencilla. Uno conversacional mantiene el estado y gestiona el diálogo, de modo que la gente puede afinar la búsqueda con preguntas de seguimiento y resolver ambigüedades a lo largo de varios turnos, una especie de diálogo con los datos.

Entorno y dependencias

Para cualquier cosa que vaya camino de producción, aísla el entorno y fija las versiones, para que una actualización de una biblioteca no rompa el pipeline sin que te enteres. Crea y activa un entorno virtual:

pip install virtualenv
virtualenv my_env
source my_env/bin/activate

Después instala este stack exactamente en estas versiones:

• ibm-watsonx-ai==1.0.4 se encarga de la inferencia del modelo fundacional.
• ibm-watson-machine-learning==1.0.357 incorpora los LLM empresariales.
• langchain==0.2.1 es el framework central de orquestación para la lógica del agente.
• langchain-ibm==0.1.7 aporta envoltorios específicos del ecosistema de IBM.
• langchain-experimental==0.0.59 contiene utilidades adicionales para agentes.
• mysql-connector-python==8.4.0 es el driver de la base de datos.

La base de datos que consulta el agente

Un agente es tan preciso como su base de datos. Se apoya en los nombres de las tablas, las descripciones de las columnas y las relaciones entre claves para conectar una pregunta con los datos, así que el esquema tiene que estar limpio.

Chinook es un buen banco de pruebas porque modela todo un negocio de medios digitales:

• Tiene 11 tablas, entre ellas Artist, Album, Invoice y Track.
• Las claves primarias y foráneas permiten al agente recorrer joins entre varias tablas.
• Contiene más de 15 000 registros, suficientes para comprobar análisis de tendencias y consultas complejas.

El agente se conecta mediante una URI que debe seguir exactamente este patrón:

mysql+mysqlconnector://{mysql_username}:{mysql_password}@{mysql_host}:{mysql_port}/{database_name}

Se necesitan cinco valores: usuario, contraseña, host, puerto (3306 por defecto) y nombre de la base de datos, aquí Chinook.

Antes de que intervenga ningún LLM, confirma la conexión y el esquema desde la CLI de MySQL:

-- Verify database existence
SHOW DATABASES;
USE Chinook;

-- Confirm data integrity: This should return exactly 347
SELECT COUNT(*) FROM Album;

El recuento de álbumes debería ser exactamente 347. Una base de datos verificada da al modelo una base sólida y reduce las probabilidades de errores al anclarse en los datos.

Construir el ejecutor del agente

Lo siguiente es envolver el modelo y conectarlo a un ejecutor de base de datos, que determina cómo ve el agente tus datos y cómo trabaja con ellos.

Ajusta los parámetros del modelo para que sea determinista. En la generación de SQL, una salida impredecible lleva directamente a una sintaxis inventada, así que mantén las cosas estables.

El agente se crea con la factoría create_sql_agent, con ibm/granite-4-h-small como motor de razonamiento. Necesita estos argumentos:

• llm recibe el modelo Granite, envuelto en una instancia de WatsonxLLM.
• db recibe tu conexión SQLDatabase.
• verbose=True te permite ver lo que hace.
• agent_type, con el valor ZERO_SHOT_REACT_DESCRIPTION para preguntas analíticas corrientes.

No veas verbose=True como un simple interruptor de depuración. En un entorno empresarial es lo que hace posible la auditoría. Puedes revisar la cadena de razonamiento y comprobar que el SQL generado y los pasos seguidos encajan con la lógica interna de los datos y con las normas de cumplimiento antes de que la respuesta llegue a nadie.

Recuperación de errores y salvaguardas

El lenguaje ambiguo y el mapeo al esquema harán tropezar incluso a los modelos más potentes, así que un entorno de producción necesita salvaguardas automáticas y supervisión humana.

Uno de los puntos fuertes reales de este agente es la autocorrección. Cuando una consulta generada falla:

1. Captura el traceback del motor de la base de datos.
2. Averigua qué ha fallado, por ejemplo un error de sintaxis o un nombre de columna mal escrito.
3. Vuelve a intentarlo con una sentencia corregida, lo que aumenta la tasa de éxito en consultas complicadas.

Cuatro prácticas protegen los datos de la empresa:

1. Ejecuta cada consulta del agente en un entorno aislado para que nada se modifique por accidente.
2. Mantén a una persona en el circuito, con un experto que revise los hallazgos que se usen en informes importantes.
3. Pule los prompts de forma continua para cubrir variaciones en la redacción y particularidades del dominio.
4. Da al conector de la base de datos un perfil de usuario restringido, con seguridad estricta a nivel de fila y límites de privacidad.

En qué queda todo esto

Pasar de SQL puro a consultas en lenguaje natural abre los datos a mucha más gente. Combina un modelo preciso como ibm/granite-4-h-small con la orquestación estructurada de LangChain y reducirás la distancia entre el lenguaje corriente y las conclusiones útiles. Aun así, un sistema en el que se pueda confiar en producción sigue dependiendo de pruebas continuas y de una gobernanza firme.