agent-framework-neo4j

Neo4j Context Provider for Microsoft Agent Framework - RAG with knowledge graphs.

Quick Install

pip install agent-framework-neo4j --pre

# With Azure AI embeddings support
pip install agent-framework-neo4j[azure] --pre

Supported Platforms

• Python 3.10+
• Windows, macOS, Linux

Setup

Configure Neo4j credentials via environment variables or constructor parameters:

# Environment variables
export NEO4J_URI="neo4j+s://xxx.databases.neo4j.io"
export NEO4J_USERNAME="neo4j"
export NEO4J_PASSWORD="your-password"

Quick Start

Basic Fulltext Search

from agent_framework_neo4j import Neo4jContextProvider, Neo4jSettings

settings = Neo4jSettings()  # Loads from environment

provider = Neo4jContextProvider(
    uri=settings.uri,
    username=settings.username,
    password=settings.get_password(),
    index_name="search_chunks",
    index_type="fulltext",
)

async with provider:
    # Use with Microsoft Agent Framework agent
    pass

Vector Search with Azure AI Embeddings

from agent_framework_neo4j import Neo4jContextProvider, AzureAIEmbedder, AzureAISettings
from azure.identity.aio import AzureCliCredential

credential = AzureCliCredential()
ai_settings = AzureAISettings()  # Loads from AZURE_AI_* env vars

embedder = AzureAIEmbedder(
    endpoint=ai_settings.project_endpoint,
    model_name=ai_settings.embedding_model,
    credential=credential,
)

provider = Neo4jContextProvider(
    uri="neo4j+s://xxx.databases.neo4j.io",
    username="neo4j",
    password="your-password",
    index_name="chunkEmbeddings",
    index_type="vector",
    embedder=embedder,
    top_k=5,
)

Hybrid Search (Vector + Fulltext)

provider = Neo4jContextProvider(
    uri=settings.uri,
    username=settings.username,
    password=settings.get_password(),
    index_name="chunkEmbeddings",        # Vector index
    fulltext_index_name="search_chunks", # Fulltext index
    index_type="hybrid",
    embedder=embedder,
)

Graph-Enriched Retrieval

Use custom Cypher queries to traverse relationships after the initial index search:

provider = Neo4jContextProvider(
    uri=settings.uri,
    username=settings.username,
    password=settings.get_password(),
    index_name="chunkEmbeddings",
    index_type="vector",
    embedder=embedder,
    retrieval_query="""
        MATCH (node)-[:FROM_DOCUMENT]->(doc:Document)
        RETURN node.text AS text, score, doc.title AS title
        ORDER BY score DESC
    """,
)

Retrieval query requirements:

• Must use node and score variables from the index search
• Must return at least text and score columns
• Use ORDER BY score DESC to maintain relevance ranking

Features

• Vector Search - Semantic similarity using embeddings
• Fulltext Search - Keyword matching with Lucene
• Hybrid Search - Combined vector + fulltext for best of both
• Graph Enrichment - Custom Cypher queries for relationship traversal
• Message History - Configurable conversation context windowing
• Pydantic Settings - Environment-based configuration with validation

Configuration Parameters

Connection

Search

Environment Variables

More Examples

See the samples directory for complete working examples.

Documentation

• Microsoft Agent Framework
• Agent Framework Python Packages
• Neo4j GraphRAG Python

License

MIT