Knowledge Graph Agent

El Knowledge Graph Agent es un asistente de IA avanzado diseñado para ofrecer respuestas precisas y verificadas explorando una red conectada de información (un grafo de conocimiento) dentro de tus bases de datos. A diferencia de las herramientas de búsqueda estándar que simplemente buscan palabras clave, este agente entiende las relaciones entre las distintas piezas de información.

Su propósito principal es responder preguntas complejas descubriendo automáticamente los temas relevantes, recuperando datos precisos de tu base de datos y proporcionando citas que demuestran de dónde proviene la información. Actúa como un “asistente de investigación” que no solo encuentra la respuesta, sino que también verifica su calidad y precisión antes de mostrártela.

Cómo funciona

Este componente se conecta a tus sistemas de datos (como bases de datos PostgreSQL, MySQL o SQLite) que contienen conocimiento estructurado. Este es un resumen sencillo del proceso:

Recepción de tu pregunta: Escribes una pregunta en el campo User Query.
Búsqueda inteligente: El agente analiza tu pregunta para identificar qué “dominios” o categorías de datos son relevantes. A continuación, busca en tu grafo de conocimiento para encontrar hechos conectados.
Recuperación y verificación: Recupera documentos o fragmentos de datos específicos. Si activas Expert Mode, buscará automáticamente en múltiples categorías.
Generación de la respuesta: El agente sintetiza una respuesta basada en la información encontrada. Lo más importante es que genera citas (referencias) para que puedas ver exactamente qué documento o sección respalda la respuesta.
Control de calidad (opcional): Si está configurado, puede ejecutar una comprobación adicional usando otro modelo de IA para puntuar la calidad y la precisión (grounding) de la respuesta, garantizando que la información sea fiable.

Conexión y credenciales

Este componente se conecta directamente a tu base de datos y a tus modelos de IA. Para usarlo, debes configurar las siguientes conexiones en tu flujo de trabajo de Nappai:

Base de datos: Conecta un componente PostgreSQL, MySQL o SQLite. Aquí es donde se almacena tu grafo de conocimiento.
LLM: Conecta un modelo de lenguaje (LLM) que se encargue del razonamiento y la generación de respuestas.
Embeddings: Conecta un modelo de embeddings que coincida con el que se usó para construir tu grafo de conocimiento. Esto garantiza que el agente entienda el lenguaje de tus datos.
Judge LLM (opcional): Puedes conectar un LLM independiente específicamente para la evaluación de calidad. Si lo dejas en blanco, se usará el LLM principal para esta tarea.

Operaciones

Nota: Este componente funciona principalmente mediante campos de configuración en lugar de pestañas de “operaciones” separadas. Sin embargo, su comportamiento cambia según el desplegable Operation, que determina el modo de trabajo:

Search: Úsalo para consultas estándar. El agente devolverá una única respuesta con citas.
Evaluate: Úsalo para obtener una respuesta junto con una puntuación de calidad del juez de IA.
Benchmark: Úsalo para ejecutar múltiples consultas de prueba automáticamente y generar un informe de rendimiento.

Importante: Asegúrate de seleccionar el modo apropiado en el campo Operation según tu objetivo.

Entradas

Los siguientes campos están disponibles para configurar este componente. Estos ajustes te permiten afinar cómo el agente busca en tus datos.

User Query: La pregunta específica que quieres que el agente responda.
Operation: Determina el modo (Search, Evaluate o Benchmark).
Database: La conexión a tu fuente de datos (PostgreSQL/MySQL/SQLite).
LLM: El modelo de IA principal usado para generar respuestas.
Judge LLM: Un modelo independiente para los controles de calidad (opcional).
Embeddings: El modelo usado para entender las estructuras de datos; debe coincidir con el modelo de embeddings de tu grafo.
Expert Mode: Cuando está activado, el agente descubre y busca automáticamente en todos los dominios relevantes del grafo. Desactívalo si quieres centrarte en una sola categoría.
Table Prefixes: Prefijos separados por comas (p. ej., kgraph_) para escanear tablas. Déjalo vacío para el descubrimiento automático.
Domains Filter: Especifica qué categorías de datos incluir (p. ej., normativas_nia). Déjalo vacío para buscar en todas.
Domain Descriptions: Un diccionario JSON que proporciona contexto adicional sobre dominios específicos para ayudar a la IA a entenderlos mejor.
Mandatory Domains: Categorías en las que siempre se debe buscar (p. ej., normas legales críticas).
Primary Domains: Categorías en las que se busca por defecto para obtener resultados más rápidos.
Document-Only Domains: Categorías que solo tienen resúmenes (sin grafo detallado). Esto omite las búsquedas complejas para ganar velocidad.
Top K: El número de resultados que se devuelven por cada acción de búsqueda.
System Prompt: Personaliza cómo se comporta el agente. Cuando “Use System Prompt” está desactivado, Nappai añade reglas estándar automáticamente. Cuando está activado, se usa tu texto tal cual.
Use System Prompt: Activa esta opción para usar tu prompt personalizado en lugar de las reglas predeterminadas de Nappai.
Citation Metadata Fields: Qué detalles (como URL o sección) incluir en la cita final.
Language: El idioma de la respuesta del agente (p. ej., inglés, español).
Stream Progress: Muestra actualizaciones en vivo mientras el agente busca.
Graph Hops: La profundidad de búsqueda del agente en el grafo (más saltos = más contexto, pero más lento).
Chunk Search Multiplier: Controla la diversidad de los resultados frente a la velocidad.
Max Chunks per Document: Limita cuánto texto se toma de cada fuente.
Min Score Threshold: Filtra las respuestas débiles (0.0 = sin filtrado).
Max Search Attempts: Cuántas veces intentará buscar el agente antes de rendirse.
Recursion Limit: Número máximo de pasos que el agente puede dar para razonar.
Enable Retriever Grading: Pide a la IA que compruebe si los resultados de búsqueda son relevantes antes de responder.
Document Finder: Añade una herramienta para buscar títulos y resúmenes de documentos por nombre.
Summary Search: Busca en los resúmenes de documentos conclusiones y doctrina.
Section Expansion: Incluye automáticamente secciones completas (como un capítulo entero) si una parte es relevante.
Section Expansion Level: El nivel a expandir (p. ej., CAPÍTULO, Sección).
Skip Graph: Omite la estructura del grafo para búsquedas más rápidas (usa solo palabras clave/hechos).
Hybrid Taxonomy Search: Clasifica las preguntas en temas para búsquedas más precisas.
Planner Mode: Usa una IA “planificadora” para crear primero una estrategia de búsqueda, mejorando la precisión pero añadiendo un ligero retraso.
Planner Prompt: Instrucciones personalizadas para la IA planificadora.
Grader LLM: Modelo independiente para comprobar si los resultados de búsqueda son buenos.
Evaluate (LLM-as-Judge): Ejecuta un control de calidad después de generar la respuesta.
Enable Grounding Check: Garantiza que la respuesta esté realmente respaldada por los datos encontrados.
Quality Instructions: Reglas sobre cómo el juez debe puntuar la calidad.
Grounding Instructions: Reglas sobre cómo el juez debe verificar los hechos.
Benchmark Queries: Una lista de preguntas de prueba para el modo benchmark.
Include Multi-Domain Queries: Añade preguntas de prueba complejas que cruzan varias categorías.
Tools: Añade herramientas adicionales que el agente puede usar junto con la búsqueda en el grafo.
Supervisor Prompt: Instrucciones para la IA supervisora que coordina a los especialistas (en modos avanzados).
Enable Streaming: Transmite eventos en vivo desde el supervisor.
Specialist Streaming: Transmite datos detallados de los agentes especialistas.
Iterative Supervisor Review: Reintenta automáticamente si la calidad es baja.
Max Review Iterations: Número máximo de reintentos del bucle de revisión.
Auto-Review Instructions: Instrucciones para la IA cuando necesita reintentar.
Min Quality Score: Puntuación mínima requerida para aceptar una respuesta.
Require Grounding: Obliga a que la respuesta esté basada en hechos verificados.
Review Required Domains: Palabras clave que activan un proceso de revisión.
Use Memory: Permite al agente recordar pasos anteriores de una conversación.
Memory: Conecta componentes de memoria para conversaciones con estado.
Memory Strategy: Cómo gestionar el historial de la conversación.
Memory Limit: Número máximo de mensajes a conservar (-1 para ilimitado).

Salidas

El componente produce una respuesta estructurada que incluye la respuesta final y la evidencia que la respalda.

Answer: La respuesta de texto directa a tu consulta.
Citations: Referencias a los documentos, secciones o nodos del grafo específicos que respaldan la respuesta.
Quality Score: (Si la evaluación está activada) Una puntuación de 0 a 1 que indica cuán precisa y fundamentada es la respuesta.
Feedback: (Si la evaluación está activada) Comentarios sobre por qué se asignó esa puntuación.

Ejemplo de datos de salida (JSON)

{
  "answer": "Los honorarios mínimos de auditoría para entidades pequeñas se determinan según la NIA-ES 230, que requiere juicio profesional basado en el riesgo.",
  "sources": [
    {
      "document": "NIA-ES 230",
      "section": "Párrafo 2",
      "url": "https://example.com/standards/230.pdf",
      "relevance": "Define directamente los principios de determinación de honorarios."
    }
  ],
  "quality_score": 0.95,
  "is_grounding_verified": true
}

Conectividad

En un flujo de trabajo típico de Nappai:

Conectar a: Este componente debe conectarse a un nodo de Base de datos (PostgreSQL/MySQL/SQLite) y a un nodo LLM.
Conectado desde: Normalmente recibe la entrada de un nodo de consulta de usuario (entrada de texto) o de otro agente que le pasa una pregunta.
Destino de la salida: La salida suele alimentar un widget de visualización de texto, un generador de documentos u otro agente para su procesamiento posterior.

Ejemplo de uso

Escenario: Necesitas encontrar la normativa específica sobre honorarios de auditoría para empresas pequeñas.

Configuración: Conecta tu Knowledge Graph Agent a la base de datos legal de tu empresa (entrada Database) y a un LLM estándar (entrada LLM).
Configura:
- Establece Operation en Search.
- En Domains Filter, escribe normativas_nia.
- Activa Expert Mode si también quieres buscar en categorías más amplias.
Ejecuta:
- En el campo User Query, escribe: “¿Cuáles son los requisitos para determinar los honorarios de auditoría según las NIA-ES?”
- Haz clic en Run.
Resultado: El agente devolverá una respuesta de texto explicando los requisitos y proporcionará una cita que enlaza con el párrafo específico del documento de la norma NIA-ES, permitiéndote verificar la información.

Notas importantes

Estado de desarrollo: Este componente está actualmente en modo development (is_development: true). Esto significa que las funciones o entradas pueden cambiar sin previo aviso. Se recomienda para pruebas y prototipado, no para flujos de trabajo críticos en producción hasta que se marque como estable.
Rendimiento: Buscar en grafos de conocimiento complejos puede llevar tiempo. Ajusta Graph Hops y Max Search Attempts para equilibrar velocidad y exhaustividad.
Coincidencia de embeddings: La entrada Embeddings debe usar exactamente el mismo modelo que se utilizó para construir tu grafo de conocimiento. Si los modelos no coinciden, los resultados de búsqueda serán pobres.

Consejos y buenas prácticas

Usa las citas para verificar: Revisa siempre las citas proporcionadas. El agente incluye referencias para que puedas confiar en la respuesta, pero la verificación humana es lo mejor para decisiones críticas.
Activa Expert Mode para preguntas amplias: Si tu pregunta toca varios temas (p. ej., “aspectos legales y financieros de las auditorías”), activa Expert Mode para que el agente busque automáticamente en todos los dominios relevantes.
Usa “Planner Mode” para consultas complejas: Si una pregunta es muy compleja y requiere consultar varias fuentes distintas, activa Planner Mode. Crea un plan antes de buscar, lo que mejora la precisión.
Establece umbrales de calidad: Si necesitas alta precisión, activa Evaluate (LLM-as-Judge) y configura un Min Quality Score. Esto garantiza que el agente revise su trabajo antes de dar la respuesta final.
Optimiza la velocidad: Para bases de datos grandes, considera activar Skip Graph si solo necesitas coincidencia de palabras clave, o reduce el valor de Graph Hops para acelerar la respuesta.

Consideraciones de seguridad

Acceso a los datos: Asegúrate de que tu conexión de Database tenga los permisos apropiados. El agente solo accederá a los datos que el usuario de la base de datos conectada tenga permitido leer.
Control de alucinaciones: Usa Require Grounding y Enable Retriever Grading para minimizar el riesgo de que la IA invente hechos. Estas comprobaciones obligan al agente a ceñirse a los documentos proporcionados.
Saneamiento de entradas: Como con cualquier entrada a un LLM, asegúrate de que la User Query no contenga instrucciones maliciosas destinadas a eludir las reglas de seguridad del agente.