This page documents the standard components available in RAGFlow's Canvas workflow system. These components serve as building blocks for constructing AI agent workflows, ranging from simple LLM invocations to complex multi-tool agent orchestrations with retrieval and conditional routing.
For information about the component architecture and registration system, see Component System Architecture. For details on workflow execution and how components interact during runtime, see Workflow Execution and Streaming.
RAGFlow provides a library of built-in components that inherit from ComponentBase (agent/component/base.py365-585) and define reusable workflow operations. Each component consists of a parameter class (inheriting from ComponentParamBase) and an implementation class that provides the _invoke method.
Built-in components fall into five functional categories:
| Category | Components | Purpose |
|---|---|---|
| LLM Interaction | LLM, Agent | Direct LLM calls with prompt templates and tool-augmented ReAct agents |
| Information Retrieval | Retrieval, Generate | Knowledge base search and context-aware content generation |
| Control Flow | Categorize, Switch, Iteration, Loop, ExitLoop | Conditional branching and iterative execution |
| User Interaction | Begin, UserFillUp, Message | Workflow entry points and user input collection |
| Content Processing | Template | Dynamic prompt construction with variable substitution |
The LLM component (agent/component/llm.py82-448) provides direct access to language models with configurable prompts, generation parameters, and optional structured output.
Sources: agent/component/llm.py33-80 agent/component/llm.py82-448
Core Parameters (agent/component/llm.py33-59):
llm_id (required): Model identifier from tenant LLM configurationsys_prompt: System-level instructions prepended to conversationprompts: List of message dictionaries with role and content fieldsmessage_history_window_size: Number of previous messages to include (default: 13)Generation Control (agent/component/llm.py61-79):
temperature: Sampling randomness (0.0-1.0)max_tokens: Maximum response lengthtop_p: Nucleus sampling thresholdpresence_penalty: Repetition penalty for new topicsfrequency_penalty: Repetition penalty for frequent tokensAdvanced Features (agent/component/llm.py48-50):
cite: Enable automatic citation insertion for retrieved contentoutput_structure: JSON schema for structured output validationvisual_files_var: Variable reference for image inputsThe LLM component supports variable references in both system prompts and message content using the syntax {component_id@output_var} or {sys.variable}. Variables are resolved during invocation (agent/component/llm.py226-259):
Sources: agent/component/base.py500-511 agent/component/llm.py102-109 agent/canvas.py164-236
When output_structure is configured with a JSON schema, the component enforces format compliance through retry logic (agent/component/llm.py365-448):
structured_output_prompt() (rag/prompts/generator.py443-445)json_repair.loads() for robustnessmax_retries times_ERROR output instead of throwing exceptionThe component automatically detects base64-encoded images in input variables (agent/component/llm.py129-167):
data:image/ prefixed strings from all input valuesLLMType.IMAGE2TEXT model if images are present (agent/component/llm.py248-252)LLMBundle.async_chat() via images parameterThe Agent component (agent/component/agent_with_tools.py83-534) implements a ReAct (Reasoning + Acting) loop that iteratively calls language models to plan actions, invoke tools, and reflect on results until completing the task.
Sources: agent/component/agent_with_tools.py38-81 agent/component/agent_with_tools.py83-118
The agent loads tool components during initialization (agent/component/agent_with_tools.py88-116):
For MCP (Model Context Protocol) servers, the agent establishes connections and registers remote tools (agent/component/agent_with_tools.py108-114).
The agent's core execution logic (agent/component/agent_with_tools.py278-419) follows this pattern:
Sources: agent/component/agent_with_tools.py278-419 rag/prompts/generator.py395-414
The agent uses specialized prompts for different phases (rag/prompts/generator.py172-177):
ANALYZE_TASK_SYSTEM + ANALYZE_TASK_USER): Breaks down the user request and available toolsNEXT_STEP): Determines which tool to invoke next based on conversation historyREFLECT): Summarizes tool call results and updates understandingThe next_step_async() function (rag/prompts/generator.py395-414) orchestrates tool selection:
Sources: rag/prompts/generator.py395-414 agent/component/agent_with_tools.py376-410
Every tool invocation triggers a callback that logs execution details to Redis (agent/canvas.py779-801):
This enables the trace visualization feature accessed via /canvas/trace endpoint (api/apps/canvas_app.py551-563).
When both tools and structured output are configured, the agent completes tool calls before enforcing schema validation (agent/component/agent_with_tools.py200-254):
complete_task is calledstructured output keyThe Categorize component (agent/component/categorize.py97-164) classifies user input into predefined categories and routes execution to different downstream components based on the classification result.
Sources: agent/component/categorize.py29-95 agent/component/categorize.py97-164
Each category in category_description is a dictionary with three fields (agent/component/categorize.py36-48):
The component dynamically builds a classification prompt (agent/component/categorize.py58-94):
USER: "query" → category_nameSources: agent/component/categorize.py107-156 agent/canvas.py612-613
If the LLM response doesn't clearly match any category, the component defaults to the last defined category (agent/component/categorize.py149-153). This ensures workflow execution always continues.
The Retrieval component (referenced in agent/canvas.py52-59) performs hybrid search over knowledge bases, combining vector similarity and keyword matching to retrieve relevant document chunks.
Based on the DSL structure in Canvas initialization:
The component produces two output variables:
content: Formatted string representation of retrieved chunks (via kb_prompt() from rag/prompts/generator.py99-143)_references: Structured list of chunk metadata for citationRetrieval results are automatically added to the canvas reference store (agent/canvas.py803-821):
The Generate component (mentioned in agent/canvas.py60-67) performs context-aware text generation, typically consuming retrieval results and user queries to produce grounded answers.
Sources: agent/canvas.py42-78
When the Generate component's cite parameter is enabled and retrieval results exist, the component automatically inserts citations using the pattern [ID: N] where N is a hash of the chunk ID (rag/prompts/generator.py159 common/misc_utils.py25).
The citation prompt template (rag/prompts/generator.py159-160) instructs the LLM to:
[ID: hash]The Template component (referenced in workflow examples) provides Jinja2-based templating for dynamic prompt construction with complex variable substitution.
The template engine supports:
The Message component (agent/canvas.py503-562) handles final output delivery to users, supporting text content, attachments, status codes, and optional text-to-speech conversion.
Sources: agent/canvas.py503-562
When auto_play parameter is enabled (agent/canvas.py504-505), the component:
LLMBundle with LLMType.TTStts() method (agent/canvas.py675-716)audio_binary in message events for client-side playbackText is cleaned before TTS (agent/canvas.py676-703):
If the message content contains citation patterns ([ID: N]), the component automatically attaches retrieval references via get_reference() (agent/canvas.py560-561 agent/canvas.py818-821).
The Begin component (agent/canvas.py446-448) serves as the workflow entry point, accepting initial user inputs and system-level configuration.
Standard Mode: Receives query and files via Canvas API (api/apps/canvas_app.py132-186)
Webhook Mode (agent/canvas.py378-387): Accepts payload via HTTP webhook with custom input mapping:
The Begin component's prologue parameter (agent/canvas.py733-734) defines an initial assistant message shown before workflow execution, useful for greetings or instructions.
The UserFillUp component (agent/canvas.py628-642) pauses workflow execution to collect additional user inputs mid-execution.
Sources: agent/canvas.py628-642 agent/canvas.py410-412
The component defines required inputs through its parameter class:
When enable_tips is true, the tips content is shown to users in the input prompt (agent/canvas.py638-639).
The Switch component (referenced in agent/canvas.py612) provides multi-way branching based on expression evaluation, similar to switch-case statements in programming languages.
The Iteration component (agent/canvas.py608-611 agent/canvas.py614-615) repeats its child components over a collection:
Sources: agent/canvas.py608-621
The Loop component (agent/canvas.py608-611 agent/canvas.py614-621) provides conditional looping with explicit exit conditions:
Sources: agent/canvas.py608-621
When an ExitLoop component is executed within a Loop's child context, the loop terminates and execution proceeds to the Loop's downstream components (agent/canvas.py616-617).
All components follow consistent I/O patterns defined by the base classes.
Components declare inputs by scanning their parameter values for variable references (agent/component/base.py500-511):
Components write outputs using set_output(key, value) (agent/component/base.py458-461):
Special output keys:
_ERROR: Signals component failure, triggers exception handler (agent/component/base.py463-464)_next: Controls routing for branching components (agent/canvas.py612-613)_created_time / _elapsed_time: Performance metrics (agent/component/base.py408 agent/component/base.py418)| Pattern | Example | Description |
|---|---|---|
| Component output | {retrieval_0@content} | References specific component's output variable |
| System variable | {sys.query} | Accesses canvas global state |
| Environment variable | {env.api_key} | User-defined workflow variables |
| Nested access | {[email protected]} | Dot notation for nested object fields |
Sources: agent/component/base.py368 agent/canvas.py164-206
The Canvas system provides a debug endpoint for testing individual components in isolation (api/apps/canvas_app.py332-366).
Sources: api/apps/canvas_app.py332-366
For LLM and Agent components, streaming outputs (stored as partial objects) are fully resolved during debug to return complete text (api/apps/canvas_app.py354-362).
Sources: agent/component/base.py407-447 agent/canvas.py571-581
Components support three exception handling strategies (agent/component/base.py567-582):
exception_goto parameterexception_default_valueException configuration is stored in component parameters (agent/component/base.py46-50) and evaluated after component execution (agent/canvas.py571-581).
Sources: agent/component/base.py365-585 agent/component/llm.py33-448 agent/component/agent_with_tools.py38-534 agent/component/categorize.py29-164 agent/canvas.py40-831 api/apps/canvas_app.py132-366 rag/prompts/generator.py159-467 agent/tools/base.py34-216
Refresh this wiki