构建具备图感知能力的智能体：Neo4j 与 Microsoft Agent Framework

Microsoft Agent Framework 是微软开源的 SDK，用于使用 .NET 和 Python 构建 AI 智能体。智能体可以通过标准化的接口调用外部工具，无论是本地函数、REST API 还是 MCP 服务器。它们可以构建工作流，让多个专业智能体协作完成复杂的任务。该框架可在本地运行以供开发，随后集成到 Microsoft Foundry 中进行生产部署，并支持跟踪和指标监控。

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

Neo4j 集成模式

将 Microsoft Agent Framework 智能体连接到 Neo4j 有四种模式。每种模式反映了关于数据库逻辑存放位置以及智能体直接控制程度的不同理念。以下社区演示展示了这些模式在生产环境中的实现。

Neo4j and Microsoft Agent Framework Integration Patterns

直接 SDK 集成

架构图展示了 Microsoft Agent Framework 与 Neo4j 之间的四种集成模式。该图说明了每种模式（上下文提供程序、直接 SDK、MCP 服务器和 HTTP API）如何通过不同的层连接到 Neo4j 数据库，并展示了不同的控制和抽象级别。

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

这种模式让你能最大限度地控制 LLM 的可见内容。你可以过滤结果、重塑数据、使用自定义逻辑处理错误，并在大结果集消耗 Token 之前进行总结。其代价是维护成本：你的集成代码与 Neo4j 驱动程序版本以及智能体的工具接口紧密耦合。

演示：GraphRAG 合同审查智能体

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

用户提问：“哪些合同引用了 GDPR 并涉及德国供应商？”智能体的自定义工具会执行一条 Cypher 查询，匹配包含 GDPR 引用的“条款”节点，进而关联到“合同”节点，然后跳转至按司法管辖区过滤的“组织”节点。工具将结果格式化为结构化响应，再由 LLM 生成答案。提示词中无需进行原始 JSON 解析。

来源： GraphRAG 合同智能体

MCP 服务器集成

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

这种模式将数据访问与智能体逻辑分离。无论你的智能体是在开发期间本地运行，还是在 Azure 中生产运行，相同的 MCP 服务器配置均适用。你可以更换 LLM 或更改智能体框架，但数据层保持不变。其代价是运维成本：你需要与智能体一同运行和维护 MCP 服务器。

演示：图数据库侦探

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

该智能体采用了“霍尔姆斯沃斯·马罗”（Holmsworth Marot，一位黄金时代的侦探）的身份。当用户询问嫌疑人与犯罪现场之间的关联时，智能体调用 MCP 服务器的 Cypher 工具来遍历图谱。它可能会查询距离“嫌疑人”节点两跳范围内的所有“地点”节点，并按事件时间戳进行过滤。MCP 服务器执行查询并返回结果，随后智能体以赫尔克里·波洛（Hercule Poirot）的风格叙述发现，将图谱遍历过程转化为侦探独白。

这种角色选择是刻意的。它展示了使用 MCP 时，智能体个性和数据访问是如何保持清晰分离的。

来源： 图数据库侦探

HTTP 查询 API

将 Neo4j Aura 视为 REST 端点。在 POST 请求体中发送 Cypher，接收 JSON 响应。无需安装驱动程序。

这种模式适用于无法安装二进制依赖的受限环境，例如无服务器函数、受限容器、基于浏览器的智能体。请求是标准的 HTTP 调用，查询包含在负载中。虽然延迟比 Bolt 协议高，JSON 响应可能比较冗长，但对于轻量级用例，这种简单性极具优势。

演示：主权 AI 知识库

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

在物理隔离场景下，安装和维护驱动依赖是一项后勤难题。通过对本地 Neo4j 实例进行 HTTP 调用完全避开了这个问题。智能体通过 REST 查询法规图谱，结合基于 BitNet 的本地推理结果，生成引用详实的答案。审计员可以追溯每一条回答至图谱中的特定法规节点。

上下文提供程序集成

上下文提供程序在每次 LLM 调用前将信息注入对话。智能体无需显式请求数据。提供程序会自动搜索 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 处理消息之前触发。

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

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

来源： Neo4j 上下文提供程序及航班演示

选择你的集成模式

如果你想快速运行具备图感知能力的智能体，**请从上下文提供程序开始**。配置索引，指向你的 Neo4j 实例，其余由框架处理。当需要初始搜索结果之外的图遍历时，你可以稍后添加检索查询。当你主要目标是让智能体响应基于关联数据，且无需编写复杂的检索逻辑时，此模式非常有效。

当你需要精确控制 LLM 的可见内容时，**转向直接 SDK 集成**。复杂的业务逻辑、Token 预算限制或自定义结果格式化都指向此模式。合同分析演示展示了其价值：工具可以在图结果到达提示词之前进行过滤、总结和结构化。虽然维护代码更多，但对成本和输出质量的控制力也更强。

当你希望在多个智能体或框架之间复用同一个数据层时，**MCP 非常有意义**。侦探演示无论智能体使用 GPT-4、Claude 还是本地模型，都连接到同一个 Neo4j MCP 服务器。如果你预计会更换 LLM 或在不同环境中运行智能体，MCP 提供的数据分离特性将带来显著回报。保持工具数量合理，以避免臃肿的系统提示词。

**HTTP API** 适用于无法安装驱动程序的受限环境。例如具有严格依赖限制的无服务器函数、沙箱容器或基于浏览器的智能体。虽然延迟较高且 JSON 解析增加了开销，但简单往往是制胜关键。

每种模式都假设你已经拥有一个值得查询的图谱。智能体集成是“最后一公里”。在此之前，需要进行数据建模、关系设计和索引配置。做好这些，智能体模式自然水到渠成。如果这些没做好，无论检索有多精妙，也无法产生有用的答案。

本指南中链接的社区演示提供了现成的起点。克隆一个，填入你的 Neo4j 凭据，看看图上下文如何改变你智能体的能力。

相关链接

🧑‍💻 作者

💬 社区支持

🔗 开源集成

🕵️ 犯罪调查演示

📄 合同分析演示

✈️ 上下文提供程序演示

📚 文档

Neo4j + 智能体模式、架构说明和示例可在相关代码仓库中找到

视频与教程

NODES 2025 与 Christian Glessner

图原生智能体实战演示：Neo4j AuraDB + Microsoft Agent Framework 应用

AI 智能体擅长推理，但不擅长记忆。

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