Heidelberg AICurriculum

GraphRAG in Python: Agentic AI with Knowledge Graphs

NeuralNine ·2026-07-17 ·2 min read

Summary written by us from the video's transcript. The video, and everything in it, is NeuralNine's work.

Learn how to set up and use GraphRAG with Neo4j in Python, from installing a graph database to querying multi‑hop relationships via an LLM‑driven agent.

Takeaways

  • GraphRAG is ideal for relationship‑heavy data and queries requiring multi‑hop reasoning.
  • A minimal Neo4j graph can be built with a few `MERGE` Cypher statements and queried via an LLM‑driven Text‑to‑Cypher retriever.
  • Wrap the retriever as a LangChain tool so the agent can automatically decide when to query the knowledge graph.
  • Use Docker Compose for quick local Neo4j setup; map ports 7474 (HTTP) and 7687 (Bolt) and set `NEO4J_AUTH`.
  • Streaming the agent’s execution reveals each intermediate Cypher query and reasoning step.

What is GraphRAG and When to Use It

GraphRAG combines retrieval‑augmented generation (RAG) with a knowledge graph so an agent can traverse entities and relationships instead of just fetching text chunks. Use it when you have many interconnected entities, need multi‑hop reasoning, or require explainable audit trails. Classic vector RAG is better for simple similarity search, small datasets, or rapidly changing data.

Setting Up the Neo4j Environment

Install Neo4j locally (Desktop, package manager, Docker) – the tutorial uses Docker Compose. Create a `docker-compose.yaml` defining a Neo4j service with image version 5, mapping ports 7474 (HTTP UI) and 7687 (Bolt), and set `NEO4J_AUTH=neo4j/password123`. Run `docker-compose up` to start the database on localhost.

Add an OpenAI API key in a `.env` file (`OPENAI_API_KEY=<your_key>`) and load it with `python-dotenv`.

Installing Required Python Packages

The example uses the optional `uv` manager, but any installer works. Install: `langchain[openai]`, `neo4j`, `neo4j-graph-rag`, and `python-dotenv`. These provide the LLM agent, Neo4j driver, GraphRAG utilities, and environment variable loading.

Creating a Minimal Knowledge Graph

Connect to Neo4j via Bolt: `driver = GraphDatabase.driver('bolt://localhost:7687', auth=('neo4j','password123'))`. Use Cypher `MERGE` statements to add nodes and relationships, e.g.:

``` MERGE (f:Person {name:'Florian Dedoff', country:'Austria'}) MERGE (c:YTChannel {name:'NeuralNine'}) MERGE (os:OS {name:'Linux'}) MERGE (l:Person {name:'Linus Torvalds', country:'Finland'}) MERGE (f)-[:OWNS]->(c) MERGE (f)-[:USES]->(os) MERGE (l)-[:CREATED]->(os) ```

This builds a graph linking a person, their channel, the OS they use, and its creator.

Configuring the Text‑to‑Cypher Retriever

Define a schema string that describes node labels and relationships, e.g.:

``` Person(name, country) YTChannel(name) OS(name) Person OWNS YTChannel Person USES OS Person CREATED OS ```

Create a `TextToCypherRetriever` with the Neo4j driver, an OpenAI LLM (e.g., `gpt-4-mini`), and the schema. The retriever turns natural‑language questions into Cypher queries.

Building the LangChain Agent with a Graph Query Tool

Use `@tool` to wrap a function `query_kg(question: str) -> str` that calls `retriever.search(question)` and returns concatenated results. Create an agent via `create_agent(model='gpt-4o-mini', tools=[query_kg], system_prompt='You are a helpful assistant with access to a knowledge graph.')`. The agent can invoke the tool whenever it needs graph data.

Running a Multi‑Hop Query

In `if __name__ == '__main__':` send a complex question such as: "What country is the creator of the operating system used by the person who runs NeuralNine from?" The agent calls the retriever, which generates Cypher, fetches nodes, and returns the answer – in this case, "Finland." Streaming mode can be enabled to see each reasoning step (who runs NeuralNine → which OS they use → who created it → that creator's country).