agentic_huge_data_base / wiki
页面 RAGFlow · 7.7 智能体与记忆 API·DeepWiki 中文全文译文
DeepWiki 中文译文 / RAGFlow / 7.7

7.7 · 智能体与记忆 API（Agent and Memory APIs）

复杂文档理解与引用检索 · 聚焦本章的模块关系、源码依据与实现要点。

项目RAGFlow 章节7.7 状态全文译文 模块界面与交互、系统架构、记忆与上下文、配置治理
项目要点页2.5 参考项目 项目章节目录RAGFlow DeepWiki 原始章节Agent and Memory APIs 上一章7.6 下一章7.8
源码线索
  • api/apps/restful_apis/agent_api.py
  • api/apps/restful_apis/memory_api.py
  • api/apps/services/memory_api_service.py
  • api/db/services/canvas_service.py
  • api/db/services/conversation_service.py
  • api/db/services/memory_service.py
  • api/utils/memory_utils.py
  • deepdoc/parser/mineru_parser.py
  • test/testcases/test_http_api/test_session_management/test_agent_completions.py
  • test/testcases/test_http_api/test_session_management/test_agent_sessions.py
模块标签
  • 界面与交互
  • 系统架构
  • 记忆与上下文
  • 配置治理
  • 测试、发布与运维

章节正文

智能体与记忆 API

原始 DeepWiki 页面https://deepwiki.com/infiniflow/ragflow/7.7-agent-and-memory-apis

代理与记忆 API

相关源文件

本章引用的主要源码文件：

  • api/apps/restful_apis/agent_api.py
  • api/apps/restful_apis/memory_api.py
  • api/apps/services/memory_api_service.py
  • api/db/services/canvas_service.py
  • api/db/services/conversation_service.py
  • api/db/services/memory_service.py
  • api/utils/memory_utils.py
  • deepdoc/parser/mineru_parser.py
  • test/testcases/test_http_api/test_session_management/test_agent_completions.py
  • test/testcases/test_http_api/test_session_management/test_agent_sessions.py
  • test/testcases/test_http_api/test_session_management/test_chat_completions.py
  • test/testcases/test_http_api/test_session_management/test_session_sdk_routes_unit.py
  • test/testcases/test_web_api/test_agent_app/test_agents_webhook_unit.py
  • test/testcases/test_web_api/test_memory_app/conftest.py
  • test/testcases/test_web_api/test_memory_app/test_create_memory.py
  • test/testcases/test_web_api/test_memory_app/test_list_memory.py
  • test/testcases/test_web_api/test_memory_app/test_rm_memory.py
  • test/testcases/test_web_api/test_memory_app/test_update_memory.py
  • web/src/components/home-card.tsx
  • web/src/hooks/use-agent-request.ts
  • web/src/interfaces/database/agent.ts
  • web/src/pages/agents/agent-card.tsx
  • web/src/pages/agents/agent-dropdown.tsx
  • web/src/pages/dataset/dataset/reparse-dialog.tsx
  • web/src/pages/dataset/dataset/use-run-document.ts
  • web/src/pages/dataset/process-log-modal.tsx
  • web/src/pages/memories/add-or-edit-modal.tsx
  • web/src/pages/memories/constants/index.tsx
  • web/src/pages/memories/hooks.ts
  • web/src/pages/memories/interface.ts
  • web/src/pages/memory/memory-message/hook.ts
  • web/src/pages/memory/memory-message/index.tsx
  • web/src/pages/memory/memory-message/interface.ts
  • web/src/pages/memory/memory-message/message-table.tsx
  • web/src/pages/memory/memory-setting/advanced-settings-form.tsx
  • web/src/pages/memory/memory-setting/hook.ts
  • web/src/pages/memory/memory-setting/index.tsx
  • web/src/pages/memory/memory-setting/memory-model-form.tsx
  • web/src/services/agent-service.ts
  • web/src/services/memory-service.ts

概述

本文档详细介绍了用于管理 RAGFlow 代理（画布）系统和持久化记忆子系统的技术实现与 API。这些 API 支持对可视化工作流、代理生命周期管理和会话状态持久化进行编程式编排。

代理系统基于图结构的领域特定语言（DSL）构建，由 Canvas 引擎解释执行 api/apps/restful_apis/agent_api.py:32，而记忆系统则使用关系数据库和向量文档存储实现多层持久化 api/db/services/memory_api_service.py:22-25。

代理与画布管理

HTTP API：代理 CRUD 操作

代理管理层提供用于操作 UserCanvas 和 UserCanvasVersion 实体的端点。这些端点主要在 agent_api.py 中定义，并由 UserCanvasService 支持 api/apps/restful_apis/agent_api.py:40-42。

端点结构：

  • 模板： GET /templates 通过 CanvasTemplateService 返回预定义的代理结构 api/apps/restful_apis/agent_api.py:41。
  • 列出会话： GET /agents/<agent_id>/sessions 检索与特定代理关联的对话历史，支持可选地包含 DSL api/apps/restful_apis/agent_api.py:152-172。
  • 会话详情： API4ConversationService 处理这些会话的抽象，在底层存储中区分 chat 和 agent 类型 api/db/services/conversation_service.py:21。

关键逻辑流程：

  1. 访问控制：端点使用 @_require_canvas_access_sync 等装饰器来验证 tenant_id 是否具有特定 agent_id 的权限 api/apps/restful_apis/agent_api.py:71-77。
  2. 版本管理：UserCanvasVersionService 维护代理配置的历史记录，支持稳定执行和回滚能力 api/apps/restful_apis/agent_api.py:52。
  3. 搜索与过滤：UserCanvasService.get_by_tenant_ids 支持关键词搜索、标签过滤和基于权限的可见性（例如 TenantPermission.TEAM）api/db/services/canvas_service.py:144-186。

标题：代理持久化与访问控制流程

RAGFlow · HTTP API：代理 CRUD 操作 · 图 1
RAGFlow · HTTP API：代理 CRUD 操作 · 图 1

来源：api/apps/restful_apis/agent_api.py:71-145，api/db/services/canvas_service.py:144-186，api/db/services/conversation_service.py:38-54

代理执行与会话管理

执行由 Canvas 类驱动，并通过补全端点对外暴露。前端通过 agentService 和自定义钩子与这些端点交互 web/src/hooks/use-agent-request.ts:23-34。

代理会话：

  • 创建： POST /agents/{id}/sessions 初始化一个新会话。在后端，这涉及 ConversationService.save，并可选择使用开场白消息进行初始化 api/db/services/conversation_service.py:117-131。
  • 交互： 交互逻辑处理 SSE（服务器发送事件）流式传输的复杂性，解析响应标记，并使用引用构建消息对象 api/db/services/conversation_service.py:73-114。

补全流程： 当用户提问时，请求会触发图执行。conversation_service.py 中的 async_completion 函数管理消息历史，使用唯一 ID 追加用户问题，并调用 async_chat 来处理检索增强生成（RAG）工作流 api/db/services/conversation_service.py:117-192。

来源：api/db/services/conversation_service.py:73-192，web/src/hooks/use-agent-request.ts:23-34，api/apps/restful_apis/agent_api.py:116-121

记忆系统 API

记忆系统为代理提供持久化状态，支持原始记忆、语义记忆和情景记忆类型。

记忆配置与管理

记忆实体通过 memory_api.py 进行管理，并由 memory_api_service.py 提供后端支持 api/apps/restful_apis/memory_api.py:25-32。

核心记忆 API：

  • 创建： POST /memories 需要名称、类型和模型 ID（embd_id、llm_id）。创建前会确保租户模型 ID 有效 api/apps/restful_apis/memory_api.py:29-51。
  • 更新： PUT /memories/{memory_id} 允许修改遗忘策略（LRU/FIFO）、温度和系统提示词 api/apps/restful_apis/memory_api.py:90-97，web/src/pages/memory/memory-setting/advanced-settings-form.tsx:12-19。
  • 检索： GET /memories/{memory_id} 获取与记忆关联的消息，支持关键词搜索和按 agent_ids 过滤 api/apps/restful_apis/memory_api.py:160-174。

标题：记忆系统实体映射

RAGFlow · 记忆配置与管理 · 图 2
RAGFlow · 记忆配置与管理 · 图 2

来源：api/apps/restful_apis/memory_api.py:29-51，api/apps/services/memory_api_service.py:22-25，web/src/pages/memory/memory-setting/advanced-settings-form.tsx:12-27

记忆数据流与持久化

记忆数据存储在文档存储中用于语义检索，同时存储在关系表中用于元数据管理。

  1. 校验：系统在配置期间校验记忆类型（例如 table、graph）和遗忘策略 web/src/pages/memory/memory-setting/advanced-settings-form.tsx:14-15。
  2. 模型绑定：ensure_tenant_model_id_for_params 将用户选择的模型名称映射为当前用户的特定 tenant_llm_id 和 tenant_embd_id api/apps/restful_apis/memory_api.py:38-50。
  3. 前端集成：AdvancedSettingsForm 提供用于配置 temperature 和 forgetting_policy 等参数的 UI web/src/pages/memory/memory-setting/advanced-settings-form.tsx:105-136。

标题：消息到记忆的持久化序列

RAGFlow · 记忆数据流与持久化 · 图 3
RAGFlow · 记忆数据流与持久化 · 图 3

来源：api/apps/restful_apis/agent_api.py:116-145，api/db/services/conversation_service.py:117-192，api/apps/services/memory_api_service.py:172-174，web/src/pages/memory/memory-setting/advanced-settings-form.tsx:91-104