# Core Components of the GraphRAG Agent System: A Complete Technical Architecture

> Explore the core components of the GraphRAG Agent system. Understand its six modular domains for end-to-end knowledge graph construction and RAG.

- Repository: [GLK/graph-rag-agent](https://github.com/1517005260/graph-rag-agent)
- Tags: architecture
- Published: 2026-02-22

---

**The GraphRAG Agent system comprises six modular domains—ingestion and graph construction, RAG search, graph-centric reasoning, evaluation, deployment, and infrastructure—that together enable end-to-end knowledge graph construction and retrieval-augmented generation.**

The GraphRAG Agent is a production-ready Python framework designed to transform unstructured documents into intelligent knowledge graphs for enhanced retrieval-augmented generation. According to the `1517005260/graph-rag-agent` source code, understanding the core components of the GraphRAG Agent system reveals a sophisticated architecture that bridges document processing, Neo4j graph databases, and multi-strategy search capabilities.

## Knowledge Ingestion and Graph Construction

The ingestion pipeline converts raw documents into a structured Neo4j knowledge graph with vector indexes. This domain handles everything from file parsing to entity extraction and embedding generation.

### Document Processing and Chunking

The pipeline begins with [`graphrag_agent/pipelines/ingestion/document_processor.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/pipelines/ingestion/document_processor.py), where the **`DocumentProcessor`** class orchestrates reading and metadata extraction. For text segmentation, [`graphrag_agent/pipelines/ingestion/text_chunker.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/pipelines/ingestion/text_chunker.py) provides the **`ChineseTextChunker`**, which splits long texts into semantic chunks optimized for downstream processing.

### Graph Structure and Indexing

Schema definition occurs in [`graphrag_agent/graph/structure/struct_builder.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/graph/structure/struct_builder.py) via the **`GraphStructureBuilder`**, which establishes node and edge types. Vector storage is managed by two specialized indexers: **`ChunkIndexManager`** in [`graphrag_agent/graph/indexing/chunk_indexer.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/graph/indexing/chunk_indexer.py) handles text-chunk embeddings, while **`EntityIndexManager`** in [`graphrag_agent/graph/indexing/entity_indexer.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/graph/indexing/entity_indexer.py) stores entity embeddings for similarity search.

### Knowledge Graph Builder

The integration layer in [`graphrag_agent/integrations/build/build_graph.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/integrations/build/build_graph.py) features the **`KnowledgeGraphBuilder`**, which executes the complete pipeline and persists nodes and edges to Neo4j. This class coordinates the extraction of entities and relations while ensuring efficient batch writing operations.

```python

# Ingest a folder of documents

from graphrag_agent.pipelines.ingestion.file_reader import FileReader
from graphrag_agent.pipelines.ingestion.document_processor import DocumentProcessor
from graphrag_agent.integrations.build.build_graph import KnowledgeGraphBuilder

files = FileReader.read_folder("/path/to/documents")
processor = DocumentProcessor()
graph_builder = KnowledgeGraphBuilder()
graph_builder.build(processor.process(files))

```

## RAG Search Architecture

The search domain provides multiple retrieval strategies that combine keyword lookup, vector similarity, and graph traversal to supply relevant context for LLM generation.

### Local and Global Search Strategies

[`graphrag_agent/search/local_search.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/local_search.py) implements **`LocalSearch`**, which performs fast intra-index lookup using keyword and vector methods. For cross-index retrieval and graph reasoning, [`graphrag_agent/search/global_search.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/global_search.py) contains **`GlobalSearch`**, which can traverse relationships across the entire knowledge graph when local results require expansion.

### Search Tool Ecosystem

All search tools inherit from **`BaseSearchTool`** defined in [`graphrag_agent/search/tool/base.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/tool/base.py). The concrete implementations include:

- **`NaiveSearchTool`** ([`graphrag_agent/search/tool/naive_search_tool.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/tool/naive_search_tool.py)): Simple BM25-style keyword search
- **`LocalSearchTool`** ([`graphrag_agent/search/tool/local_search_tool.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/tool/local_search_tool.py)): Vector-based retrieval for semantic similarity
- **`HybridSearchTool`** ([`graphrag_agent/search/tool/hybrid_tool.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/tool/hybrid_tool.py)): Combines local and global search strategies
- **`DeepResearchTool`** ([`graphrag_agent/search/tool/deep_research_tool.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/tool/deep_research_tool.py)): Iterative reasoning with chain-of-thought capabilities

```python

# Perform a RAG query

from graphrag_agent.search.local_search import LocalSearch
from graphrag_agent.search.global_search import GlobalSearch

query = "How does the university support postgraduate research?"
local = LocalSearch()
global_ = GlobalSearch()

local_results = local.search(query)
if not local_results:
    final_results = global_.search(query)
else:
    final_results = local_results

```

## Graph-Centric Reasoning Components

This domain enables the agent to navigate the knowledge graph dynamically, generate hypotheses, and perform multi-hop reasoning before synthesizing answers.

### Multi-Hop Query Generation

[`graphrag_agent/search/tool/reasoning/search.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/tool/reasoning/search.py) contains **`DualPathSearcher`** and **`QueryGenerator`**, which generate and execute complex multi-hop Cypher queries. These classes analyze the query intent to determine optimal traversal paths through the graph.

### Dynamic Knowledge Enhancement

The reasoning layer includes **`DynamicKnowledgeGraphBuilder`** in [`graphrag_agent/search/tool/reasoning/kg_builder.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/tool/reasoning/kg_builder.py), which constructs temporary sub-graphs for specific queries. **`EvidenceChainTracker`** in [`graphrag_agent/search/tool/reasoning/evidence.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/tool/reasoning/evidence.py) maintains provenance metadata throughout the reasoning process, while **`CommunityAwareSearchEnhancer`** in [`graphrag_agent/search/tool/reasoning/community_enhance.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/tool/reasoning/community_enhance.py) leverages community detection algorithms to broaden retrieval scope when initial results are insufficient.

## Evaluation Framework

The evaluation domain supplies comprehensive metrics to measure retrieval quality, LLM response coherence, and graph-level relevance.

### Retrieval and Response Metrics

[`graphrag_agent/evaluation/metrics/retrieval_metrics.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/evaluation/metrics/retrieval_metrics.py) provides **`RetrievalPrecision`** and **`RetrievalLatency`** for assessing search performance. LLM output quality is measured by **`ResponseCoherence`** and **`FactualConsistency`** in [`graphrag_agent/evaluation/metrics/llm_metrics.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/evaluation/metrics/llm_metrics.py). Graph-specific metrics include **`CommunityRelevanceMetric`** and **`GraphCoverageMetric`** located in [`graphrag_agent/evaluation/metrics/graph_metrics.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/evaluation/metrics/graph_metrics.py).

The **`GraphRAGRetrievalEvaluator`** in [`graphrag_agent/evaluation/evaluators/retrieval_evaluator.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/evaluation/evaluators/retrieval_evaluator.py) orchestrates the complete evaluation pipeline, executing benchmark queries and aggregating metric scores.

```python

# Run an evaluation benchmark

from graphrag_agent.evaluation.evaluators.retrieval_evaluator import GraphRAGRetrievalEvaluator

evaluator = GraphRAGRetrievalEvaluator(
    metric_names=["RetrievalPrecision", "ResponseCoherence"]
)
evaluator.evaluate(test_dataset_path="/path/to/benchmark")

```

## Deployment and API Layer

The deployment domain exposes the agent through production-ready web interfaces.

### FastAPI Backend Services

[`server/main.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/main.py) serves as the FastAPI entry point, mounting routers for endpoints like `/chat` and `/knowledge_graph`. The chat logic resides in [`server/routers/chat.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/routers/chat.py), which handles user messages and invokes the appropriate RAG pipeline based on query classification.

### Streamlit Frontend Interface

[`frontend/app.py`](https://github.com/1517005260/graph-rag-agent/blob/main/frontend/app.py) implements the Streamlit UI, providing an interactive chat interface that connects to the FastAPI backend and visualizes knowledge graph subsets during conversations.

## Infrastructure and Utilities

Supporting utilities ensure efficient operations and monitoring.

[`server/utils/cache.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/utils/cache.py) implements an on-disk cache for LLM responses to reduce redundant API calls. Concurrent processing is managed through [`server/utils/concurrent.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/utils/concurrent.py), which provides thread-pool utilities for async endpoints. For graph operations, [`server/utils/neo4j_batch.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/utils/neo4j_batch.py) contains batch writers that optimize Neo4j ingestion throughput, while [`server/utils/performance.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/utils/performance.py) provides timers and logging for latency analysis.

## Summary

- **Ingestion Pipeline**: Converts documents to knowledge graphs using `DocumentProcessor`, `ChineseTextChunker`, and `KnowledgeGraphBuilder` with vector indexes managed by `ChunkIndexManager` and `EntityIndexManager`.
- **Search Architecture**: Provides `LocalSearch` for fast retrieval and `GlobalSearch` for graph-aware reasoning, implemented through specialized tools like `HybridSearchTool` and `DeepResearchTool`.
- **Reasoning Layer**: Enables multi-hop navigation via `DualPathSearcher` and dynamic sub-graph construction through `DynamicKnowledgeGraphBuilder`.
- **Evaluation Suite**: Measures system performance using `GraphRAGRetrievalEvaluator` with metrics for retrieval precision, factual consistency, and graph coverage.
- **Deployment Stack**: Delivers the system via FastAPI ([`server/main.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/main.py)) and Streamlit ([`frontend/app.py`](https://github.com/1517005260/graph-rag-agent/blob/main/frontend/app.py)) with shared configuration management.
- **Infrastructure**: Supports production operations with caching, batch Neo4j writes, and performance monitoring utilities.

## Frequently Asked Questions

### What is the difference between LocalSearch and GlobalSearch in the GraphRAG Agent system?

**LocalSearch** ([`graphrag_agent/search/local_search.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/local_search.py)) performs fast keyword and vector-based lookups within specific indexes, ideal for direct semantic matches. **GlobalSearch** ([`graphrag_agent/search/global_search.py`](https://github.com/1517005260/graph-rag-agent/blob/main/graphrag_agent/search/global_search.py)) executes cross-index retrieval with graph traversal, enabling multi-hop reasoning across the entire knowledge graph when queries require relationship exploration beyond simple similarity.

### How does the GraphRAG Agent handle document ingestion?

The system uses `DocumentProcessor` to orchestrate file reading and metadata extraction, `ChineseTextChunker` for semantic text segmentation, and `KnowledgeGraphBuilder` to extract entities and relations before persisting to Neo4j. Vector embeddings are stored via `ChunkIndexManager` and `EntityIndexManager` to support hybrid retrieval strategies.

### What evaluation metrics are available in the GraphRAG Agent framework?

The framework provides retrieval metrics (`RetrievalPrecision`, `RetrievalLatency`), LLM response metrics (`ResponseCoherence`, `FactualConsistency`), and graph-specific metrics (`CommunityRelevanceMetric`, `GraphCoverageMetric`). These are orchestrated by `GraphRAGRetrievalEvaluator` to benchmark system performance against test datasets.

### How is the GraphRAG Agent deployed in production?

The system deploys via a FastAPI backend ([`server/main.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/main.py)) exposing REST endpoints for chat and knowledge graph operations, paired with a Streamlit frontend ([`frontend/app.py`](https://github.com/1517005260/graph-rag-agent/blob/main/frontend/app.py)) for interactive visualization. Both components utilize shared configuration files and benefit from utilities like [`neo4j_batch.py`](https://github.com/1517005260/graph-rag-agent/blob/main/neo4j_batch.py) for efficient database operations and [`cache.py`](https://github.com/1517005260/graph-rag-agent/blob/main/cache.py) for response optimization.