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.

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 del 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, ordenados alfabéticamente por nombre, 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.

Haz clic en la cabecera de cualquier columna para reordenar el listado por ese dato. Cada clic sobre la misma cabecera recorre tres estados: ascendente, descendente y el orden alfabético por nombre con el que llegó el listado. Ten en cuenta que la cabecera «Fuente de datos» ordena por el identificador interno de cada fuente y no por el nombre que ves, por lo que agrupa los agentes de una misma fuente, pero no coloca las fuentes por orden alfabético; para ver los agentes de una sola fuente resulta más práctico el filtro «Fuente de datos».

Bajo la tabla, el selector «Mostrando» fija cuántos agentes se ven por página, junto al total de agentes del listado: 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 la ordenación, 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 mensaje de error aparece en rojo debajo del campo y se muestra el aviso "No se pudo crear el agente SQL", de modo que podrás corregirlo sin perder lo que ya has escrito.

• Nombre: obligatorio; si lo dejas vacío verás el error "El campo nombre es requerido." y un icono rojo de aviso dentro de la caja. 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, por orden alfabético, 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, la aplicación no guarda el agente y muestra solo el aviso "No se pudo crear el agente SQL", sin marcar el campo «Modelo LLM». En ese caso, elige otro modelo activo y vuelve a guardar.
• Fuente de datos: obligatoria. Es la fuente de datos del 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 manual Fuentes de datos.
• 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 el esquema que el agente tiene en cuenta, lo que mejora la precisión de sus respuestas en bases de datos grandes. Es importante tener en cuenta que las tablas deben ir en una sola línea, separadas solo por comas: si usas saltos de línea, el agente no reconocerá las tablas y el asistente no podrá consultar la base de datos en el chat, aunque «Mejorar con IA» sí las interprete bien.
• Prompt: obligatorio ("El campo prompt es requerido."). Son las instrucciones que definen cómo se comporta el agente. El campo viene precargado con un prompt en inglés que indica al agente que cree una consulta correcta a partir de la pregunta, limite los resultados a 10 salvo que se pida otra cantidad, consulte solo las columnas relevantes, revise cada consulta antes de ejecutarla y la reintente si falla, no ejecute nunca sentencias de modificación (INSERT, UPDATE, DELETE, DROP, etc.) y responda "I don't know" cuando la pregunta no tenga relación con la base de datos. Podrás editarlo a mano o mejorarlo con «Mejorar con IA».

Es importante tener en cuenta que las indicaciones del prompt y la lista de «Tablas» orientan al agente, pero no bloquean técnicamente ninguna consulta. Para garantizar que no se modifiquen datos ni se lean tablas no deseadas, configura en la fuente de datos un usuario de base de datos de solo lectura y con acceso únicamente a las tablas necesarias. Si editas el prompt, a mano o con «Mejorar con IA», conserva la instrucción que prohíbe las sentencias de modificación.

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.

Al abrir la ventana, el cursor se sitúa en el campo «Nombre» y la tecla Tab recorre únicamente los controles de la ventana, sin saltar a la pantalla que queda detrás. Además, dispones de estas teclas:

• Intro: guarda el agente, igual que «Guardar», cuando el cursor está en un campo de texto. Si el foco está sobre un botón o un desplegable, como «Cancelar», «Mejorar con IA» o «Modelo LLM», Intro activa ese control en lugar de guardar; con un desplegable abierto, elige la opción resaltada.
• Mayús+Intro: inserta un salto de línea en «Prompt». Es importante tener en cuenta que en ese campo Intro también guarda el agente, por lo que para escribir en varias líneas necesitas esta combinación.
• Esc: cierra la ventana sin guardar, igual que «Cancelar». Si tienes abierto un desplegable, Esc lo cierra a él primero y la ventana sigue abierta.

Al cerrar la ventana, el foco vuelve al botón «Crear».

Desde las ventanas de crear y editar, el botón «Mejorar con IA» abre la ventana «Mejorar prompt con IA», que se superpone a la del agente: al cerrarla, vuelves al formulario con todos los datos tal y como los dejaste. 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. En la vista previa, las etiquetas del tipo <role> que estructuran el prompt aparecen resaltadas y, si el prompt incluye listas de casillas, podrás marcarlas o desmarcarlas ahí mismo y el cambio pasa al texto. 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…" y el botón queda deshabilitado. 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 ni uses la tecla Esc mientras se muestra el aviso, o perderás el resultado.
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.

En esta ventana, la tecla Intro no guarda nada ni salta de línea en los campos de texto: para escribir en varias líneas en el prompt o en las directrices, usa Mayús+Intro. Esc cierra la ventana sin aplicar los cambios y te devuelve al formulario del agente, igual que «Cancelar».

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».

Dentro de la ventana, el teclado funciona igual que al crear: Intro guarda, Mayús+Intro inserta un salto de línea en «Prompt» y Esc cierra sin guardar.

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 mensaje de error bajo el campo afectado; «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» (solo la ve el rol Super Administrador), 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, la aplicación no guarda el cambio y muestra solo el aviso "No se pudo editar el agente SQL", sin marcar el campo «Modelo LLM».

Es importante tener en cuenta que, en esta ventana, después de un cambio rechazado «Guardar» deja de responder, también con Intro y sin ningún aviso, hasta que elijas otro valor en «Modelo LLM» o corrijas el campo marcado en rojo. La ventana no está bloqueada: en cuanto modifiques el campo afectado, podrás volver a guardar.

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. Comprueba el nombre del agente: la ventana «Borrar agente SQL» pregunta "¿Estás seguro que deseas borrar el agente '…'?" con su nombre dentro de la pregunta.
3. Haz clic en «Confirmar» para eliminarlo, o en «Cancelar» para conservarlo.

Al abrirse la ventana, el foco queda sobre «Confirmar», así que la tecla Intro también borra el agente. Esc equivale a «Cancelar» y, si llevas el foco a «Cancelar» con la tecla Tab, Intro cancela el borrado.

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", sin más detalle, y el agente permanece en la tabla.

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

• Base de datos y fuente de datos: no se modifican; solo se elimina la configuración del agente.
• Perfiles que usan el agente: el borrado no comprueba si algún perfil de conversación lo tiene asignado, así que esos perfiles dejan de poder consultar la base de datos hasta que les asignes otro 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 del tipo «Base de Datos», tal y como se explica en el manual Fuentes de datos; 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», a la que llegas desde el menú «Usuarios», opción «Perfiles», y que se explica en el manual 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.