diff --git a/agent-framework/TOC.yml b/agent-framework/TOC.yml index fb24a7d2..323aa1e2 100644 --- a/agent-framework/TOC.yml +++ b/agent-framework/TOC.yml @@ -164,6 +164,10 @@ items: href: integrations/purview.md - name: M365 href: integrations/m365.md + - name: Neo4j GraphRAG Provider + href: integrations/neo4j-graphrag.md + - name: Neo4j Memory Provider + href: integrations/neo4j-memory.md - name: A2A Protocol href: integrations/a2a.md - name: AG-UI Protocol diff --git a/agent-framework/agents/rag.md b/agent-framework/agents/rag.md index 5850b501..7871d279 100644 --- a/agent-framework/agents/rag.md +++ b/agent-framework/agents/rag.md @@ -553,6 +553,8 @@ This pattern works with any Semantic Kernel VectorStore connector, including: Each connector provides the same `create_search_function` method that can be bridged to Agent Framework tools, allowing you to choose the vector database that best fits your needs. See [the full list here](/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors). +For knowledge graph RAG using graph traversal and Cypher queries, see the [Neo4j GraphRAG Provider](../integrations/neo4j-graphrag.md). + ::: zone-end ## Next steps diff --git a/agent-framework/integrations/index.md b/agent-framework/integrations/index.md index 5d1fb837..61d77797 100644 --- a/agent-framework/integrations/index.md +++ b/agent-framework/integrations/index.md @@ -72,6 +72,7 @@ Here is a list of existing providers that can be used. | [Mem0 Memory Provider](https://github.com/microsoft/agent-framework/blob/main/python/packages/mem0/agent_framework_mem0/_provider.py) | Preview | | [Redis Provider](https://github.com/microsoft/agent-framework/blob/main/python/packages/redis/agent_framework_redis/_provider.py) | Preview | | [Purview Context Provider](./purview.md) | Preview | +| [Neo4j Memory Provider](./neo4j-memory.md) | Preview | ::: zone-end @@ -94,6 +95,7 @@ Here is a list of existing providers that can be used. | RAG AI Context Provider | Release Status | | ------------------------------------------------------------------ | --------------- | | [Azure AI Search Provider](https://github.com/microsoft/agent-framework/blob/main/python/packages/azure-ai-search/agent_framework_azure_ai_search/_search_provider.py) | Preview | +| [Neo4j GraphRAG Provider](./neo4j-graphrag.md) | Preview | ::: zone-end diff --git a/agent-framework/integrations/neo4j-graphrag.md b/agent-framework/integrations/neo4j-graphrag.md new file mode 100644 index 00000000..2eb6cdaf --- /dev/null +++ b/agent-framework/integrations/neo4j-graphrag.md @@ -0,0 +1,117 @@ +--- +title: Neo4j GraphRAG Context Provider for Agent Framework +description: Learn how to use the Neo4j GraphRAG Context Provider to add knowledge graph retrieval capabilities to your Agent Framework agents +zone_pivot_groups: programming-languages +author: retroryan +ms.topic: article +ms.author: ryanknight +ms.date: 03/29/2026 +ms.service: agent-framework +--- + +# Neo4j GraphRAG Context Provider + +The Neo4j GraphRAG Context Provider adds Retrieval Augmented Generation (RAG) capabilities to Agent Framework agents using a Neo4j knowledge graph. It supports vector, fulltext, and hybrid search modes, with optional graph traversal to enrich results with related entities via custom Cypher queries. + +For knowledge graph scenarios where relationships between entities matter, this provider retrieves relevant subgraphs rather than isolated text chunks, giving agents richer context for generating responses. + +## Why use Neo4j for GraphRAG? + +- **Graph enhanced retrieval**: Standard vector search returns isolated chunks; graph traversal follows connections to surface related entities, giving agents richer context. +- **Flexible search modes**: Combine vector similarity, keyword/BM25, and graph traversal in a single query. +- **Custom retrieval queries**: Cypher queries let you control exactly which relationships to traverse and what context to return. + +> [!NOTE] +> Neo4j offers two separate integrations for Agent Framework. This provider (`agent-framework-neo4j`) is for **GraphRAG** — searching an existing knowledge graph to ground agent responses. For **persistent memory** that learns from conversations and builds a knowledge graph over time, see the [Neo4j Memory Provider](./neo4j-memory.md). + +::: zone pivot="programming-language-csharp" + +This provider is not yet available for C#. See the Python tab for usage examples. + +::: zone-end + +::: zone pivot="programming-language-python" + +## Prerequisites + +- A Neo4j instance (self-hosted or [Neo4j AuraDB](https://neo4j.com/cloud/aura/)) with a vector or fulltext index configured +- An Azure AI Foundry project with a deployed chat model and an embedding model (e.g. `text-embedding-ada-002`) +- Environment variables set: `NEO4J_URI`, `NEO4J_USERNAME`, `NEO4J_PASSWORD`, `AZURE_AI_PROJECT_ENDPOINT` +- Azure CLI credentials configured (`az login`) +- Python 3.10 or later + +## Installation + +```bash +pip install agent-framework-neo4j +``` + +## Usage + +```python +from agent_framework import Agent +from agent_framework.azure import AzureAIClient +from agent_framework_neo4j import Neo4jContextProvider, Neo4jSettings, AzureAISettings, AzureAIEmbedder +from azure.identity.aio import AzureCliCredential + +credential = AzureCliCredential() + +# Reads NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD from environment variables +neo4j_settings = Neo4jSettings() + +# Reads AZURE_AI_PROJECT_ENDPOINT, AZURE_AI_EMBEDDING_NAME from environment variables +azure_settings = AzureAISettings() + +embedder = AzureAIEmbedder( + endpoint=azure_settings.inference_endpoint, + credential=credential, + model=azure_settings.embedding_model, +) + +neo4j_provider = Neo4jContextProvider( + uri=neo4j_settings.uri, + username=neo4j_settings.username, + password=neo4j_settings.get_password(), + index_name=neo4j_settings.vector_index_name, + index_type="vector", + embedder=embedder, + top_k=5, + retrieval_query=""" + MATCH (node)-[:FROM_DOCUMENT]->(doc:Document) + OPTIONAL MATCH (doc)<-[:FILED]-(company:Company) + RETURN node.text AS text, score, doc.title AS title, company.name AS company + ORDER BY score DESC + """, +) + +async with ( + neo4j_provider, + AzureAIClient(credential=credential, project_endpoint=azure_settings.project_endpoint) as client, + Agent( + client=client, + instructions="You are a financial analyst assistant.", + context_providers=[neo4j_provider], + ) as agent, +): + session = agent.create_session() + response = await agent.run("What risks does Acme Corp face?", session=session) +``` + +## Key features + +- **Index-driven**: Works with any Neo4j vector or fulltext index +- **Graph traversal**: Custom Cypher queries enrich search results with related entities +- **Search modes**: Vector (semantic similarity), fulltext (keyword/BM25), or hybrid (both combined) + +## Resources + +- [Neo4j Context Provider repository](https://github.com/neo4j-labs/neo4j-maf-provider) +- [PyPI package page](https://pypi.org/project/agent-framework-neo4j/) +- [Workshop: Neo4j Context Providers for Agent Framework](https://github.com/neo4j-partners/maf-context-providers-lab) + +::: zone-end + +## Next steps + +> [!div class="nextstepaction"] +> [Neo4j Memory Provider](./neo4j-memory.md) diff --git a/agent-framework/integrations/neo4j-memory.md b/agent-framework/integrations/neo4j-memory.md new file mode 100644 index 00000000..6281c527 --- /dev/null +++ b/agent-framework/integrations/neo4j-memory.md @@ -0,0 +1,127 @@ +--- +title: Neo4j Memory Provider for Agent Framework +description: Learn how to use the Neo4j Memory Provider to add persistent knowledge graph memory to your Agent Framework agents +zone_pivot_groups: programming-languages +author: retroryan +ms.topic: article +ms.author: ryanknight +ms.date: 03/29/2026 +ms.service: agent-framework +--- + +# Neo4j Memory Provider + +The Neo4j Memory Provider gives Agent Framework agents persistent memory backed by a knowledge graph. Unlike RAG providers that retrieve from static knowledge bases, the memory provider stores and recalls agent interactions, automatically extracting entities and building a knowledge graph over time. + +The provider manages three types of memory: + +- **Short-term memory**: Conversation history and recent context +- **Long-term memory**: Entities, preferences, and facts extracted from interactions +- **Reasoning memory**: Past reasoning traces and tool usage patterns + +## Why use Neo4j for agent memory? + +- **Knowledge graph persistence**: Memories are stored as connected entities, not flat records, so the agent can reason about relationships between things it remembers. +- **Automatic entity extraction**: Conversations are parsed into structured entities and relationships without manual schema design. +- **Cross-session recall**: Preferences, facts, and reasoning traces persist across sessions and surface automatically via context providers. + +> [!NOTE] +> Neo4j offers two separate integrations for Agent Framework. This provider (`neo4j-agent-memory`) is for **persistent memory** — storing and recalling agent interactions, extracting entities, and building a knowledge graph over time. For **GraphRAG** from an existing knowledge graph using vector, fulltext, or hybrid search, see the [Neo4j GraphRAG Context Provider](./neo4j-graphrag.md). + +::: zone pivot="programming-language-csharp" + +This provider is not yet available for C#. See the Python tab for usage examples. + +::: zone-end + +::: zone pivot="programming-language-python" + +## Prerequisites + +- A Neo4j instance (self-hosted or [Neo4j AuraDB](https://neo4j.com/cloud/aura/)) +- An Azure AI Foundry project with a deployed chat model +- An OpenAI API key or Azure OpenAI deployment (for embeddings and entity extraction) +- Environment variables set: `NEO4J_URI`, `NEO4J_PASSWORD`, `AZURE_AI_PROJECT_ENDPOINT` +- Azure CLI credentials configured (`az login`) +- Python 3.10 or later + +## Installation + +```bash +pip install neo4j-agent-memory[microsoft-agent] +``` + +## Usage + +```python +import os +from pydantic import SecretStr +from agent_framework import Agent +from agent_framework.azure import AzureAIClient +from azure.identity.aio import AzureCliCredential +from neo4j_agent_memory import MemoryClient, MemorySettings +from neo4j_agent_memory.integrations.microsoft_agent import ( + Neo4jMicrosoftMemory, + create_memory_tools, +) + +# MemorySettings accepts nested configuration for Neo4j, embedding, and LLM providers. +# Environment variables use the NAM_ prefix with __ as nested delimiter +# (e.g. NAM_NEO4J__URI, NAM_NEO4J__PASSWORD, NAM_EMBEDDING__MODEL). +settings = MemorySettings( + neo4j={ + "uri": os.environ["NEO4J_URI"], + "username": os.environ.get("NEO4J_USERNAME", "neo4j"), + "password": SecretStr(os.environ["NEO4J_PASSWORD"]), + }, + embedding={ + "provider": "openai", + "model": "text-embedding-3-small", + }, +) + +memory_client = MemoryClient(settings) + +async with memory_client: + memory = Neo4jMicrosoftMemory.from_memory_client( + memory_client=memory_client, + session_id="user-123", + ) + tools = create_memory_tools(memory) + + async with ( + AzureAIClient( + credential=AzureCliCredential(), + project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"], + ) as client, + Agent( + client=client, + instructions="You are a helpful assistant with persistent memory.", + tools=tools, + context_providers=[memory.context_provider], + ) as agent, + ): + session = agent.create_session() + response = await agent.run("Remember that I prefer window seats on flights.", session=session) +``` + +## Key features + +- **Bidirectional**: Automatically retrieves relevant context before invocation and saves new memories after responses +- **Entity extraction**: Builds a knowledge graph from conversations using a multi-stage extraction pipeline +- **Preference learning**: Infers and stores user preferences across sessions +- **Memory tools**: Agents can explicitly search memory, remember preferences, and find entity connections + +## Resources + +- [Neo4j Agent Memory repository](https://github.com/neo4j-labs/agent-memory) +- [PyPI package page](https://pypi.org/project/neo4j-agent-memory/) +- [Sample: Retail Assistant with Neo4j Agent Memory](https://github.com/neo4j-labs/agent-memory/tree/main/examples/microsoft_agent_retail_assistant) +- [Workshop: Neo4j Context Providers for Agent Framework](https://github.com/neo4j-partners/maf-context-providers-lab) + +::: zone-end + +## Next steps + +> [!div class="nextstepaction"] +> [Neo4j GraphRAG Context Provider](./neo4j-graphrag.md)