Microsoft Agent Framework + Neo4j 集成

Microsoft Agent Framework 是微软推出的开源 SDK，用于在 .NET 和 Python 中构建 AI Agent。Agent 可以通过标准接口调用外部工具，无论是本地函数、REST API 还是 MCP 服务器。它们可以形成工作流，通过多个专业 Agent 协作完成复杂任务。该框架支持本地开发，并可与 Microsoft Foundry 集成，实现生产环境部署、追踪和指标监控。

其架构在数据访问方面保持了灵活性。自定义工具可以直接查询数据库；MCP 服务器通过标准协议公开数据能力；上下文提供程序（Context providers）会在每次 LLM 调用前自动注入信息。你可以根据自己的限制条件选择最适合的模式。

Neo4j 集成模式

将 Microsoft Agent Framework 的 Agent 连接到 Neo4j 有四种模式。每种模式都反映了关于数据库逻辑存放位置以及 Agent 直接控制程度的不同理念。

Neo4j and Microsoft Agent Framework Integration Patterns

直接 SDK 集成

使用官方 Neo4j 驱动程序编写自定义工具。Agent 调用你的函数，你的代码执行 Cypher，你可以精确控制返回的内容。

这种模式让你对 LLM 看到的内容拥有最大程度的控制权。你可以在数据消耗 token 之前过滤结果、重塑数据、通过自定义逻辑处理错误并汇总大量结果集。其代价是维护成本：你的集成代码与 Neo4j 驱动程序版本以及 Agent 的工具接口紧密耦合。

演示：GraphRAG 合同审查 Agent

Microsoft MVP Christian Glessner 基于此模式构建了一个合同分析系统。合同、组织、条款和管辖区作为知识图谱中的节点存在。该 Agent 结合了结构化的 Cypher 查询与向量搜索，以回答跨文档集的合规性问题。

用户询问：“哪些合同引用了 GDPR 且涉及德国的供应商？”Agent 的自定义工具执行一个 Cypher 查询，匹配链接到包含 GDPR 引用的“条款”节点的“合同”节点，然后遍历到按管辖区过滤的“组织”节点。该工具在 LLM 生成答案之前将结果格式化为结构化响应。提示词中无需进行原始 JSON 解析。

来源： GraphRAG 合同 Agent

MCP 服务器集成

将 Neo4j MCP 服务器作为独立进程运行。Agent 像连接任何其他 MCP 工具提供程序一样连接到它。服务器通过标准协议公开诸如 read_cypher 和 get_schema 之类的功能。

这种模式将数据访问与 Agent 逻辑分离开来。无论你的 Agent 是在开发阶段本地运行，还是在 Azure 上进行生产部署，同样的 MCP 服务器配置均可工作。更换 LLM 或更改 Agent 框架时，数据层保持不变。其代价是运营成本：你需要与 Agent 一起运行并维护 MCP 服务器。

演示：图数据库侦探

Microsoft AI MVP Jose Luis Latorre 构建了一个通过 MCP 连接到 Neo4j Aura 的调查 Agent。该图谱包含了 POLE 数据集：来自犯罪调查的人员、物体、地点和事件。

该 Agent 采用“黄金时代侦探”的人设。当用户询问嫌疑人与犯罪现场之间的联系时，Agent 会调用 MCP 服务器的 Cypher 工具来遍历图谱。MCP 服务器执行查询并返回结果，随后 Agent 以角色口吻叙述调查结果，将图谱遍历过程转化为侦探独白。这种人设选择是有意为之，它展示了在使用 MCP 时，Agent 的个性和数据访问是如何保持清晰分离的。

来源： 图数据库侦探

HTTP 查询 API

将 Neo4j 视为一个 REST 端点。在 POST 请求正文中发送 Cypher 语句，并接收 JSON 响应。无需安装驱动程序。

这种模式适用于无法安装二进制依赖的受限环境，例如无服务器函数（Serverless）、受限容器或基于浏览器的 Agent。其延迟高于 Bolt 协议，且 JSON 响应可能较为冗长，但在轻量级用例中，这种简单性极具优势。

演示：主权 AI 知识库

Matthias Buchhorn Roth (Sopra Steria) 为受监管环境构建了一个 RAG 解决方案。该图谱包含法规、法律文件和操作规程。系统同时在云端和物理隔离（Air-gapped）部署中运行。

在物理隔离场景下，安装和维护驱动程序依赖项是个后勤难题。向本地 Neo4j 实例发送 HTTP 请求完全避开了这个问题。Agent 通过 REST 查询法规图谱，将结果与基于 BitNet 的本地推理相结合，并生成包含引用的答案。审计人员可以追踪每一条回复，直至图谱中特定的法规节点。

上下文提供程序集成

上下文提供程序（Context providers）在每次 LLM 调用之前向对话中注入信息。Agent 无需显式请求数据——提供程序会自动搜索 Neo4j，通过图谱遍历丰富结果，并将上下文合并到提示词中。

Neo4j 上下文提供程序基于 neo4j-graphrag-python 库构建，该库提供了用于语义相似度搜索的 VectorRetriever、用于向量与全文混合搜索的 HybridRetriever，以及先进行向量搜索再进行图谱遍历的 VectorCypherRetriever。上下文提供程序封装了这些检索器，并将它们挂载到 Microsoft Agent Framework 的生命周期中。

配置非常简单。你只需指定索引名称、选择搜索类型，并根据需要提供用于图谱扩充的 Cypher 检索查询。

from neo4j_context_provider import Neo4jContextProvider

provider = Neo4jContextProvider(
    uri="neo4j+s://your-instance.databases.neo4j.io",
    username="neo4j",
    password="your-password",
    index_name="maintenance_events",
    index_type="fulltext",  # or "vector"
    top_k=5,
    retrieval_query="""
        MATCH (node)<-[:HAS_EVENT]-(comp:Component)
              <-[:HAS_COMPONENT]-(sys:System)
              <-[:HAS_SYSTEM]-(aircraft:Aircraft)
        RETURN node.fault AS fault,
               node.corrective_action AS corrective_action,
               aircraft.model AS aircraft_model,
               sys.name AS system_name
    """
)

index_type 参数决定了提供程序内部使用的检索器。将其设置为 "fulltext" 可进行基于关键词的 BM25 匹配，或设置为 "vector" 进行语义相似度搜索。retrieval_query 在初始搜索后运行，从匹配的节点出发遍历图谱，以提取相关上下文。

上下文提供程序架构详细信息

演示：飞机维护与飞行操作

Neo4j 上下文提供程序演示将维护事件和航班延误建模为知识图谱。当用户询问特定机型的复发性故障时，提供程序的 invoking() 方法会在 LLM 处理消息之前触发。

提供程序使用用户的问题对维护索引进行全文搜索。结果以维护事件节点的形式返回。随后，配置的检索查询从这些事件出发，通过组件和系统关系遍历到飞机节点，提取故障代码、纠正措施和受影响的系统。这些丰富的上下文会自动合并到提示词中。

航班延误 Agent 的工作原理类似。关于延误模式的问题会触发对航班数据的搜索，图谱遍历会从延误节点扩展到航班、机场和航线。LLM 在 Agent 无需进行任何显式工具调用的情况下，就能接收到关联的数据视图。

来源： Neo4j 上下文提供程序及飞行演示

选择你的集成模式

如果你希望快速构建具备图谱感知能力的 Agent，请从上下文提供程序开始。配置一个索引，指向你的 Neo4j 实例，框架会处理其余工作。当你需要超出初始搜索结果的图谱遍历能力时，再添加检索查询。

当你需要精确控制 LLM 看到的内容时，请转向直接 SDK 集成。复杂的业务逻辑、token 预算限制或自定义结果格式化都适用此模式。该工具可以在图谱结果到达提示词之前进行过滤、汇总和结构化处理。

当你希望在多个 Agent 或框架之间复用同一个数据层时，MCP 是合理的选择。如果你预计会更换 LLM 或在不同环境中运行 Agent，MCP 提供的解耦优势会显现出来。注意保持工具数量合理，以避免臃肿的系统提示词。

HTTP API 适用于无法安装驱动程序的受限环境——如无服务器函数、沙箱容器或基于浏览器的 Agent。

每种模式都假设你已经拥有值得查询的图谱。Agent 集成是“最后一公里”。在此之前，需要完成数据建模、关系设计和索引配置。

资源

作者

开源集成

社区演示

文档

视频与教程

NODES 2025 — Christian Glessner：图原生 Agent 实战编码：Neo4j AuraDB + Microsoft Agent Framework

© . This site is unofficial and not affiliated with Neo4j, Inc.