Neo4j

Neo4j supporta due modelli di provider di contesto di Agent Framework distinti. Condividono un database a grafo, ma usano pacchetti e flussi di dati separati.

Pattern	Behavior
GraphRAG	Cerca un grafo delle conoscenze indicizzato esistente con vettore, full-text o recupero ibrido e può attraversare le entità correlate con cypher.
Memoria persistente	Estrae entità, fatti, preferenze e ragionamenti dalle conversazioni e crea un grafico delle conoscenze che può essere richiamato tra le sessioni.

GraphRAG da un grafo delle conoscenze esistente

Il provider di contesto Neo4j GraphRAG aggiunge funzionalità di generazione aumentata di recupero (RAG) agli agenti di Agent Framework usando un grafico delle conoscenze Neo4j. Supporta le modalità di ricerca vettoriale, fulltext e ibrida, con attraversamento grafico facoltativo per arricchire i risultati con entità correlate tramite query di crittografia personalizzate.

Per altri servizi di recupero gestiti, vedere Azure AI Search e Microsoft Foundry.

Per gli scenari del grafico delle conoscenze in cui le relazioni tra le entità sono importanti, questo provider recupera sottogrammi pertinenti anziché blocchi di testo isolati, fornendo agli agenti un contesto più completo per la generazione di risposte.

Perché usare Neo4j per GraphRAG?

• Recupero avanzato grafico: la ricerca vettoriale standard restituisce blocchi isolati; L'attraversamento grafico segue le connessioni alle entità correlate alla superficie, offrendo agli agenti un contesto più completo.
• Modalità di ricerca flessibili: combinare la somiglianza del vettore, la parola chiave/BM25 e l'attraversamento grafico in una singola query.
• Query di recupero personalizzate: le query con crittografia consentono di controllare esattamente quali relazioni attraversare e quale contesto restituire.

Prerequisiti

• Istanza Neo4j (self-hosted o Neo4j AuraDB) con un indice vettoriale o full-text configurato
• Progetto Azure AI Foundry con un modello di chat distribuito e un modello di incorporamento (ad esempio text-embedding-3-small)
• Set di variabili di ambiente: NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD, AZURE_AI_SERVICES_ENDPOINT, AZURE_AI_EMBEDDING_NAME
• Credenziali di interfaccia della riga di comando di Azure configurate (az login)
• .NET 8.0 o versione successiva

Installation

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));

Funzionalità principali

• Basato su indici: funziona con qualsiasi vettore Neo4j o indice fulltext
• Attraversamento grafico: le query con crittografia personalizzata arricchiscono i risultati della ricerca con entità correlate
• Modalità di ricerca: Vector (somiglianza semantica), fulltext (parola chiave/BM25) o ibrido (entrambi combinati)

Resources

• Repository del provider di contesto Neo4j
• Pagina del pacchetto NuGet
• Workshop: Fornitori di Contesto Neo4j per il Framework degli Agenti

Prerequisiti

• Istanza Neo4j (self-hosted o Neo4j AuraDB) con un indice vettoriale o full-text configurato
• Progetto Azure AI Foundry con un modello di chat distribuito e un modello di incorporamento (ad esempio text-embedding-ada-002)
• Set di variabili di ambiente: NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORDFOUNDRY_PROJECT_ENDPOINT, , FOUNDRY_MODELAZURE_AI_EMBEDDING_NAME
• Credenziali di interfaccia della riga di comando di Azure configurate (az login)
• Python 3.10 o versione successiva

Installation

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)

Funzionalità principali

• Basato su indici: funziona con qualsiasi vettore Neo4j o indice fulltext
• Attraversamento grafico: le query con crittografia personalizzata arricchiscono i risultati della ricerca con entità correlate
• Modalità di ricerca: Vector (somiglianza semantica), fulltext (parola chiave/BM25) o ibrido (entrambi combinati)

Resources

• Repository del provider di contesto Neo4j
• Pagina del pacchetto PyPI
• Workshop: Fornitori di Contesto Neo4j per il Framework degli Agenti

Annotazioni

Il supporto per questa funzionalità sarà presto disponibile. Vedere il repository di Agent Framework Go per lo stato più aggiornato.

Memoria agente persistente

Le integrazioni di memoria Neo4j archiviano e richiamano le interazioni degli agenti, estraendo automaticamente le entità e creando un grafico delle conoscenze nel tempo.

I provider gestiscono:

• Memoria a breve termine: cronologia delle conversazioni e contesto recente.
• Memoria a lungo termine: entità, preferenze e fatti estratti dalle interazioni.
• Memoria di ragionamento: passato ragionamento di tracce e modelli di utilizzo degli strumenti.

Perché usare Neo4j per la memoria dell'agente?

• Persistenza del grafico delle conoscenze: le memorie vengono archiviate come entità connesse, non come record flat, in modo che l'agente possa ragionare sulle relazioni tra le informazioni memorizzate.
• Estrazione automatica di entità: le conversazioni vengono analizzate in entità strutturate e relazioni senza uno schema definito manualmente.
• Richiamo tra sessioni: preferenze, fatti e tracce di ragionamento persistono tra sessioni e superfici tramite provider di contesto.

Annotazioni

Il pacchetto .NET (AgentMemory) è una porta indipendente gestita dalla community .NET del provider di memoria Neo4j Labs. Non è un pacchetto ufficiale di Neo4j Labs. Vedere il repository AgentMemory (.NET) per il codice sorgente e i dettagli.

Prerequisiti

• Istanza neo4j (self-hosted o Neo4j AuraDB).
• Una distribuzione openAI Azure o Microsoft Foundry con un modello di chat e un modello di incorporamento.
• Set di variabili di ambiente: NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD, AZURE_OPENAI_ENDPOINT.
• interfaccia della riga di comando di Azure credenziali configurate (az login) o una chiave API.
• .NET 8.0 o versione successiva.

Installation

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);

Funzionalità principali

• Bidirezionale: Neo4jMemoryContextProvider richiama la memoria pertinente prima di ogni esecuzione e mantiene la nuova memoria dopo di essa.
• Estrazione di entità: la pipeline di estrazione configurabile compila un grafico delle conoscenze dalle conversazioni.
• Apprendimento delle preferenze: le preferenze, i fatti e le entità possono essere richiamate da un nuovo AgentSession utente per lo stesso utente.
• Strumenti di memoria: MemoryToolFactory espone le istanze per operazioni esplicite AIFunction di ricerca, memorizzazione e richiamo.
• Inserimento delle dipendenze per primo: AddNeo4jAgentMemory e AddAgentMemoryFramework integrazione con l'host generico e le applicazioni ASP.NET Core.
• Beyond Agent Framework: la stessa libreria si integra anche con i client Kernel semantico e MCP e include l'osservabilità di OpenTelemetry.

Resources

• Repository di AgentMemory (.NET)
• Pagina del pacchetto NuGet
• Esempio: Assistente vendita al dettaglio con AgentMemory

Prerequisiti

• Istanza neo4j (self-hosted o Neo4j AuraDB).
• Un progetto Microsoft Foundry con un modello di chat distribuito.
• Chiave API OpenAI o Azure distribuzione OpenAI per incorporamenti ed estrazione di entità.
• Set di variabili di ambiente: NEO4J_URI, NEO4J_PASSWORD, FOUNDRY_MODELFOUNDRY_PROJECT_ENDPOINT, , OPENAI_API_KEY.
• interfaccia della riga di comando di Azure credenziali configurate (az login).
• Python 3.10 o versione successiva.

Installation

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)

Funzionalità principali

• Bidirezionale: recupera il contesto pertinente prima della chiamata e salva nuovi ricordi dopo le risposte.
• Estrazione di entità: crea un grafico delle informazioni dalle conversazioni con una pipeline di estrazione a più fasi.
• Apprendimento delle preferenze: deduce e archivia le preferenze utente tra le sessioni.
• Strumenti di memoria: consente agli agenti di cercare in modo esplicito la memoria, ricordare le preferenze e trovare le connessioni alle entità.

Resources

• Repository di memoria dell'agente Neo4j
• Pagina del pacchetto PyPI
• Esempio: Assistente alle vendite al dettaglio con memoria di agente Neo4j
• Workshop: Fornitori di Contesto Neo4j per il Framework degli Agenti

Annotazioni

Le integrazioni neo4j GraphRAG e memoria non sono attualmente documentate per Agent Framework Go. Vedere il repository di Agent Framework Go per lo stato più aggiornato.

Passaggi successivi

Esplorare le integrazioni del provider di contesto