Canvas Architecture#

RAGFlow supports two distinct canvas types — AgentCanvas and DataflowCanvas — that share the same DSL wire format and database table but differ in purpose, seed structure, component set, and model configuration behavior.

Canvas Type Enum#

The distinction is encoded in two enums:

• Frontend — AgentCategory in web/src/constants/agent.tsx:

  • AgentCategory.AgentCanvas = 'agent_canvas'
  • AgentCategory.DataflowCanvas = 'dataflow_canvas'

• Backend — CanvasCategory in api/db/__init__.py:

  • CanvasCategory.Agent = "agent_canvas"
  • CanvasCategory.DataFlow = "dataflow_canvas"

The canvas_category field on UserCanvas (database column, max_length=32, default="agent_canvas") stores this value and is indexed for efficient filtering. CanvasCategory.Agent is the default for new canvases created via the API.

Creation and DSL Initialization#

When a new canvas is created, useCreateAgentOrPipeline passes isAgent (derived from FlowType in the creation form) to initialEmptyDsl, which selects the appropriate seed:

The DataflowCanvas seed pre-wires a File→Parser edge and seeds initialParserValues into the Parser node's form data 1. The AgentCanvas seed initializes the full globals map (sys.query, sys.user_id, sys.conversation_turns, sys.files, sys.history, sys.date) 2; the DataflowCanvas seed sets globals: {}.

Import detection: inferIsAgentFromImport detects canvas type from an uploaded DSL file by checking if graph nodes include both File and Parser operators (dataflow) — defaulting to agent if ambiguous.

DSL Structure (Shared Wire Format)#

Both canvas types use the same canonical DSL shape 3:

{
  globals, graph: { nodes, edges }, // React-Flow layout surface
  variables, components, // execution topology
  path, retrieval, history
}

The frontend rebuilds components from graph on every save; the backend reads components only and ignores graph. The graph block is the single source of truth for import/export.

DSL transformations are handled by four functions in dsl-bridge.ts:

Component Set Differences#

The Operator enum defines all component types for both canvas types in a single enum. DataflowCanvas-specific operators are: File, Parser, Tokenizer, TokenChunker, TitleChunker, Extractor, Compilation 4. The pipeline operator form dispatcher PipelineOperatorForm routes to these dedicated forms (Parser, TokenChunker, TitleChunker, Extractor, Tokenizer) — it returns null for any unrecognized operator, so AgentCanvas-only operators don't render in the pipeline panel.

LLM Model Configuration#

AgentCanvas LLM configuration is set globally at the canvas level via initialLlmBaseValues 5:

temperature: 0.1, top_p: 0.3, frequency_penalty: 0.7, presence_penalty: 0.4, max_tokens: 256

DataflowCanvas pipeline components that require LLM access (e.g., Extractor) configure the model per-component. The Extractor form 6 embeds LlmSettingSchema — a Zod schema combining llm_id, generation parameters, and enable/disable flags 7 — directly into each node's form. The LargeModelFormField component 8 renders the model picker with a filter dropdown that scopes the model list to all, Chat, or Image2text types.

initialExtractorValues 9 spreads initialLlmBaseValues and adds field_name: 'summary', auto_keywords: 0, auto_questions: 0 as pipeline-specific defaults.

Key Source Files#