agentic_huge_data_base / wiki
页面 RAGFlow · 8 智能体与工作流系统·DeepWiki 中文全文译文
DeepWiki 中文译文 / RAGFlow / 8

8 · 智能体与工作流系统（Agent and Workflow System）

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

项目RAGFlow 章节8 状态全文译文 模块系统架构、智能体运行时、测试、发布与运维、检索、召回与索引
项目要点页2.5 参考项目 项目章节目录RAGFlow DeepWiki 原始章节Agent and Workflow System 上一章7.8 下一章8.1
源码线索
  • .gitignore
  • agent/canvas.py
  • agent/component/agent_with_tools.py
  • agent/component/base.py
  • agent/component/categorize.py
  • agent/component/llm.py
  • agent/tools/base.py
  • bin/.gitkeep
  • common/mcp_tool_call_conn.py
  • rag/prompts/generator.py
模块标签
  • 系统架构
  • 智能体运行时
  • 测试、发布与运维
  • 检索、召回与索引
  • 界面与交互

章节正文

智能体与工作流系统

原始 DeepWiki 页面https://deepwiki.com/infiniflow/ragflow/8-agent-and-workflow-system

智能体与工作流系统

相关源文件

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

  • .gitignore
  • agent/canvas.py
  • agent/component/agent_with_tools.py
  • agent/component/base.py
  • agent/component/categorize.py
  • agent/component/llm.py
  • agent/tools/base.py
  • bin/.gitkeep
  • common/mcp_tool_call_conn.py
  • rag/prompts/generator.py
  • web/.eslintrc.cjs
  • web/src/components/embed-dialog/index.tsx
  • web/src/components/floating-chat-widget.tsx
  • web/src/components/next-message-item/group-button.tsx
  • web/src/components/pdf-drawer/hooks.ts
  • web/src/components/pdf-drawer/index.tsx
  • web/src/pages/agent/gobal-variable-sheet/index.tsx
  • web/src/pages/agent/hooks/use-build-dsl.ts
  • web/src/pages/agent/hooks/use-save-graph.ts
  • web/src/pages/agent/hooks/use-send-shared-message.ts
  • web/src/pages/agent/index.tsx

智能体与工作流系统提供了一个可视化编程环境，用于创建由 AI 驱动的工作流和自主智能体。它实现了一个基于图的执行引擎，用于编排组件管线、管理对话状态，并支持使用工具进行多步推理。该系统通过领域特定语言（DSL）将可视化工作流设计与后端执行连接起来。

有关大语言模型（LLM）集成和模型管理的信息，请参见 LLM 集成系统。有关 REST API 层的详细信息，请参见 后端 API 系统。

画布 DSL 与图模型

工作流系统构建于一个基于 JSON 的 DSL 之上，该 DSL 将工作流表示为支持循环和分支的有向图。每个工作流被称为一个“画布”，并作为序列化的 DSL 文档存储。

DSL 结构

DSL 由组件、全局状态和执行元数据组成：

{
  "components": {
    "begin": {
      "obj": {
        "component_name": "Begin",
        "params": {}
      },
      "downstream": ["component_id"],
      "upstream": []
    }
  },
  "history": [],
  "path": ["begin"],
  "retrieval": {"chunks": [], "doc_aggs": []},
  "globals": {
    "sys.query": "",
    "sys.user_id": "",
    "sys.conversation_turns": 0,
    "sys.files": []
  }
}

组件部分：每个组件包含其配置 obj agent/canvas.py:48-51，以及拓扑链接 downstream 和 upstream agent/canvas.py:52-53。

全局状态：globals 对象维护系统变量，如 sys.query 和 sys.files agent/canvas.py:75-80。

来源：agent/canvas.py:43-82

图类架构

图到代码的映射：

RAGFlow · 图类架构 · 图 1
RAGFlow · 图类架构 · 图 1

Graph 类 agent/canvas.py:43 使用 normalize_chunker_dsl agent/canvas.py:89 解析 DSL，通过 component_class agent/canvas.py:101-109 实例化组件对象，并管理执行路径。

来源：agent/canvas.py:43-109, agent/canvas.py:153-165

组件系统架构

组件是工作流的构建块。该系统使用工厂模式来实现动态组件注册和参数校验。

组件基类

组件实体空间：

RAGFlow · 组件基类 · 图 2
RAGFlow · 组件基类 · 图 2

ComponentParamBase agent/component/base.py:40-51：

  • 通过 check() agent/component/base.py:57 定义带校验的参数。
  • 实现递归配置更新 update() agent/component/base.py:127-187。
  • 处理已废弃参数的追踪 agent/component/base.py:61-95。

ComponentBase [agent/component/base.py:29]（在 agent/canvas.py:31 中被引用）：

  • 提供生命周期方法（_invoke, _invoke_async）。
  • 实现变量解析和输入/输出管理。

来源：agent/component/base.py:40-187, agent/canvas.py:30-31, agent/component/llm.py:83

状态与变量管理

画布维护着多个级别的状态，并提供了一个变量解析系统。

变量系统

变量类型：

  • sys.*：系统变量（query, user_id, files, history）。
  • env.*：用户定义的工作流变量。
  • component_id@output_key：对特定组件输出的引用。

用于变量检测的正则表达式模式 agent/canvas.py:169：

pat = re.compile(r"\{* *\{([a-zA-Z:0-9]+@[A-Za-z0-9_.-]+|sys\.[A-Za-z0-9_.]+|env\.[A-Za-z0-9_.]+)\} *\}*")
变量解析流程

变量解析 agent/canvas.py:195-204：

  • 如果表达式是 sys.* 或 env.*，则在 globals 字典中查找值。
  • 如果包含 @，则将字符串拆分为 cpn_id 和 var_nm agent/canvas.py:199。
  • 使用 get_component(cpn_id) agent/canvas.py:200 获取组件，并访问其输出。

来源：agent/canvas.py:166-204

智能体组件与 ReAct 循环

Agent 组件实现了 ReAct（推理 + 行动）模式，用于结合工具进行自主的多步任务执行。

智能体实现

Agent 组件 agent/component/agent_with_tools.py:73-74：

  • 继承自 LLM 和 ToolBase。
  • 使用 _load_tool_obj() agent/component/agent_with_tools.py:133-145 加载工具组件。
  • 将工具绑定到 LLMBundle，以实现模型驱动的工具调用 agent/component/agent_with_tools.py:113。
  • 通过 MCPServerService agent/component/agent_with_tools.py:101-104 支持 MCP（模型上下文协议） 工具集成。

工具调用基础设施：

  • LLMToolPluginCallSession agent/tools/base.py:50：管理工具插件的执行会话，通过 tool_call_async agent/tools/base.py:58-86 处理标准组件工具和 MCP 工具。
  • MCPToolCallSession common/mcp_tool_call_conn.py:49：使用 SSE 或可流式传输的 HTTP 传输协议 common/mcp_tool_call_conn.py:84-123 处理与 MCP 服务器的通信。

来源：agent/component/agent_with_tools.py:73-145, agent/tools/base.py:50-86, common/mcp_tool_call_conn.py:49-123

工作流执行与流式传输

执行引擎在处理组件的同时，支持动态分支和流式响应。

  • 消息格式化：系统使用 message_fit_in rag/prompts/generator.py:68 来确保提示词保持在 Token 限制内。
  • 上下文注入：从数据集检索到的知识通过 kb_prompt rag/prompts/generator.py:127 格式化为提示词。
  • 动态路径选择：像 Categorize agent/component/categorize.py:98 这样的组件通过设置 _next 输出 agent/component/categorize.py:158 来决定下一步。
  • 前端集成：基于 React 的画布 web/src/pages/agent/index.tsx:44 允许用户可视化地设计这些图，然后将其保存为 DSL。
  • 嵌入式组件：工作流可以作为嵌入式聊天组件 web/src/components/floating-chat-widget.tsx:87 共享，使用 EmbedDialog web/src/components/embed-dialog/index.tsx:115。

来源：rag/prompts/generator.py:68-163, agent/component/categorize.py:98-158, web/src/pages/agent/index.tsx:44, web/src/components/floating-chat-widget.tsx:87, web/src/components/embed-dialog/index.tsx:115

子页面

  • 画布引擎与 DSL — 记录 Canvas 类、DSL 结构、基于图的执行模型，以及工作流的存储和加载方式
  • 组件系统架构 — 解释组件基类、参数校验、组件工厂模式和动态注册
  • 内置组件 — 记录标准组件库，包括 LLM、检索、工具、分类、生成、消息、开关、迭代和智能体组件
  • 工作流执行与流式传输 — 解释基于路径的执行算法、流式支持以及工作流运行期间的 SSE 事件生成
  • 状态与变量管理 — 记录变量解析系统（sys.*, env.*, component@output）、全局状态管理和上下文处理
  • 智能体工具与 ReAct 循环 — 解释 Agent 组件的 ReAct 模式、工具调用机制、MCP 集成、多步推理以及用于扩展工具能力的插件系统
  • 画布 API 与管理 — 详述画布的 CRUD 端点、版本管理、副本系统和对话会话处理