Neo4j

Neo4j obsługuje dwa odrębne wzorce dostawcy kontekstu platformy Agent Framework. Współużytkują one grafową bazę danych, ale używają oddzielnych pakietów i przepływów danych.

Pattern	Behavior
GraphRAG	Wyszukuje istniejący indeksowany graf wiedzy z wektorem, pełnym tekstem lub pobieraniem hybrydowym i może przechodzić przez powiązane jednostki za pomocą Programu Cyprher.
Pamięć trwała	Wyodrębnia jednostki, fakty, preferencje i rozumowanie z konwersacji oraz tworzy wykres wiedzy, który można odwołać między sesjami.

GraphRAG z istniejącego grafu wiedzy

Dostawca kontekstu Neo4j GraphRAG dodaje możliwości rozszerzonego pobierania (RAG) do agentów Agent Framework przy użyciu grafu wiedzy Neo4j. Obsługuje tryby wyszukiwania wektorowego, pełnotekstowego i hybrydowego, z opcjonalnym przechodzeniem grafu w celu wzbogacania wyników o powiązane jednostki za pośrednictwem niestandardowych zapytań Cyprher.

W przypadku innych zarządzanych usług pobierania zobacz Wyszukiwanie AI platformy Azure i Microsoft Foundry.

W przypadku scenariuszy grafu wiedzy, w których relacje między jednostkami mają znaczenie, ten dostawca pobiera odpowiednie podgrafy, a nie izolowane fragmenty tekstu, zapewniając agentom bogatszy kontekst generowania odpowiedzi.

Dlaczego warto używać neo4j dla programu GraphRAG?

• Rozszerzone pobieranie grafu: wyszukiwanie wektorów standardowych zwraca izolowane fragmenty; Przechodzenie grafu następuje po połączeniach z jednostkami powiązanymi z powierzchnią, dając agentom bogatszy kontekst.
• Elastyczne tryby wyszukiwania: Połącz podobieństwo wektorowe, słowa kluczowe/BM25 oraz przeszukiwanie grafu w jednym zapytaniu.
• Niestandardowe zapytania pobierania: Zapytania Cypher umożliwiają dokładną kontrolę tego, które relacje mają być przechodzone i jaki kontekst ma być zwracany.

Wymagania wstępne

• Instancja Neo4j (self-hosted lub Neo4j AuraDB) ze skonfigurowanym indeksem wektorowym lub pełnotekstowym
• Projekt rozwiązania Azure AI Foundry z wdrożonym modelem czatu i modelem osadzania (np. text-embedding-3-small)
• Zestaw zmiennych środowiskowych: NEO4J_URI, , NEO4J_USERNAMENEO4J_PASSWORD, , AZURE_AI_SERVICES_ENDPOINTAZURE_AI_EMBEDDING_NAME
• Skonfigurowane poświadczenia Azure CLI (az login)
• .NET 8.0 lub nowszy

Instalacja

dotnet add package Neo4j.AgentFramework.GraphRAG

Usage

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.OpenAI;
using Microsoft.Extensions.AI;
using Neo4j.AgentFramework.GraphRAG;
using Neo4j.Driver;

// Read connection details from environment variables
var neo4jSettings = new Neo4jSettings();
var azureEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_SERVICES_ENDPOINT")!;

// Create embedding generator
var credential = new DefaultAzureCredential();
var azureClient = new AzureOpenAIClient(new Uri(azureEndpoint), credential);

IEmbeddingGenerator<string, Embedding<float>> embedder = azureClient
    .GetEmbeddingClient("text-embedding-3-small")
    .AsIEmbeddingGenerator();

// Create Neo4j driver
await using var driver = GraphDatabase.Driver(
    neo4jSettings.Uri, AuthTokens.Basic(neo4jSettings.Username, neo4jSettings.Password!));

// Create the Neo4j context provider
await using var provider = new Neo4jContextProvider(driver, new Neo4jContextProviderOptions
{
    IndexName = "chunkEmbeddings",
    IndexType = IndexType.Vector,
    EmbeddingGenerator = embedder,
    TopK = 5,
    RetrievalQuery = """
        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
        """,
});

// Create an agent with the provider
AIAgent agent = azureClient
    .GetChatClient("gpt-4o")
    .AsIChatClient()
    .AsBuilder()
    .UseAIContextProviders(provider)
    .BuildAIAgent(new ChatClientAgentOptions
    {
        ChatOptions = new ChatOptions
        {
            Instructions = "You are a financial analyst assistant.",
        },
    });

var session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("What risks does Acme Corp face?", session));

Kluczowe funkcje

• Oparte na indeksie: działa z dowolnym wektorem Neo4j lub indeksem pełnotekstowym
• Przechodzenie grafu: niestandardowe zapytania Cypher wzbogacają wyniki wyszukiwania o powiązane obiekty
• Tryby wyszukiwania: wektor (podobieństwo semantyczne), pełnotekst (słowo kluczowe/BM25) lub hybryda (oba połączone)

Resources

• Repozytorium dostawcy kontekstu Neo4j
• Strona pakietu NuGet
• Warsztaty: Dostawcy kontekstu Neo4j dla struktury agentów

Wymagania wstępne

• Instancja Neo4j (self-hosted lub Neo4j AuraDB) ze skonfigurowanym indeksem wektorowym lub pełnotekstowym
• Projekt rozwiązania Azure AI Foundry z wdrożonym modelem czatu i modelem osadzania (np. text-embedding-ada-002)
• Zestaw zmiennych środowiskowych: NEO4J_URI, , NEO4J_USERNAMENEO4J_PASSWORDFOUNDRY_PROJECT_ENDPOINT, , , FOUNDRY_MODELAZURE_AI_EMBEDDING_NAME
• Skonfigurowane poświadczenia Azure CLI (az login)
• Python 3.10 lub nowszy

Instalacja

pip install agent-framework-neo4j

Usage

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_neo4j import Neo4jContextProvider, Neo4jSettings, AzureAISettings, AzureAIEmbedder
from azure.identity import DefaultAzureCredential
from azure.identity.aio import AzureCliCredential

# Reads NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD from environment variables
neo4j_settings = Neo4jSettings()

# Reads FOUNDRY_PROJECT_ENDPOINT, AZURE_AI_EMBEDDING_NAME from environment variables
azure_settings = AzureAISettings()

sync_credential = DefaultAzureCredential()
embedder = AzureAIEmbedder(
    endpoint=azure_settings.inference_endpoint,
    credential=sync_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,
    AzureCliCredential() as credential,
    Agent(
        client=FoundryChatClient(
            credential=credential,
            project_endpoint=azure_settings.project_endpoint,
            model=os.environ["FOUNDRY_MODEL"],
        ),
        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)

Kluczowe funkcje

• Oparte na indeksie: działa z dowolnym wektorem Neo4j lub indeksem pełnotekstowym
• Przechodzenie grafu: niestandardowe zapytania Cypher wzbogacają wyniki wyszukiwania o powiązane obiekty
• Tryby wyszukiwania: wektor (podobieństwo semantyczne), pełnotekst (słowo kluczowe/BM25) lub hybryda (oba połączone)

Resources

• Repozytorium dostawcy kontekstu Neo4j
• Strona pakietu PyPI
• Warsztaty: Dostawcy kontekstu Neo4j dla struktury agentów

Note

Obsługa tej funkcji w języku Go będzie dostępna wkrótce. Aktualny status znajdziesz w repozytorium Agent Framework dla Go.

Pamięć agenta trwałego

Integracje pamięci Neo4j przechowują i odwołują interakcje agentów, automatycznie wyodrębniając jednostki i tworząc wykres wiedzy w czasie.

Dostawcy zarządzają:

• Pamięć krótkoterminowa: historia konwersacji i ostatni kontekst.
• Pamięć długoterminowa: Jednostki, preferencje i fakty wyodrębnione z interakcji.
• Pamięć rozumowania: poprzednie ślady rozumowania i wzorce użycia narzędzi.

Dlaczego warto używać neo4j do pamięci agenta?

• Trwałość grafu wiedzy: pamięci są przechowywane jako połączone jednostki, a nie rekordy płaskie, dzięki czemu agent może wnioskować o relacjach między zapamiętanych informacjami.
• Automatyczne wyodrębnianie jednostek: konwersacje są analizowane w jednostkach strukturalnych i relacjach bez ręcznie zdefiniowanego schematu.
• Kompletność między sesjami: Preferencje, fakty i ślady rozumowania są utrwalane między sesjami i powierzchniami za pośrednictwem dostawców kontekstu.

Note

Pakiet .NET (AgentMemory) to niezależny, utrzymywany przez społeczność port .NET dostawcy pamięci Neo4j Labs. Nie jest to oficjalny pakiet Neo4j Labs. Zobacz repozytorium AgentMemory (.NET), aby uzyskać kod źródłowy i szczegółowe informacje.

Wymagania wstępne

• Wystąpienie Neo4j (self-hosted lub Neo4j AuraDB).
• Wdrożenie Azure OpenAI lub Microsoft Foundry z modelem czatu i modelem osadzania.
• Zestaw zmiennych środowiskowych: NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD, AZURE_OPENAI_ENDPOINT.
• Azure CLI skonfigurowanych poświadczeń (az login) lub klucza interfejsu API.
• .NET 8.0 lub nowszy.

Instalacja

dotnet add package AgentMemory
dotnet add package AgentMemory.AgentFramework

Usage

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using AgentMemory;
using AgentMemory.Abstractions.Services;
using AgentMemory.AgentFramework;
using AgentMemory.AgentFramework.Tools;

var builder = Host.CreateApplicationBuilder(args);

// Registers Core + Neo4j infrastructure in one call (reads NEO4J_URI / NEO4J_USERNAME /
// NEO4J_PASSWORD, falling back to local-dev defaults). Passing configureLlm opts in to
// LLM-backed entity/fact/preference extraction, using the IChatClient registered below.
builder.Services.AddNeo4jAgentMemory(
    configureMemory: _ => { },
    configureNeo4j: neo4j =>
    {
        neo4j.Uri = Environment.GetEnvironmentVariable("NEO4J_URI") ?? "bolt://localhost:7687";
        neo4j.Username = Environment.GetEnvironmentVariable("NEO4J_USERNAME") ?? "neo4j";
        neo4j.Password = Environment.GetEnvironmentVariable("NEO4J_PASSWORD") ?? "password";
    },
    configureLlm: _ => { });

// Any Microsoft.Extensions.AI-compatible chat + embedding client works
var azureClient = new AzureOpenAIClient(
    new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!), new DefaultAzureCredential());
builder.Services.AddSingleton(azureClient.GetChatClient("gpt-4o-mini").AsIChatClient());
builder.Services.AddSingleton(azureClient.GetEmbeddingClient("text-embedding-3-small").AsIEmbeddingGenerator());

// AutoExtractOnPersist builds the knowledge graph from every conversation turn
builder.Services.AddAgentMemoryFramework(options =>
{
    options.AutoExtractOnPersist = true;
    options.ContextFormat.IncludeEntities = true;
    options.ContextFormat.IncludeFacts = true;
    options.ContextFormat.IncludePreferences = true;
});

using var host = builder.Build();
await using var scope = host.Services.CreateAsyncScope();
var services = scope.ServiceProvider;

// Bootstraps Neo4j schema/indexes on first run (idempotent)
await services.GetRequiredService<ISchemaBootstrapper>().BootstrapAsync();

var memoryProvider = services.GetRequiredService<Neo4jMemoryContextProvider>();
var memoryTools = services.GetRequiredService<MemoryToolFactory>().CreateAIFunctions();

// WithMemoryOwnerScoping wraps the whole invocation — recall, the tool-calling loop, and
// persistence — in the owner scope set by WithMemoryIdentity below, so no manual
// BeginOwnerScope call is needed around RunAsync.
AIAgent agent = services.GetRequiredService<IChatClient>().AsAIAgent(new ChatClientAgentOptions
{
    ChatOptions = new ChatOptions
    {
        Instructions = "You are a helpful assistant with persistent memory.",
        Tools = [.. memoryTools],
    },
    AIContextProviders = [memoryProvider],
}).WithMemoryOwnerScoping(services);

var session = (await agent.CreateSessionAsync())
    .WithMemoryIdentity(userId: "user-123", sessionId: "session-1", applicationId: "my-app");

var response = await agent.RunAsync("Remember that I prefer window seats on flights.", session);

Kluczowe funkcje

• Dwukierunkowe: Neo4jMemoryContextProvider przypomina odpowiednią pamięć przed każdym uruchomieniem i utrwala nową pamięć po nim.
• Wyodrębnianie jednostek: konfigurowalny potok wyodrębniania tworzy wykres wiedzy z konwersacji.
• Uczenie preferencji: preferencje, fakty i jednostki mogą być przywoływane przez nowego AgentSession użytkownika.
• Narzędzia pamięci: MemoryToolFactory uwidacznia AIFunction wystąpienia dla jawnych operacji wyszukiwania, zapamiętywania i odwoływania.
• Najpierw wstrzykiwanie zależności: AddNeo4jAgentMemory i AddAgentMemoryFramework integracja z hostem ogólnym i aplikacjami ASP.NET Core.
• Poza platformą Agent Framework: ta sama biblioteka integruje się również z klientami Semantic Kernel i MCP oraz obejmuje możliwość obserwacji biblioteki OpenTelemetry.

Resources

• Repozytorium AgentMemory (.NET)
• Strona pakietu NuGet
• Przykład: Asystent sprzedaży detalicznej z AgentMemory

Wymagania wstępne

• Wystąpienie Neo4j (self-hosted lub Neo4j AuraDB).
• Projekt Microsoft Foundry z wdrożonym modelem czatu.
• Klucz interfejsu API openAI lub Azure wdrożenie openAI na potrzeby osadzania i wyodrębniania jednostek.
• Zestaw zmiennych środowiskowych: NEO4J_URI, , FOUNDRY_PROJECT_ENDPOINTNEO4J_PASSWORD, FOUNDRY_MODEL, OPENAI_API_KEY.
• Azure CLI skonfigurowanych poświadczeń (az login).
• Python 3.10 lub nowszy.

Instalacja

pip install neo4j-agent-memory[microsoft-agent]

Usage

import os
from pydantic import SecretStr
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
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,
)

# Pass Neo4j and embedding configuration directly via constructor arguments.
# MemorySettings also supports loading from environment variables or .env files
# using the NAM_ prefix (e.g. NAM_NEO4J__URI, 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 AzureCliCredential() as credential, Agent(
        client=FoundryChatClient(
            credential=credential,
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
        ),
        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)

Kluczowe funkcje

• Dwukierunkowe: pobiera odpowiedni kontekst przed wywołaniem i zapisuje nowe wspomnienia po odpowiedziach.
• Wyodrębnianie jednostek: tworzy wykres wiedzy z konwersacji przy użyciu potoku wyodrębniania wieloetapowego.
• Uczenie preferencji: wnioskowanie i przechowywanie preferencji użytkownika między sesjami.
• Narzędzia pamięci: umożliwia agentom jawne wyszukiwanie pamięci, zapamiętywanie preferencji i znajdowanie połączeń jednostek.

Resources

• Repozytorium pamięci agenta Neo4j
• Strona pakietu PyPI
• Przykład: Asystent sprzedaży detalicznej z pamięcią agenta Neo4j
• Warsztaty: Dostawcy kontekstu Neo4j dla struktury agentów

Note

Integracja neo4j GraphRAG i pamięci nie jest obecnie udokumentowana w środowisku Agent Framework Go. Aktualny status znajdziesz w repozytorium Agent Framework dla Go.

Następne kroki

Przeglądanie integracji dostawcy kontekstu