Knowledge Graph Agent

The Knowledge Graph Agent is an advanced AI assistant designed to provide accurate, verified answers by exploring a connected web of information (a knowledge graph) within your databases. Unlike standard search tools that simply look for keywords, this agent understands the relationships between different pieces of information.

Its primary purpose is to answer complex questions by automatically discovering relevant topics, retrieving precise facts from your database, and providing citations to prove where the information came from. It acts as a “Research Assistant” that not only finds the answer but also verifies its quality and accuracy before showing it to you.

How it Works

This component works by connecting to your data systems (such as PostgreSQL, MySQL, or SQLite databases) that contain structured knowledge. Here is a simple breakdown of the process:

Receiving Your Question: You provide a question in the User Query field.
Smart Search: The agent analyzes your question to identify which “domains” or categories of data are relevant. It then searches through your knowledge graph to find connected facts.
Retrieval & Verification: It retrieves specific documents or data chunks. If you enable Expert Mode, it will search across multiple categories automatically.
Answer Generation: The agent synthesizes an answer based on the found information. Crucially, it generates citations (references) so you can see exactly which document or section supports the answer.
Quality Check (Optional): If configured, it can run an extra check using another AI model to grade the answer for quality and accuracy (grounding), ensuring the information is reliable.

Connection & Credentials

This component connects directly to your database and AI models. To use it, you must configure the following connections in your Nappai workflow:

Database: Connect a PostgreSQL, MySQL, or SQLite component. This is where your knowledge graph is stored.
LLM: Connect a Large Language Model (LLM) to handle the reasoning and answer generation.
Embeddings: Connect an Embedding model that matches the one used to build your knowledge graph. This ensures the agent understands the language of your data.
Judge LLM (Optional): You can connect a separate LLM specifically for quality evaluation. If left blank, it uses the main LLM for this task.

Operations

Note: This component operates primarily through configuration inputs rather than separate “operations” tabs. However, its behavior changes based on the Operation dropdown field, which determines the workflow mode:

Search: Use this for standard queries. The agent will return a single answer with citations.
Evaluate: Use this to get an answer along with a quality score from the AI judge.
Benchmark: Use this to run multiple test queries automatically and generate a performance report.

Important: Ensure you select the appropriate mode in the Operation field to align with your goal.

Inputs

The following fields are available to configure this component. These settings allow you to fine-tune how the agent searches your data.

User Query: The specific question you want the agent to answer.
Operation: Determines the mode (Search, Evaluate, or Benchmark).
Database: The connection to your data source (PostgreSQL/MySQL/SQLite).
LLM: The main AI model used to generate answers.
Judge LLM: A separate model for quality checks (optional).
Embeddings: The model used to understand data structures; must match your graph’s embedding model.
Expert Mode: When enabled, the agent automatically discovers and searches across all relevant domains in the graph. Disable this if you want to focus on a single category.
Table Prefixes: Comma-separated prefixes (e.g., kgraph_) to scan for tables. Leave empty to auto-discover.
Domains Filter: Specify which data categories to include (e.g., normativas_nia). Leave empty to search all.
Domain Descriptions: A JSON dictionary providing extra context for specific domains to help the AI understand them better.
Mandatory Domains: Categories that must always be searched (e.g., critical legal norms).
Primary Domains: Categories searched by default for faster results.
Document-Only Domains: Categories that only have summaries (no detailed graph). This skips complex searches for speed.
Top K: The number of results to return per search action.
System Prompt: Customize how the agent behaves. When “Use System Prompt” is off, Nappai adds standard rules automatically. When on, your text is used exactly.
Use System Prompt: Toggle to use your custom prompt instead of the default Nappai rules.
Citation Metadata Fields: Which details (like URL or Section) to include in the final citation.
Language: The language for the agent’s response (e.g., English, Spanish).
Stream Progress: Show live updates while the agent is searching.
Graph Hops: How deep the agent should search in the graph (more hops = more context, but slower).
Chunk Search Multiplier: Controls result diversity vs. speed.
Max Chunks per Document: Limits how much text is taken from each source.
Min Score Threshold: Filters out weak answers (0.0 = no filtering).
Max Search Attempts: How many times the agent will try searching before giving up.
Recursion Limit: Max steps the agent can take to reason.
Enable Retriever Grading: Ask the AI to check if search results are relevant before answering.
Document Finder: Adds a tool to search document titles/summaries by name.
Summary Search: Searches document summaries for conclusions and doctrine.
Section Expansion: Automatically includes full sections (like a whole Chapter) if one part is relevant.
Section Expansion Level: The level to expand (e.g., CAPÍTULO, Sección).
Skip Graph: Skips the graph structure for faster searches (uses only keywords/facts).
Hybrid Taxonomy Search: Classifies questions into themes for more precise searches.
Planner Mode: Uses a “planner” AI to create a search strategy first, improving accuracy but adding slight delay.
Planner Prompt: Custom instructions for the planner AI.
Grader LLM: Separate model for checking if search results are good.
Evaluate (LLM-as-Judge): Run a quality check after generating the answer.
Enable Grounding Check: Ensures the answer is actually supported by the data found.
Quality Instructions: Rules for how the judge should score quality.
Grounding Instructions: Rules for how the judge should verify facts.
Benchmark Queries: A list of test questions for benchmarking mode.
Include Multi-Domain Queries: Add complex cross-category test questions.
Tools: Add extra tools the agent can use alongside the graph search.
Supervisor Prompt: Instructions for the supervisor AI that coordinates specialists (in advanced modes).
Enable Streaming: Stream live events from the supervisor.
Specialist Streaming: Stream detailed data from specialist agents.
Iterative Supervisor Review: Automatically retry if quality is low.
Max Review Iterations: Max retries for the review loop.
Auto-Review Instructions: Instructions for the AI when it needs to retry.
Min Quality Score: Minimum score required to accept an answer.
Require Grounding: Force the answer to be factually grounded.
Review Required Domains: Keywords that trigger a review process.
Use Memory: Allow the agent to remember previous steps in a conversation.
Memory: Connect memory components for stateful conversations.
Memory Strategy: How to manage conversation history.
Memory Limit: Max messages to keep (-1 for unlimited).

Outputs

The component produces a structured response that includes the final answer and its supporting evidence.

Answer: The direct text response to your query.
Citations: References to the specific documents, sections, or graph nodes that support the answer.
Quality Score: (If evaluation is enabled) A score from 0 to 1 indicating how accurate and grounded the answer is.
Feedback: (If evaluation is enabled) Comments on why the score was given.

Output Data Example (JSON)

{
  "answer": "The minimum audit fee for small entities is determined by NIA-ES 230, which requires professional judgment based on risk.",
  "sources": [
    {
      "document": "NIA-ES 230",
      "section": "Paragraph 2",
      "url": "https://example.com/standards/230.pdf",
      "relevance": "Directly defines fee determination principles."
    }
  ],
  "quality_score": 0.95,
  "is_grounding_verified": true
}

Connectivity

In a typical Nappai workflow:

Connect To: This component should be connected to a Database node (PostgreSQL/MySQL/SQLite) and an LLM node.
Connected From: It typically receives input from a User Query node (text input) or another agent that passes along a question.
Output Destination: The output usually feeds into a Text Display widget, a Document Generator, or another agent for further processing.

Usage Example

Scenario: You need to find the specific regulations regarding audit fees for small companies.

Setup: Connect your Knowledge Graph Agent to your company’s legal database (Database input) and a standard LLM (LLM input).
Configure:
- Set Operation to Search.
- In Domains Filter, enter normativas_nia.
- Enable Expert Mode if you want to search broader categories as well.
Execute:
- In the User Query field, type: “What are the requirements for determining audit fees according to NIA-ES?”
- Click Run.
Result: The agent will return a text answer explaining the requirements and provide a citation linking to the specific paragraph in the NIA-ES standard document, allowing you to verify the information.

Important Notes

Development Status: This component is currently in development mode (is_development: true). This means features or inputs may change without notice. It is recommended for testing and prototyping rather than critical production workflows until marked as stable.
Performance: Searching through complex knowledge graphs can take time. Adjust Graph Hops and Max Search Attempts to balance speed vs. thoroughness.
Embedding Match: The Embeddings input must use the exact same model that was used to build your knowledge graph. Mismatched models will result in poor search results.

Tips and Best Practices

Use Citations for Verification: Always review the provided citations. The agent provides references so you can trust the answer, but human verification is best for critical decisions.
Enable Expert Mode for Broad Questions: If your question touches on multiple topics (e.g., “Legal and Financial aspects of Audits”), turn on Expert Mode so the agent searches all relevant domains automatically.
Use “Planner Mode” for Complex Queries: If a question is very complex and requires checking several different sources, enable Planner Mode. It creates a plan before searching, which improves accuracy.
Set Quality Thresholds: If you need high precision, enable Evaluate (LLM-as-Judge) and set a Min Quality Score. This ensures the agent re-checks its work before finalizing the answer.
Optimize Speed: For large databases, consider enabling Skip Graph if you only need keyword matching, or lower the Graph Hops value to speed up the response.

Security Considerations

Data Access: Ensure your Database connection has the appropriate permissions. The agent will only access data that the connected database user is allowed to read.
Hallucination Control: Use Require Grounding and Enable Retriever Grading to minimize the risk of the AI making up facts. These checks force the agent to stick to the provided documents.
Input Sanitization: As with any LLM input, ensure that the User Query does not contain malicious instructions intended to bypass the agent’s safety rules.