Chat Inteligente | Agentes de extracción

AdministradorSuper Administrador

Un agente de extracción es una configuración que lee documentos y devuelve sus datos con una estructura fija: un esquema que defines tú, un prompt con las instrucciones y el modelo LLM (modelo de lenguaje) que hace el trabajo. Desde esta pantalla podrás crear, buscar, editar y borrar esos agentes, que después se asignan a las colecciones de documentos de tipo «Estructurada» para que todos sus documentos se procesen igual. Se accede desde el menú «RAG» (Retrieval Augmented Generation, la técnica con la que el asistente busca en tus documentos antes de responder), opción «Agentes de extracción»; ese menú solo lo ven los usuarios con rol Administrador o Super Administrador. Bajo el título de la pantalla, la aplicación recuerda su finalidad: «Crea agentes especializados para extraer información estructurada de documentos asignándolos a colecciones estructuradas».

Para localizar un agente, escribe parte de su nombre en el campo «Buscar por nombre», situado en la parte superior izquierda de la pantalla. La búsqueda se lanza sola medio segundo después de que dejes de escribir, por lo que no hace falta confirmar con la tecla «Intro», y encuentra el texto en cualquier posición del nombre. Si dejas el campo vacío, la tabla vuelve a mostrar todos los agentes de la organización.

Si ningún nombre coincide, la tabla se queda solo con las cabeceras y el pie indica "elementos de 0": borra parte del texto para ampliar la búsqueda. Cuando la búsqueda no se puede completar, aparece el aviso "Error al buscar agentes:" y la tabla se queda vacía; en ese caso vuelve a escribir en el campo para repetir la consulta. De esta forma localizarás en segundos el agente que necesitas aunque tu organización tenga decenas configurados.

La tabla muestra un agente por fila, ordenados alfabéticamente por nombre, con estas columnas:

• Nombre: el nombre con el que identificas el agente. Es el que verás al asignarlo a una colección estructurada, así que conviene que describa qué tipo de documento procesa.
• Esquema: el esquema, en formato JSON, de los datos que el agente extrae. Se muestra recortado a 100 caracteres; el texto completo aparece al pasar el cursor por encima.
• Prompt: las instrucciones de extracción. Se muestra recortado a 90 caracteres y, como en la columna anterior, el texto completo aparece al pasar el cursor por encima.
• Modelo LLM: el identificador técnico del modelo de lenguaje con el que trabaja el agente.

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 original con el que llegó el listado. La aplicación recuerda esa ordenación, junto con 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.

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. Con «Todos», el pie pasa a indicar "Mostrando Todos los elementos" y deja de contar el total. Los botones «<<», el número de página y «>>» permiten moverte entre páginas.

Cada fila incluye dos acciones a la derecha:

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

Si la ventana del navegador es estrecha, la propia tabla se desplaza en horizontal: deslízala hacia la derecha para llegar a la columna «Modelo LLM» y a las acciones «Editar» y «Borrar». De esta forma podrás consultar el listado completo también desde una pantalla pequeña.

1. Haz clic en «Crear», el botón situado en la esquina superior derecha del buscador. Se abre la ventana «Crear agente de extracción» con el cursor puesto en el campo «Nombre».
2. Completa los cuatro campos que se describen en el apartado siguiente. Todos son obligatorios.
3. Haz clic en «Guardar». Mientras se guarda, el botón queda deshabilitado y muestra un indicador de carga. A continuación la ventana se cierra, aparece el aviso "Agente creado correctamente" y el agente se añade a la tabla. Con «Cancelar» se cierra la ventana sin guardar nada.

Dentro de la ventana, la tecla Intro equivale a «Guardar» y Esc a «Cancelar». Para insertar un salto de línea en «Esquema de extracción» o en «Prompt de extracción» usa Mayús+Intro. Es importante tener en cuenta que Intro envía el formulario aunque «Guardar» esté deshabilitado; en ese caso es el servidor quien devuelve el error.

El botón «Guardar» permanece deshabilitado mientras el «Esquema de extracción» tenga contenido que no pase la validación. Si lo dejas vacío, el botón sigue activo y al guardar el servidor responde "El esquema es obligatorio". Cuando el servidor rechaza algún dato, el campo afectado se marca en rojo con su mensaje debajo y la ventana permanece abierta para que lo corrijas. Los mensajes por campo vacío son "El nombre es obligatorio", "El esquema es obligatorio", "El prompt es obligatorio" y, si no hay ningún modelo seleccionado, "Debe seleccionar un modelo de LLM".

Es importante tener en cuenta que, mientras un campo siga marcado en rojo, «Guardar» permanece deshabilitado: el aviso desaparece en cuanto editas ese campo —en «Modelo LLM», en cuanto eliges un valor en el desplegable— y el botón vuelve a activarse. De esta forma sabrás siempre qué te queda por corregir antes de volver a intentar el guardado.

• Nombre (obligatorio, hasta 255 caracteres): el nombre con el que aparecerá el agente en la tabla y en el selector de las colecciones estructuradas.
• Esquema de extracción (obligatorio): la estructura, en formato JSON, de los datos que quieres obtener de cada documento. El campo aparece vacío, con un ejemplo en gris claro a modo de guía que no se guarda si no escribes nada encima. Se valida mientras escribes: cuando el esquema es correcto aparece el mensaje "Esquema válido para Pydantic" (Pydantic es la biblioteca con la que el sistema comprueba los datos extraídos) y, cuando no lo es, el error concreto. Debajo del campo tienes un bloque «Ejemplo válido:» con un esquema de muestra que puedes seleccionar y copiar, y la nota "Tipos soportados: string, integer, number, boolean, object, array".
• Prompt de extracción (obligatorio): las instrucciones que sigue el modelo para localizar en el documento cada dato del esquema. Cuanto más concreto seas sobre dónde aparece cada dato, menos variaciones tendrá el resultado entre documentos parecidos.
• Modelo LLM (obligatorio): desplegable con los modelos de lenguaje activos de tu organización, ordenados alfabéticamente y con su nombre comercial. No admite valor vacío y, al abrir la ventana, ya trae un modelo seleccionado que no tiene por qué ser el primero de la lista; cámbialo si necesitas otro. Ten en cuenta que la columna «Modelo LLM» de la tabla muestra en su lugar el identificador técnico de ese mismo modelo, de modo que el texto del desplegable y el del listado no son iguales aunque se refieran al mismo modelo.

El esquema debe cumplir las reglas que se indican a continuación. Cuando incumple alguna, el formulario muestra el motivo bajo el campo y «Guardar» queda deshabilitado:

• JSON bien formado: si el texto no es JSON válido aparece "El formato JSON no es válido".
• properties: el esquema debe ser un objeto con esa propiedad, que es la que contiene los campos a extraer.
• type: cada campo lleva uno de los tipos soportados —string, integer, number, boolean, object o array— y admite además una description para orientar la extracción, tal y como hace el ejemplo de la ventana.
• required: es opcional; si la incluyes debe ser un array y cada nombre que contenga debe existir en properties.
• Campos de tipo object: pueden llevar sus propias properties y su propio required, que se validan con las mismas reglas.
• Campos de tipo array: deben llevar items indicando el tipo de sus elementos.

Los errores de estructura se muestran con el prefijo "Esquema inválido para Pydantic:" seguido del detalle, por ejemplo la propiedad que falta o el campo con un tipo no soportado. El servidor aplica las mismas reglas al guardar, de forma que si le llega un esquema incorrecto (por ejemplo, al enviar con Intro) responde "El esquema no es un JSON válido" o "El esquema no tiene una estructura válida para Pydantic".

Este es el ejemplo válido que muestra la ventana, aquí con saltos de línea para leerlo mejor:

{
  "properties": {
    "nombre": { "type": "string", "description": "Nombre completo" },
    "edad": { "type": "integer" },
    "activo": { "type": "boolean" }
  },
  "required": ["nombre"]
}

1. Haz clic en «Editar» en la fila del agente. Se abre la ventana «Editar agente de extracción» con los valores actuales de «Nombre», «Esquema de extracción», «Prompt de extracción» y «Modelo LLM».
2. Modifica lo que necesites. El esquema se valida con las mismas reglas que al crear y los cuatro campos siguen siendo obligatorios.
3. Haz clic en «Guardar». Mientras se guarda, el botón queda deshabilitado y muestra un indicador de carga. Después aparece el aviso "Agente de extracción se ha editado correctamente" y la tabla se actualiza. Con «Cancelar» se descartan los cambios. Intro equivale a «Guardar» y Esc a «Cancelar», igual que al crear.

Revisa el campo «Modelo LLM» antes de guardar: el desplegable se rellena con la lista de modelos activos y puede quedar seleccionado uno distinto del que tenía el agente. De esta forma evitarás cambiar el modelo sin darte cuenta.

Si el servidor rechaza los cambios, aparece un aviso con el título "No se pudo editar el agente de extracción" y el detalle del error, y los campos afectados se marcan en rojo dentro de la ventana. Igual que al crear, «Guardar» queda deshabilitado mientras siga marcado alguno de esos campos y vuelve a activarse en cuanto lo editas.

Las colecciones estructuradas guardan únicamente la referencia al agente, sin copia de su esquema ni de su prompt, por lo que los cambios que guardes aquí se aplican a todas las colecciones que lo usan.

1. Haz clic en «Borrar» en la fila del agente. Se abre la ventana «Borrar agente de extracción» con el mensaje "¿Estás seguro que deseas borrar el agente de extracción '…'? Las colecciones estructuradas que actualmente usen este agente quedarán sin agente de extracción asignado.", donde aparece el nombre del agente.
2. Haz clic en «Confirmar» para eliminarlo, o en «Cancelar» para conservarlo. Intro equivale a «Confirmar» y Esc a «Cancelar».

Una vez borrado aparece el aviso "Agente de extracción eliminado con éxito" y el agente desaparece de la tabla. Las colecciones estructuradas que lo usaban se quedan sin agente asignado, y mientras estén así los documentos que subas a ellas no se procesarán. Para que vuelvan a funcionar, edita cada colección y asígnale otro agente. Si el borrado falla, aparece un aviso con el título "Error": vuelve a intentarlo y, si se repite, avisa al responsable técnico de tu instalación de la aplicación, porque hasta que el borrado se complete el agente sigue en el listado y sigue asignado a sus colecciones.

Los agentes de esta pantalla se eligen al crear o editar una colección de tipo «Estructurada», en el campo «Agente de extracción», que es obligatorio para ese tipo de colección. Esa configuración vive en la pantalla «Colecciones de documentos», a la que se llega desde el menú «RAG», opción «Colecciones». Al crear la colección, en cuanto seleccionas un agente, la aplicación muestra su «Esquema de extracción» y su «Prompt» en modo lectura, de forma que puedas comprobar que has escogido el adecuado antes de continuar. Desde la colección podrás cambiar el agente asignado, pero no su esquema ni su prompt: esos se modifican aquí, desde la pantalla de agentes de extracción.

A partir de ese momento, cada documento que subas a la colección se procesa con el agente asignado: la aplicación aplica su prompt y su esquema con el modelo LLM indicado, guarda el resultado como un archivo .json junto al documento original y lo indexa para que el asistente pueda responder sobre esos datos. El detalle de la configuración de colecciones está en el manual de Colecciones de documentos.