Chat Inteligente | Agentes SQL

AdministradorSuper Administrador

Un agente SQL es la configuración con la que la aplicación consulta una base de datos desde el chat: define la fuente de datos, las tablas que tiene en cuenta, el modelo LLM (modelo de lenguaje) y el prompt con el que escribe y ejecuta las consultas. Desde esta pantalla podrás crear, buscar, editar y borrar esos agentes, que después se asignan a un perfil de conversación para que quien use ese perfil pueda preguntar sobre la base de datos en lenguaje natural. Para llegar a ella, haz clic en «RAG» en el menú superior de la pantalla y escoge «Agentes SQL»; solo la ven los roles Administrador y Super Administrador. Bajo el título, la aplicación resume su finalidad: «Configura y gestiona los agentes que consultan tus bases de datos SQL, eligiendo la fuente de datos, las tablas y el modelo que deben utilizar para obtener información».

En el panel situado sobre la tabla dispones de dos controles que se combinan entre sí, de modo que el listado muestra los agentes que cumplen ambos criterios a la vez. No hace falta confirmar la búsqueda con la tecla Intro: la tabla se actualiza sola medio segundo después de que dejes de escribir o cambies una opción.

• Buscar por nombre: escribe parte del nombre del agente en la caja con la lupa, situada en la parte superior izquierda del panel, y el listado mostrará los agentes que coincidan.
• Fuente de datos: el desplegable situado debajo del buscador recoge las fuentes de datos de tipo base de datos. Al elegir una, la tabla muestra solo los agentes que consultan esa fuente. La opción «Todas», que es la que viene marcada, quita el filtro.

De esta forma localizarás en segundos el agente que necesitas, aunque tu organización trabaje con varias bases de datos.

La tabla muestra un agente SQL por fila, con estas columnas:

• Nombre: el nombre con el que identificas al agente. Es el que verás después al asignarlo a un perfil de conversación.
• Fuente de datos: la fuente de datos sobre la que consulta el agente. Mientras se carga el nombre de la fuente aparece en su lugar una barra gris animada; si la fuente ya no existe, la celda se queda con esa barra gris.
• Modelo: el modelo LLM asignado al agente. Si no tiene ninguno, se muestra «Por defecto» en gris, lo que significa que el agente usará el modelo de la conversación en la que se le pregunte. Si el modelo asignado ya no está activo, se muestra su identificador técnico en lugar del nombre habitual.
• Tablas: las tablas que el agente tiene en cuenta. Si no se indicó ninguna, se muestra «Todas». Cuando la lista supera los 20 caracteres se recorta con puntos suspensivos, así que deja el cursor encima para leerla completa.

Bajo la tabla, el selector «Mostrando» fija cuántos agentes se ven por página: ofrece 10 por defecto, las opciones 20, 40 y 80 a medida que la lista crece, y «Todos» para verlos de una sola vez. Los botones «<<», el número de página y «>>» permiten moverte entre páginas. La aplicación recuerda el número de filas por página y la página en la que estabas, de forma que encuentres el listado tal y como lo dejaste la próxima vez que entres.

Cada fila termina con dos botones a la derecha:

• Editar: abre el formulario del agente con sus valores actuales.
• Borrar: elimina el agente después de pedirte confirmación.

1. Haz clic en «Crear»: el botón está situado en la esquina superior derecha del panel de búsqueda. Se abre la ventana «Crear agente SQL».
2. Completa los campos que se describen en el apartado siguiente.
3. Guarda el agente: haz clic en «Guardar» para crearlo, o en «Cancelar» para descartarlo.

Al guardar, el agente aparece en la tabla y se muestra el aviso "Se creó el agente SQL correctamente". Si algún campo no supera la validación, la ventana sigue abierta, el campo se marca en rojo con su mensaje de error debajo y aparece el aviso "No se pudo crear el agente SQL", de modo que podrás corregirlo sin perder lo que ya has escrito.

• Nombre: obligatorio. Es el nombre con el que identificarás el agente en la tabla y en los perfiles de conversación.
• Modelo LLM: el modelo de lenguaje con el que el agente escribe y resuelve las consultas. El desplegable lista los modelos LLM activos en tu organización. Si dejas la opción «Por defecto (modelo de la conversación)», se usará el modelo de la conversación desde la que se pregunte, tal y como recuerda el texto de ayuda "Si no eliges ninguno, se usará el modelo de la conversación.". Si el modelo elegido se desactiva antes de guardar, el servidor rechaza el agente con el error "El modelo seleccionado no está activo", pero la ventana solo muestra el aviso "No se pudo crear el agente SQL", sin marcar el campo. En ese caso, elige otro modelo activo y vuelve a guardar.
• Fuente de datos: obligatoria. Es la fuente de datos de tipo base de datos contra la que consultará el agente; si la dejas vacía verás el error "Debes seleccionar una fuente de datos". Las fuentes se crean en la pantalla «Fuentes de datos», tal y como se explica en el último apartado de este manual.
• Tablas: escribe los nombres de las tablas que el agente debe tener en cuenta, separados por coma, como indica el texto de ayuda "Indica las tablas que quieres que se tengan en cuenta separadas por coma. Si no especificas ninguna, se usarán todas.". Los espacios alrededor de las comas se ignoran. Limitar las tablas acota lo que el agente explora, lo que mejora la precisión de sus respuestas en bases de datos grandes.
• Prompt: obligatorio. Son las instrucciones que definen cómo se comporta el agente. El campo viene precargado con un prompt en inglés que fija un comportamiento seguro: crear una consulta correcta a partir de la pregunta, limitar los resultados a 10 salvo que se pida otra cantidad, consultar solo las columnas relevantes, revisar cada consulta antes de ejecutarla y reintentarla si falla, no ejecutar nunca sentencias de modificación (INSERT, UPDATE, DELETE, DROP, etc.) y responder "I don't know" cuando la pregunta no tenga relación con la base de datos. Podrás editarlo a mano o generarlo con «Mejorar con IA».

El botón «Mejorar con IA», situado a la derecha de la etiqueta «Prompt», permanece deshabilitado hasta que selecciones una «Fuente de datos», porque necesita conectarse a ella.

Desde las ventanas de crear y editar, el botón «Mejorar con IA» abre la ventana «Mejorar prompt con IA». En ella, un agente de IA explora el esquema y filas de ejemplo de la base de datos de la fuente seleccionada y redacta un prompt ajustado a ella, lo que te permite partir de unas instrucciones adaptadas a tus datos en lugar del prompt genérico. Para ello tiene en cuenta las «Tablas» que hayas indicado, el «Prompt» actual y el «Modelo LLM» elegido (o el modelo por defecto de la plataforma si dejaste «Por defecto (modelo de la conversación)»).

1. Revisa el prompt actual: la ventana lo abre en modo «Vista previa», con el texto formateado. Haz clic en «Editar» para modificarlo directamente y en «Vista previa» para volver al formato. Con «Copiar» lo llevarás al portapapeles y aparecerá el aviso "Prompt copiado al portapapeles"; este botón solo aparece si el prompt no está vacío.
2. Escribe tus directrices, de forma opcional, en el campo «Define las directrices para optimizar tu prompt», indicando lo que quieres que la IA tenga en cuenta. El campo sugiere ejemplos como "Céntrate en los informes de ventas mensuales" o "No muestres datos de márgenes". Bajo el campo, el recuadro «Consejo» recuerda: "Define el objetivo, las restricciones y el tipo de respuesta que esperas. La IA explorará el esquema y ejemplos seguros de la base de datos."
3. Haz clic en «Mejorar con IA». Mientras se genera, la ventana se cubre con el aviso "Un agente está explorando tu base de datos y redactando el prompt…". El proceso puede tardar un rato, porque explora la base de datos real y después llama al modelo, así que no cierres la ventana mientras se muestra el aviso.
4. Revisa el resultado: cuando termina, el prompt mejorado sustituye al anterior y se muestra en «Vista previa», aunque estuvieras editando. Aparece el aviso "Prompt mejorado correctamente. Puedes seguir perfeccionándolo o aplicar los cambios." y el recuadro cambia a «¡Prompt mejorado!». Las directrices se vacían para que puedas escribir otras. Podrás repetir el proceso tantas veces como quieras; cada pasada parte del prompt que haya en ese momento en la ventana.
5. Restaura el original si lo necesitas: para volver al prompt con el que abriste la ventana, haz clic en «Restaurar original». Este botón solo aparece cuando hay cambios. Al usarlo, el prompt vuelve al modo edición, el recuadro vuelve a «Consejo» y aparece el aviso "Prompt restaurado a la versión original".
6. Haz clic en «Aplicar cambios» para volcar el resultado al campo «Prompt» del formulario del agente, o en «Cancelar» para cerrar sin tocar el formulario. «Aplicar cambios» está deshabilitado si el prompt está vacío.

Es importante tener en cuenta que «Aplicar cambios» no guarda el agente: solo rellena el campo «Prompt». Para que el cambio se conserve, haz clic en «Guardar» en la ventana del agente.

Si la mejora falla, por ejemplo porque la fuente de datos no tiene una conexión configurada o porque el modelo elegido ya no está activo, aparece el aviso "Error al mejorar el prompt" y el prompt de la ventana no cambia.

1. Haz clic en «Editar»: el botón está a la derecha de la fila del agente que quieras modificar. Se abre la ventana «Editar agente SQL» con los valores actuales de «Nombre», «Modelo LLM», «Fuente de datos», «Tablas» y «Prompt», y con el botón «Mejorar con IA» también disponible.
2. Modifica los campos que necesites.
3. Guarda los cambios con «Guardar», o descártalos con «Cancelar».

Al guardar aparece el aviso "Se editó el agente SQL correctamente" y la tabla se actualiza. Si la validación falla, verás el aviso "No se pudo editar el agente SQL" y el campo afectado marcado en rojo; «Nombre» y «Prompt» siguen siendo obligatorios al editar.

Si el modelo que tenía asignado el agente ha dejado de estar activo en «Configuración», pestaña «Modelos LLM», el desplegable «Modelo LLM» aparece con «Por defecto (modelo de la conversación)» al abrir la ventana. Elige otro modelo activo, o guarda así para que el agente use el modelo de la conversación. Si el modelo se desactiva mientras tienes la ventana abierta, el servidor rechaza el cambio con el error "El modelo seleccionado no está activo" y verás el aviso "No se pudo editar el agente SQL".

Los cambios afectan a todos los perfiles de conversación que tengan asignado el agente a partir de la siguiente pregunta que se le haga, de modo que podrás ajustar su comportamiento desde un único sitio.

1. Haz clic en «Borrar»: el botón rojo del final de la fila del agente que quieras eliminar.
2. Confirma la acción en la ventana «Borrar agente SQL», que pregunta "¿Estás seguro que deseas borrar el agente '…'?" con el nombre del agente dentro de la pregunta.
3. Haz clic en «Confirmar» para eliminarlo, o en «Cancelar» para conservarlo.

Tras la eliminación aparece el aviso "Agente SQL eliminado con éxito" y el agente desaparece de la tabla. Si el borrado falla, aparece un aviso con el título "Error" y el motivo devuelto por el servidor, y el agente permanece en la tabla.

Antes de borrar, ten en cuenta qué se pierde:

• Se elimina solo la configuración del agente en la aplicación; los datos de la base de datos y la fuente de datos no se modifican.
• El borrado no comprueba si algún perfil de conversación usa el agente. Los perfiles que lo tenían asignado dejan de poder consultar la base de datos hasta que les asignes otro agente en su campo «Agente SQL».

Un agente SQL no guarda las credenciales de la base de datos: se apoya en una fuente de datos, que es donde se configura la conexión («Cadena de conexión» y «Dialecto SQL»). Para crear o modificar esa conexión, haz clic en «RAG» en el menú superior, escoge «Fuentes de datos» y configura una fuente de tipo «Base de datos SQL»; después podrás seleccionarla aquí, en el campo «Fuente de datos». En esta pantalla solo se listan las fuentes de datos de ese tipo. Es importante tener en cuenta que, si borras la fuente de datos o le quitas la conexión, los agentes que la usan dejan de funcionar aunque sigan en la tabla.

Para que un agente responda en el chat, asígnalo a un perfil de conversación desde la pantalla «Perfiles de conversación». En el perfil, elige «Agente SQL» en «Fuentes externas»; entonces aparece el campo «Agente SQL», donde seleccionas el agente y que es obligatorio con esa fuente. Un mismo agente puede estar asignado a varios perfiles, de forma que podrás reutilizar la misma configuración en distintos tipos de conversación.