FalkorDB
Solutions
Use cases
Why FalkorDB
Developers

Agentic GraphRAG: Your Agent Plans, FalkorDB Keeps It Honest

featured-image
Agentic GraphRAG · FalkorDB

Your agent plans. FalkorDB keeps it honest.

Agentic GraphRAG on FalkorDB: GraphRAG-SDK gives the agent you already run, whether that's Claude Code, Cursor, a LangGraph or pydantic-ai agent, or your own, a set of bounded tools over a FalkorDB knowledge graph. Every piece of evidence comes back numbered, every citation can be checked, and the same agent can build the graph from a folder with a plan tailored to each file. Here's how it works and how to use it.

●●●agentic-graphrag · architecture
The whole architecture in 40 seconds. An agent asks, the toolkit searches FalkorDB without writing to it, evidence comes back numbered, the citations are checked, and the same agent builds the graph from a folder.
01

We didn't build another agent. We built the ground it stands on.

Agents are everywhere, and they're good at planning. What they lack is a source of knowledge they can query safely and cite honestly.

So GraphRAG-SDK does not run an agent loop. Your agent plans, calls the graph tools and writes the answer. The SDK makes every one of those calls safe: it runs each one bounded, runs its own graph queries as GRAPH.RO_QUERY while retrieve's searches only read, numbers every piece of evidence it returns, and gives the agent check_​citations to verify the [n] citations in its draft against that evidence before it replies.

Agentic GraphRAG in three layers: your agent plans and writes, the toolkit bounds, numbers and checks, FalkorDB stores and answers queries
A clean division of labour. The agent keeps the judgement, FalkorDB keeps the knowledge, and the toolkit between them keeps every exchange bounded and verifiable.

Reach for the tools when a question needs more than one lookup: "which suppliers are connected to this plant", multi-hop chains, comparisons. For a plain question about the content, rag.​completion() answers it in a single step.

The agent keeps the judgement. FalkorDB keeps the facts. Every citation in the answer can be traced to the graph.
02

Eight tools, one contract

Three tools read the graph, one checks the answer, and four handle ingestion. An operator decides which ones an agent sees: read_only=True hides the ingestion tools entirely, and include= narrows the set further.

Read the graph
statusEntity, relation, document and chunk counts, with every label and relation type
get_ontologyDeclared entity and relation types with their (source, target) patterns, plus live counts
retrieveHybrid search for a question: entities, relations, facts and source passages
Check the answer
check_citationsVerifies every [n] in a draft answer against the evidence it was given
Build the graph
preview_filesOne sample from the middle of each file, to design an ontology from
set_ontologyAdds entity and relation types and patterns, and updates descriptions. Never removes
ingestAdds text, or files under a root folder with a plan per file
finalizeDeduplicates, embeds and indexes after a batch of ingests

Every tool honours the same contract. Input is validated against a strict schema. Each call returns a typed result, and to_llm_text() renders it compactly for a model, sharing space fairly across sections and giving the source passages twice the room, so a long list of entities can't crowd them out. A call with bad arguments, or to a tool that isn't available, raises ToolError with a hint that names the fix, so the agent knows what to do next. Calling an ingestion tool on a read-only toolkit raises ReadOnlyViolation.

agent_tools.py
from graphrag_sdk.tools import GraphRAGToolkit

toolkit = GraphRAGToolkit(rag, read_only=True)

for spec in toolkit.tool_specs():          # name, description, JSON Schema
    register_with_your_agent(spec.name, spec.description, spec.input_schema)

result = await toolkit.call("retrieve", {"question": "Where does Alice work?"})
print(result.to_llm_text())                # compact text with [n] evidence numbers

Any framework that accepts a name, a description and a JSON Schema can register these tools as-is. Multi-tenant setups get GraphRAGToolkit.​for_​tenant(base_​config, "acme", ...​), which binds a toolkit to that tenant's own graph.

03

retrieve: five search paths in one call

One call to retrieve runs a hybrid search, combining vector, full-text and graph search, across five paths. By default it runs all five. An agent that knows what a question needs can name just the paths that fit:

Agentic GraphRAG retrieval: retrieve fans out into five search paths over the graph
One call, five ways in. The results come back as one typed set of entities, relations, facts and passages, each with its own evidence number.

Which paths fit which question:

Questionexact_namesfuzzy_namesfactslinkspassages
“What do we know about Acme Corp's supply chain?”retrieve(question) # all five run●●●●●
“Who works with Maya Ellison?”retrieve(question, paths=["exact_names", "links"])●○○●○
“Which company owns the firm that supplies Acme's steel?”retrieve(question), then expand_hops=3 to walk three hops out●●●●●
“Why did Acme switch steel suppliers?”retrieve(question, paths=["exact_names", "passages", "facts"])●○●○●
The agent picks the paths. These follow the guide the MCP server hands every client: name the paths a question needs, leave them out for broad questions, and go deeper with exact names, links or more hops when the first call misses.

The walk is precise at every step. links follows edges in both directions and each edge once, and every requested hop gets its own share of the results, so the first hop can't crowd out the deeper ones. Lookups only ever return entities that are actually stored, and no embedding vector or internal node label ever reaches the model's prompt.

04

Evidence with numbers, answers with receipts

Every entity, edge, fact and passage a tool returns carries an evidence number. So does each status and get_ontology result, so even an answer about the graph itself can be cited. The numbers run across every call in a session, one per conversation, so an answer can cite results from several calls. Before replying, the agent runs check_​citations on its draft, as the MCP server's guide tells every client to. Here is one draft, checked:

Acme Corp depends on Northwind Steel [2] and Polar Logistics [3]. Northwind ships 4,200 tonnes a month [6]. Kestrel Ports joined the network last spring [9]. The graph does not say who founded Polar Logistics.
grounded: truethe draft cites real evidence
cited [2] [3] [6]numbers a tool returned in this session
invalid [9]points at nothing, so it's removed from the answer
unsupportedflagged: “4,200” is not in the text of [6]
uncitedflagged: with [9] removed, “Kestrel Ports” has no [n] of its own
not flaggeda sentence saying the graph lacks something needs no citation
A literal check, with no LLM involved. Figures must appear as numbers in the cited evidence, and every word of three or more letters in a name must appear in it as a whole word, in any letter case (a trailing Inc or GmbH aside). An honest "the graph doesn't say" needs no citation. Unbacked claims are flagged for the agent to fix. Claim warnings never flip grounded; only citing no real evidence does.
session = toolkit.new_session()               # one numbering per conversation
found = await session.retrieve("Where does Alice work?")
check = await session.check_citations(draft)
check.grounded      # cites at least one real piece of evidence
check.invalid       # numbers that point at nothing; removed from check.answer
check.uncited       # sentences stating a figure or a name with no [n]
check.unsupported   # cited sentences whose figures or names the evidence lacks

A marker can cite one item ([3]), a list ([1, 4]) or a range ([1-3]). Because the check is deterministic, the same draft against the same evidence always gets the same verdict.

05

Read-only by construction

A read tool can't write, and that isn't left to a prompt to enforce. The toolkit's own graph queries (counts, ontology, entity cards, relation expansion, the existence check) run as GRAPH.RO_QUERY, so FalkorDB itself refuses any write. retrieve's search paths run the SDK's standard retrieval queries, which only read.

Missing means missing

A graph that was never written or has been deleted is never silently created. retrieve and get_ontology raise an error naming it, and status says so in its hint.

Down means down

If FalkorDB is unreachable, the call says Could not reach the graph store instead of reporting an empty graph the agent might believe.

Nothing internal leaks

Results never carry embedding vectors or internal __Label__ names. The model only sees what it can reason about.

Errors say what to do

Graph 'kb' does not exist.​ Hint: Ingest documents (and finalize) first… An agent can recover from that without a human.

06

MCP: plug the graph into any agent

The same tools ship as an MCP server, graphrag-mcp. Any MCP client can then search, cite and build a FalkorDB knowledge graph with nothing more than a config entry.

Agentic GraphRAG over MCP: clients connect over stdio or SSE to graphrag-mcp, which serves FalkorDB
One server, every client. Each connection gets its own evidence numbering, so one client can never cite another's evidence.
pip install "graphrag-sdk[mcp,markdown,pdf]"
graphrag-mcp --read-only                                  # stdio, for local MCP clients
graphrag-mcp --files-root ./corpus                        # can also build the graph from ./corpus
GRAPHRAG_MCP_TOKEN=... graphrag-mcp --transport sse --host 0.0.0.0   # network, token required
.mcp.json
{
  "mcpServers": {
    "graphrag": {
      "command": "graphrag-mcp",
      "args": ["--read-only"],
      "env": { "FALKOR_HOST": "localhost", "GRAPHRAG_GRAPH": "my_graph", "OPENAI_API_KEY": "sk-..." }
    }
  }
}
  • Secure on the network. Serving SSE on a non-loopback host without a bearer token is refused. A loopback server accepts only requests whose Host (and Origin, when sent) names it, which blocks DNS rebinding.
  • Writes need a yes. ingest, set_ontology and finalize carry MCP's destructive annotation, so clients that honour MCP annotations ask the user before running them.
  • Your models, your choice. GRAPHRAG_MODEL and GRAPHRAG_​EMBED_​MODEL pick the LLM and the embedder, and GRAPHRAG_​EMBED_​DIM its dimension; use the same embedding model and dimension the graph was built with.
  • A guide comes with the tools. The server tells every client how to use them well: call retrieve first with the user's question word for word, go deeper with exact names or expand_hops when needed, cite [n], and always run check_​citations before replying.
07

From a folder to a graph, driven by the agent

Give the toolkit a files_root and an agent can build the graph itself from a folder of .txt, .md, .markdown, .rst and .pdf files. Clients that honour MCP annotations ask you before each write.

1

Settle the ontology

Ask the user for one. Otherwise page through preview_files, which gives one sample from the middle of every file, then declare one ontology for the whole corpus with set_ontology.

2

Ingest with a plan

ingest(files=[...​], plan=[rules]), globs welcome. The first rule that matches a file picks its chunker, extractor and resolver.

3

Finalize once

After the last batch, finalize deduplicates, embeds and indexes.

4

Close the gaps

Each result's pruned says what the ontology misses, and for relations whose type pair wasn't declared, its hint gives the exact set_ontology call that keeps them. Extend the ontology, then re-extract just those files.

toolkit = GraphRAGToolkit(rag, files_root="corpus/")
await toolkit.set_ontology(
    entities=[{"label": "Drug"}, {"label": "Disease"}],
    relations=[{"label": "TREATS", "patterns": [["Drug", "Disease"]]}],
)
result = await toolkit.ingest(
    files=["notes/*.md", "reports/*.pdf"],
    plan=[{"match": "*.md", "chunker": "structural"}, {"match": "*", "chunker": "sentence"}],
)
print(result.pruned)       # what the ontology misses
await toolkit.finalize()

Re-running is safe. An unchanged file is skipped, and a changed file is replaced in place rather than added beside its old chunks. Within a toolkit or MCP server, an update or re-extraction runs on its own, so its cleanup never touches something a parallel ingest has just written. The file root is guarded too: .., absolute paths, hidden files and symlinks leading out of it are refused.

08

A plan per document, tuned by you

Chunking, extraction and entity resolution decide graph quality, and the right choice depends on the document. Pass auto=True and a planner inspects a sample of each document and picks all three for it.

DocumentchunkerextractorresolverWhy
handbook.mdstructuralplannerglinerplannerexactplannerMarkdown with headings keeps its structure, so each chunk follows a section.
meeting_notes.txtsentenceplannerglinerplannerexactplannerPlain prose with no headings or lists gets sentence chunking, the default.
handbook.md, you pass a resolverstructuralplannerglinerplannerExactMatchResolution()callerExplicit wins: a strategy you pass is never overridden. The planner only fills the rest.
Example plans, and every decision is recorded. result.​metadata["plan"] stores the plan, its reason, and where each slot came from: caller, planner or default.
from graphrag_sdk import HeuristicIngestionPlanner

await rag.ingest(source="handbook.md", auto=True)                 # one small LLM call decides
await rag.ingest(source="handbook.md", planner=HeuristicIngestionPlanner())   # zero cost
await rag.ingest(source="handbook.md", auto=True,
                 plan_limits={"chunkers": ("sentence", "structural", "contextual"),
                              "extractors": ("gliner", "llm")})      # allow costlier options
PlannerCostHow it decides
LLMIngestionPlannerOne small LLM call per documentA guided prompt over a sample of the document. The default with auto=True
HeuristicIngestionPlannerZeroCheap features: file extension, headings, lists
RuleBasedIngestionPlannerZeroYour rules: the first glob that matches the file. This is what the agent's ingest tool uses

You decide what a plan may use

With auto=True, and in the toolkit, the planner picks only strategies that add no LLM calls beyond the one extraction call per chunk: sentence, fixed or structural chunking, gliner entity extraction and exact resolution. Turn on richer ones, like contextual chunking, the llm extractor or llm_verified resolution, through plan_limits: on rag.ingest() for your own pipeline, or on GraphRAGToolkit(...​, files_​root=...​) for an agent, whose tool description then tells it what each option costs in LLM calls, so it spends them only where a file benefits.

  • Clamped parameters. The planner may tune values like chunk size, but every value is coerced and clamped to a safe range, so a model can never produce an unsafe config.
  • Never silently broken. An empty or invalid plan, or a planner error, falls back to safe defaults (sentence / gliner / exact, or the first option you allowed). A slot that can't be built falls back on its own, while the others still follow the plan.
  • Document text is data. The sample the planner reads is quoted and marked as data. Even content written to steer it can only land on an option you already allowed.
09

The path router: only the paths a question needs

rag.​completion() can be selective too. MultiPathRetrieval runs every retrieval path for every question by default. Give it a router and each question runs only the paths it needs.

from graphrag_sdk import (ConnectionConfig, FalkorDBConnection, GraphRAG, GraphStore,
                          HeuristicPathRouter, MultiPathRetrieval, VectorStore)

conn = FalkorDBConnection(ConnectionConfig(host="localhost", graph_name="kb"))
strategy = MultiPathRetrieval(
    graph_store=GraphStore(conn),
    vector_store=VectorStore(conn, embedder=embedder, embedding_dimension=256),
    embedder=embedder, llm=llm,
    router=HeuristicPathRouter(),          # or LLMPathRouter(llm)
)
rag = GraphRAG(conn, llm=llm, embedder=embedder, retrieval_strategy=strategy)
# rag.completion() runs only the paths each question needs

HeuristicPathRouter

No model call. Always runs relates and chunks. It adds expansion and entity_cypher for relationship questions ("how are X and Y connected"), and the entity paths when a question quotes a phrase or names something.

LLMPathRouter

One short LLM call returns the path ids to run. Any object with an async plan(query, ctx) works as a router.

✓

A failed route runs everything. An empty plan, or a router that fails, runs every path, so a router failure never costs recall.

10

Agentic GraphRAG, built to be trusted

Giving a model access to your knowledge only works if every edge case lands somewhere safe. Here is where each one lands:

If…Then
an agent wants to write through a read toolThere's no way to: the toolkit's own queries run as GRAPH.RO_QUERY, and retrieve's searches only read
the agent cites [n] it never gotIt's listed as invalid and removed from the answer
the graph doesn't existThe tools say so by name, and nothing is created
two MCP clients share a serverEach gets its own evidence numbering
a document tries to steer the planIt can only reach options you allowed, with clamped values
the planner or router failsThe defaults run, or every path does
you don't pass auto=, a planner or a routerIngestion uses the default chunker, extractor and resolver, and rag.​completion() runs every retrieval path
Agentic where it helps, deterministic where it must be, and every answer traceable to the graph.
11

Frequently asked questions

Which agents can use these tools?

Any MCP client, such as Claude Code or Cursor, through graphrag-mcp and a single config entry. In Python, tool_specs() gives each tool's name, description and JSON Schema, which is exactly what frameworks like LangGraph and pydantic-ai register.

Can an agent change or delete my data?

Not through the read tools: the toolkit's own queries run as GRAPH.RO_QUERY, so FalkorDB itself refuses writes, and retrieve's searches only read. Start the server with --read-only (or pass read_only=True) and the write tools aren't offered at all. When you do serve them, they carry MCP's destructive annotation, so clients that honour MCP annotations ask you first.

How do I know an answer is really grounded in the graph?

Every piece of evidence carries a number, and check_​citations verifies each [n] in the draft: that a tool really returned it in this session, and that the figures and names it backs appear in that evidence. The check is literal and makes no LLM call, so the same draft against the same evidence always gets the same verdict.

When should I use rag.completion() instead of the tools?

rag.​completion() answers a plain question about your content in one call, and with a path router it runs only the retrieval paths each question needs. The tools shine when a question takes several steps: multi-hop chains, comparisons, “which X are connected to Y”.

Can the agent build the knowledge graph too?

Yes. Give the toolkit a files_root and the agent previews the files, declares an ontology, ingests with a plan per file and finalizes. Each result tells it what the ontology still misses, so it can extend the ontology and re-extract. In your own code, rag.​ingest(auto=True) brings the same per-document planning to any pipeline.

Give your agent a graph.

Install the SDK, start a FalkorDB, and point any MCP client at graphrag-mcp. Your agent searches, cites and builds, and every answer comes with receipts.

github.com/​FalkorDB/​GraphRAG-SDK
# a FalkorDB server
docker run -p 6379:6379 -p 3000:3000 \
  falkordb/falkordb

# the SDK and its MCP server
pip install "graphrag-sdk[mcp,markdown,pdf]"

# then add graphrag-mcp to your MCP client,
# with the .mcp.json entry above
Your agent plans. FalkorDB keeps it honest.

Author

  • Naseem Ali

    Software Engineer at FalkorDB, working across AI, GraphRAG, and developer platforms. He builds graph-powered AI solutions, contributes to GraphRAG, Snowflake integrations, and MCP tooling, and develops full-stack products while driving automation, testing, and open-source initiatives with Python and TypeScript.