google / google/adk-samples

[RECIPE PROPOSAL] Multi-agent GraphRAG over a Neo4j knowledge graph (Python)

Open
#2,619 1 comment 0 reactions 1 assignee Assigned to @pierpaolo28 View on GitHub
contribute python
Dominant language
Python
Stars
10.3k
Forks
2.9k
Avg merge
1d 10h
Merged PRs (30d)
66

Description

### ⚠️ Scope Notice
For `contrib/` recipes only. `core/` recipes follow a different process.

1- What is the intent/purpose of your new recipe? In what way will it help the ADK community?
A multi-agent GraphRAG (graph retrieval-augmented generation) recipe: a root
orchestrator routes questions to three specialist sub-agents over a Neo4j
knowledge graph: (a) a Text-to-Cypher agent that reads the live schema,
generates read-only Cypher, and self-corrects; (b) a hand-written graph-tool
agent (company → investor lookup); and (c) an agent that calls pre-validated
queries via the MCP Toolbox.

It fills a real gap: there is no knowledge-graph / GraphRAG recipe in the repo
today, the existing retrieval recipes (rag-agent-search, rag-vector-search,
multiformat-hybrid-rag) are all vector-based. It teaches graph-grounded
retrieval (multi-hop / relationship queries with explainable results) as a
complement to vector RAG, and shows three distinct graph-retrieval strategies
in one place. It runs out-of-the-box against Neo4j's public read-only demo
database, so it needs only a Gemini API key.

2- What language is your recipe is implemented in (e.g. Python, Go, etc)?
Python (3.11+), using google-adk.

3- Will this be a deployable recipe, either by having a Dockerfile, or by utilizing Vertex AI?
Not deployable as-is (no Dockerfile). It runs locally via `adk web` / `adk run`.
It supports Vertex AI as an auth option (GOOGLE_GENAI_USE_VERTEXAI=1) in
addition to the Google AI Studio API key. Happy to add a Dockerfile if the
team would like it to be deployable.

4- What GCP services or third-party APIs (Salesforce, Jira, etc.) are required?
- Gemini via Google AI Studio API key, or Vertex AI.
- Neo4j, defaults to the public, read-only "companies" demo database
(neo4j+s://demo.neo4jlabs.com), so no provisioning is needed to try it.
- Optional: MCP Toolbox (genai-toolbox) for the pre-validated-query agent;
the recipe falls back gracefully to schema + Cypher tools when it isn't run.

5- Who (individual/team) will own and maintain this?
JOFLOX (individual contributor), listed as ownership.poc in the recipe manifest.

6- Please include any additional information you'd like to share.
Already implemented and CI-clean in PR #2616 (validate, ruff, check_env_vars,
check_recipe_pyproject, and pytest all pass locally; every automated-review
finding across the rounds has been addressed). Adapted from the Apache-2.0
"Building GraphRAG Agents with ADK and Neo4j" codelab, with attribution in the
recipe README. Opening this proposal per @happyhuman 's request so the team can
approve the recipe before PR review.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.