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» (las herramientas con las que el asistente busca en tus documentos), opción «Agentes de extracción»; ese menú solo lo ven los usuarios con rol Administrador o Super Administrador.

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, por ejemplo, "Mostrando 10 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. Si es muy largo, la tabla lo recorta con puntos suspensivos para que quepa en una línea.
• ESQUEMA: el esquema, en formato JSON, de los datos que el agente extrae. Se muestra en una sola línea, recortado a 100 caracteres y al ancho de la columna; el texto completo aparece al pasar el cursor por encima.
• PROMPT: las instrucciones de extracción. Se muestra en una sola línea, recortado a 90 caracteres y al ancho de la columna. Al pasar el cursor por encima aparece el texto completo, salvo que el prompt contenga comillas dobles: en ese caso se corta en la primera de ellas, así que, para leerlo entero, ábrelo con «Editar».
• 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. El navegador 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 desde ese mismo navegador.

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 «>>», situados a la derecha del pie, 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.

Aunque la fila se resalta al pasar el ratón, hacer clic sobre ella no abre el agente: usa «Editar».

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 a la derecha del buscador, en la parte superior derecha de la pantalla. 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», a la izquierda de «Guardar», se cierra la ventana sin guardar nada.

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, la aplicación responde "El esquema es obligatorio". Cuando la aplicación 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" y "El prompt es obligatorio".

Es importante tener en cuenta que, tras un rechazo, «Guardar» vuelve a quedar activo aunque haya campos marcados en rojo, por lo que corrige cada campo señalado antes de volver a hacer clic en «Guardar»: el aviso de cada campo desaparece en cuanto lo editas. De esta forma evitarás que la aplicación vuelva a rechazar el guardado.

Si prefieres completar la ventana sin ratón, en el apartado «Usar el teclado en las ventanas» se explica cómo recorrer los campos y guardar con el teclado.

• Nombre: obligatorio y de hasta 255 caracteres; si lo superas, la aplicación muestra bajo el campo "El campo nombre debe ser menor que 255 caracteres.". Es el nombre con el que aparecerá el agente en la tabla y en el selector de las colecciones estructuradas.
• Esquema de extracción: obligatorio. Es 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. Son 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. Es un desplegable con los modelos de lenguaje activos de tu organización, ordenados alfabéticamente por su nombre comercial. No admite valor vacío y, al abrir la ventana, ya trae seleccionado el primer modelo activo por orden alfabético de su identificador técnico, que no tiene por qué coincidir con el primero de la lista; cámbialo si necesitas otro. Ten en cuenta que la columna «MODELO LLM» de la tabla muestra ese identificador técnico, de modo que el texto del desplegable y el del listado no son iguales aunque se refieran al mismo modelo. Si tu organización no tiene ningún modelo activo, el desplegable aparece vacío y la aplicación no guardará el agente ni mostrará ningún aviso en la ventana; pide a un Super Administrador que active antes un modelo en la pestaña «Modelos LLM» de «Configuración» (ver Configuración).

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. La aplicación vuelve a comprobar el esquema 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», a la izquierda de «Guardar», se descartan los cambios. El teclado funciona igual que al crear, tal y como se explica en el apartado «Usar el teclado en las ventanas».

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 la aplicación 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» vuelve a quedar activo aunque siga marcado alguno de esos campos, así que corrígelos antes de volver a guardar.

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, pero solo a los documentos que se procesen a partir de ese momento. Los documentos ya procesados conservan los datos extraídos con la versión anterior hasta que los reindexes con «Reindexar» desde la pantalla de documentos de la colección (ver Documentos). De esta forma podrás decidir qué documentos actualizar con el nuevo esquema.

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», pero recuerda que, si has llevado el foco con la tecla Tab hasta «Cancelar», Intro cancela el borrado en lugar de confirmarlo.

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. Los documentos que hayas subido mientras la colección estaba sin agente no se procesan solos al asignarlo: reindéxalos con «Reindexar» desde la pantalla de documentos.

Si el borrado falla, aparece un aviso con el título "Error": vuelve a intentarlo y, si se repite, avisa al administrador técnico de la aplicación en tu organización, ya que hasta que el borrado se complete el agente sigue en el listado y asignado a sus colecciones.

Mientras está abierta la ventana de crear o de editar un agente, el foco del teclado se queda dentro de ella: la tecla Tab recorre sus campos y botones sin saltar a la pantalla que hay detrás y, al pasar del último control, vuelve al primero. De esta forma podrás completar el formulario entero sin tocar el ratón.

La tecla Intro hace una cosa u otra según dónde esté el foco:

• En «Nombre», «Esquema de extracción» o «Prompt de extracción»: Intro equivale a «Guardar». Para insertar un salto de línea en el esquema o en el prompt usa Mayús+Intro. Es importante tener en cuenta que Intro envía el formulario aunque «Guardar» esté deshabilitado; en ese caso es la aplicación quien devuelve el error.
• En un botón de la ventana: Intro activa ese botón y no el guardado. Con el foco en «Cancelar», por ejemplo, Intro cierra la ventana sin guardar nada.
• En el desplegable «Modelo LLM»: Intro o las flechas arriba y abajo abren la lista. Con la lista abierta, las flechas arriba y abajo recorren los modelos y cada uno queda seleccionado en cuanto lo resaltas; Intro o Esc cierran la lista sin cerrar la ventana y conservan el último modelo resaltado, por lo que, si te pasas, vuelve con las flechas al modelo que querías.

Fuera del desplegable, Esc cierra la ventana sin guardar, igual que «Cancelar». Cuando la cierras de cualquiera de las dos formas, el foco vuelve al botón con el que la abriste, por lo que podrás seguir trabajando con el teclado desde el mismo punto de la pantalla. En la ventana «Borrar agente de extracción», Intro equivale a «Confirmar» y Esc a «Cancelar», tal y como se explica en el apartado «Borrar un agente de extracción».

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.