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

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

时序知识图谱与动态事实记忆 · 聚焦本章的模块关系、源码依据与实现要点。

项目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

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 的客户端连接。

集成模式示意图：

Graphiti · 集成架构总览 · 图 1
Graphiti · 集成架构总览 · 图 1

来源： 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 数据流图：

Graphiti · 智能体架构 · 图 2
Graphiti · 智能体架构 · 图 2

来源： 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 方法的映射图：

Graphiti · MCP 工具与 Graphiti 映射 · 图 3
Graphiti · MCP 工具与 Graphiti 映射 · 图 3

来源： 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）访问。

架构
Graphiti · 架构 · 图 4
Graphiti · 架构 · 图 4

来源： 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