agentic_huge_data_base / wiki
页面 Graphiti · 11.2 AI 智能体集成模式·DeepWiki 中文全文译文
DeepWiki 中文译文 / Graphiti / 11.2

11.2 · AI 智能体集成模式（AI Agent Integration Patterns）

时序知识图谱与动态事实记忆 · 本章是 Graphiti DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Graphiti 章节11.2 状态全文译文 模块界面与交互、接口与服务契约、模型调用与提供方适配、图谱与关系
项目要点页2.5 参考项目 项目章节目录Graphiti DeepWiki 原始章节AI Agent Integration Patterns 上一章11.1 下一章11.3
源码线索
  • CODE_OF_CONDUCT.md
  • Zep-CLA.md
  • examples/langgraph-agent/agent.ipynb
  • graphiti_core/driver/kuzu_driver.py
  • graphiti_core/driver/neptune_driver.py
  • mcp_server/.env.example
  • mcp_server/README.md
  • mcp_server/src/graphiti_mcp_server.py
  • mcp_server/src/models/response_types.py
  • tests/test_graphiti_mock.py
模块标签
  • 界面与交互
  • 接口与服务契约
  • 模型调用与提供方适配
  • 图谱与关系
  • 系统架构

中文译文

AI 智能体集成模式（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/getzep/graphiti/11.2-ai-agent-integration-patterns
翻译时间：2026-05-27T08:44:58.849Z
翻译模型：deepseek-chat
原文字符数：11936
项目：Graphiti (graphiti)

--- 好的，作为一名资深技术文档翻译专家，我将严格遵循您的要求，对这份 DeepWiki 技术文档进行全文翻译和润色。

---

AI 智能体集成模式

相关源文件

生成此维基页面时参考了以下文件：

  • CODE_OF_CONDUCT.md
  • Zep-CLA.md
  • examples/langgraph-agent/agent.ipynb
  • graphiti_core/driver/kuzu_driver.py
  • graphiti_core/driver/neptune_driver.py
  • mcp_server/.env.example
  • mcp_server/README.md
  • mcp_server/src/graphiti_mcp_server.py
  • mcp_server/src/models/response_types.py
  • tests/test_graphiti_mock.py

目的与范围

本文档记录了将 AI 智能体连接到 Graphiti 知识图谱的各种集成模式。它涵盖了两种主要方法：

  1. 直接库集成 — 将 graphiti-core 直接嵌入到智能体循环中（以 LangGraph ShoeBot 示例说明）。
  2. MCP 服务器集成 — 通过模型上下文协议（MCP）服务器连接 AI 智能体客户端，支持 HTTP 传输、标准输入输出（stdio）传输以及为 Cursor 和 Claude Desktop 等客户端提供的网关桥接。

有关 MCP 服务器部署的详细信息，请参见第 8.1 页。有关核心 Graphiti API 参考，请参见第 4.1 页。

集成架构总览

Graphiti 可以通过两种方式集成到智能体工作流中：作为 Python 库直接集成在智能体进程内，或者作为外部 MCP 服务器供任何兼容 MCP 的客户端连接。

集成模式示意图：

graph TB
    subgraph Pattern1DirectLibrary["模式 1：直接库集成"]
        LANGGRAPH["LangGraph StateGraph"]
        GRAPHITI_LIB["graphiti_core.Graphiti"]
        LANGGRAPH -->|"add_episode()<br/>search()"| GRAPHITI_LIB
    end

    subgraph Pattern2MCPServer["模式 2：MCP 服务器"]
        subgraph AIAgentClients["AI 智能体客户端"]
            CURSOR["Cursor IDE"]
            VSCODE["VS Code + Copilot"]
            CLAUDE["Claude Desktop"]
            CUSTOM["自定义 MCP 客户端"]
        end

        subgraph TransportLayer["传输层"]
            HTTP["HTTP 传输<br/>localhost:8000/mcp/"]
            STDIO["标准输入输出（stdio）传输"]
            GATEWAY["mcp-remote 网关"]
        end

        MCP_SERVER["mcp_server/src/graphiti_mcp_server.py<br/>FastMCP(Graphiti Agent Memory)"]

        CURSOR -->|"HTTP"| HTTP
        VSCODE -->|"HTTP"| HTTP
        CUSTOM -->|"stdio"| STDIO
        CLAUDE -->|"stdio"| GATEWAY
        GATEWAY -->|"HTTP"| HTTP
        HTTP --> MCP_SERVER
        STDIO --> MCP_SERVER
    end

    subgraph SharedBackend["共享后端"]
        GRAPHITI_CORE["graphiti_core.Graphiti"]
        DB["Neo4jDriver<br/>FalkorDriver<br/>KuzuDriver<br/>NeptuneDriver"]
        LLM["LLMClient<br/>OpenAI/Anthropic/Gemini/Azure"]
    end

    GRAPHITI_LIB --> GRAPHITI_CORE
    MCP_SERVER --> GRAPHITI_CORE
    GRAPHITI_CORE --> DB
    GRAPHITI_CORE --> LLM

来源： mcp_server/README.md:10-28, mcp_server/README.md:163-172, mcp_server/src/graphiti_mcp_server.py:147-150

模式 1：直接库集成（LangGraph ShoeBot）

examples/langgraph-agent/agent.ipynb 笔记本演示了如何将 graphiti-core 直接嵌入到 LangGraph 智能体中。该智能体是一个鞋类销售聊天机器人（“ShoeBot”），它使用 Graphiti 实现持久化记忆和产品知识。

智能体架构

LangGraph + Graphiti 数据流图：

graph LR
    subgraph LangGraphStateGraph["LangGraph StateGraph"]
        START["START"] --> agent["chatbot()"]
        agent -->|"tool_calls 存在"| tools["ToolNode<br/>get_shoe_data"]
        tools --> agent
        agent -->|"无 tool_calls"| END["END"]
    end

    subgraph GraphitiOperations["Graphiti 操作"]
        SEARCH["client.search()<br/>center_node_uuid=user_node_uuid<br/>返回 EntityEdge[]"]
        ADD["client.add_episode()<br/>source=EpisodeType.message<br/>asyncio.create_task()"]
        TOOL_SEARCH["client.search()<br/>center_node_uuid=manybirds_node_uuid"]
    end

    subgraph PersistenceLayer["持久化层"]
        MEM["MemorySaver<br/>内存检查点器"]
        GRAPH_DB["Neo4jDriver<br/>持久化图谱事实"]
    end

    agent -->|"检索上下文"| SEARCH
    agent -->|"持久化对话"| ADD
    tools -->|"产品查找"| TOOL_SEARCH
    SEARCH --> GRAPH_DB
    ADD --> GRAPH_DB
    TOOL_SEARCH --> GRAPH_DB
    agent <--> MEM

来源： examples/langgraph-agent/agent.ipynb:1-10, examples/langgraph-agent/agent.ipynb:111-127

分步设置
  1. 初始化 Graphiti：实例化 Graphiti 客户端。在 MCP 服务器中，这由 GraphitiService.initialize() 处理，它使用 LLMClientFactory 和 DatabaseDriverFactory 根据 GraphitiConfig 组装客户端：mcp_server/src/graphiti_mcp_server.py:171-185, mcp_server/src/services/factories.py:1-50。
  2. 导入产品数据：将产品记录作为 EpisodeType.json 类型的片段加载到图谱中。示例中的 ingest_products_data 函数演示了这一点。MCP 服务器为此提供了 add_memory 工具：examples/langgraph-agent/agent.ipynb:169-187, mcp_server/README.md:18-18。
  3. 定位关键实体节点：智能体使用 search_nodes 按名称定位实体节点。返回的 uuid 通过 center_node_uuid 参数锚定后续搜索：examples/langgraph-agent/agent.ipynb:217-217, mcp_server/README.md:19-19。
  4. 定义智能体工具：工具封装了 client.search()，通常通过 center_node_uuid 将结果固定到特定实体节点，以将检索偏向特定领域：examples/langgraph-agent/agent.ipynb:300-317。
  5. 上下文检索与持久化：智能体循环执行两个操作：
  • 检索：search_facts 获取实体之间的相关关系。
  • 持久化：add_memory 将新的交互轮次存储为片段：mcp_server/README.md:18-18。
关键代码实体
代码实体模块角色
Graphitigraphiti_core知识图谱客户端 examples/langgraph-agent/agent.ipynb:113-113
add_episode()graphiti_core.Graphiti持久化片段数据 examples/langgraph-agent/agent.ipynb:177-183
_search()graphiti_core.Graphiti检索相关节点/边 examples/langgraph-agent/agent.ipynb:217-217
LLMClientFactorymcp_server.services.factories创建特定提供商的 LLM 客户端 mcp_server/src/graphiti_mcp_server.py:179-180
EpisodeTypegraphiti_core.nodes枚举类型：json、text 或 message examples/langgraph-agent/agent.ipynb:114-114
QueueServicemcp_server.services.queue_service管理异步片段处理 mcp_server/src/graphiti_mcp_server.py:154-154

来源： examples/langgraph-agent/agent.ipynb:113-114, examples/langgraph-agent/agent.ipynb:177-183, examples/langgraph-agent/agent.ipynb:217-217, mcp_server/src/graphiti_mcp_server.py:154-154, mcp_server/src/graphiti_mcp_server.py:179-180

---

模式 2：MCP 服务器集成

MCP 服务器将 Graphiti 的操作暴露为 MCP 工具。任何兼容 MCP 的客户端都可以连接，而无需编写 Python 代码。该服务器支持 HTTP 传输（默认）和标准输入输出（stdio）传输。

MCP 工具与 Graphiti 映射

MCP 工具到 Graphiti 方法的映射图：

graph LR
    subgraph MCPTools["mcp_server 工具"]
        T1["add_memory"]
        T2["search_nodes"]
        T3["search_facts"]
        T4["get_entity_edge"]
        T5["delete_entity_edge"]
        T8["clear_graph"]
    end

    subgraph GraphitiCore["graphiti_core.Graphiti"]
        G1["add_episode()"]
        G2["_search()"]
        G3["search()"]
        G4["EntityEdge.get_by_uuid()"]
        G5["delete_entity_edge()"]
        G8["clear_data()"]
    end

    T1 --> G1
    T2 --> G2
    T3 --> G3
    T4 --> G4
    T5 --> G5
    T8 --> G8

来源： mcp_server/README.md:18-28, mcp_server/src/graphiti_mcp_server.py:129-135, mcp_server/src/graphiti_mcp_server.py:19-19

HTTP 传输模式

HTTP 传输模式通过 /mcp/ 的 REST 端点暴露 MCP 服务器，使其可以被任何支持基于 HTTP 的 MCP 通信的客户端（如 Cursor）访问。

架构
sequenceDiagram
    participant Client as "AI 智能体客户端<br/>(Cursor/VS Code)"
    participant HTTP as "HTTP 端点<br/>localhost:8000/mcp/"
    participant MCP as "mcp_server/src/graphiti_mcp_server.py<br/>FastMCP(Graphiti)"
    participant Graphiti as "graphiti_core.Graphiti"
    participant Driver as "Neo4jDriver /<br/>FalkorDriver /<br/>KuzuDriver /<br/>NeptuneDriver"

    Client->>HTTP: "POST /mcp/call_tool<br/>{tool: 'add_memory'}"
    HTTP->>MCP: "路由到工具处理器"
    MCP->>Graphiti: "add_episode()"
    Graphiti->>Driver: "提取与持久化"
    Driver-->>Graphiti: "OK"
    Graphiti-->>MCP: "SuccessResponse"
    MCP-->>HTTP: "JSON 响应"
    HTTP-->>Client: "成功"

来源： mcp_server/README.md:56-76, mcp_server/src/graphiti_mcp_server.py:163-163, graphiti_core/driver/neptune_driver.py:139-142, graphiti_core/driver/kuzu_driver.py:136-137

Cursor IDE 集成

Cursor IDE 使用简化的 HTTP 配置格式。将 URL http://localhost:8000/mcp/ 添加到 Cursor 的 MCP 设置中，即可使智能体使用 Graphiti 工具：mcp_server/README.md:56-76。

标准输入输出（stdio）传输模式

标准输入输出（stdio）传输模式使用标准输入/输出流进行通信，适用于像 Claude Desktop 这样将服务器作为子进程启动的 MCP 客户端。

Claude 桌面的配置

Claude Desktop 需要在其 config.json 中添加一个配置条目，指定命令和环境变量。服务器必须使用 --transport stdio 参数启动：

{
  "mcpServers": {
    "graphiti": {
      "command": "uv",
      "args": ["--directory", "/path/to/graphiti/mcp_server", "run", "src/graphiti_mcp_server.py", "--transport", "stdio"],
      "env": {
        "OPENAI_API_KEY": "your_key",
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_PASSWORD": "your_password"
      }
    }
  }
}

来源： mcp_server/README.md:44-54, mcp_server/src/graphiti_mcp_server.py:163-163, mcp_server/.env.example:1-12

并发与速率限制

SEMAPHORE_LIMIT 环境变量控制并发片段处理的数量。每个片段会触发多次 LLM 调用（提取、解析），因此应根据 LLM 提供商的层级调整信号量限制，以避免 429 错误：

提供商层级建议的 SEMAPHORE_LIMIT
OpenAI层级 1（免费）1–2
OpenAI层级 310–15
Anthropic默认5–8
Ollama本地1–5

来源： mcp_server/src/graphiti_mcp_server.py:48-75, mcp_server/.env.example:20-32

实体类型配置

内置实体类型在 config.yaml 中配置，LLM 在提取过程中使用这些类型对知识进行分类。这些类型在配置的 graphiti.entity_types 部分中定义：

  • 偏好（Preference）：用户的偏好、选择或意见（优先处理）。
  • 需求（Requirement）：需要满足的特定需求或功能。
  • 流程（Procedure）：标准操作流程和顺序指令。
  • 位置（Location）：物理或虚拟场所。
  • 事件（Event）：有时间限制的活动或事件。
  • 组织（Organization）：公司、机构或正式团体。
  • 文档（Document）：各种形式的信息内容。
  • 主题/对象（Topic/Object）：通用主题或项目的后备类别。

来源： mcp_server/README.md:193-207