Agent Canvas/Component System/ — Component System

Contents

Architecture

graph TB
    BASE["ComponentBase
Abstract Lifecycle"]
    PARAM["ComponentParamBase
Parameter Schema"]
    BASE --> PARAM
    
    REGISTRY["Component
Registry"]
    BASE --> REGISTRY
    
    BEGIN["Begin
Entry"] --> REGISTRY
    LLM["LLM
Chat"] --> REGISTRY
    AGENT["Agent
Tools"] --> REGISTRY
    SWITCH["Switch
Route"] --> REGISTRY
    ITER["Iteration
Loop"] --> REGISTRY
    LOOP["Loop
Struct"] --> REGISTRY
    MSG["Message
Format"] --> REGISTRY
    INVOKE["Invoke
Direct"] --> REGISTRY

flowchart TD
    Init["__init__
Configure"]
    Validate["validate_params
Schema Check"]
    Run["run()
Execute"]
    Cache["Output Cache
Stored"]
    Serialize["to_dict()
Serialize"]
    
    Init --> Validate
    Validate --> Run
    Run --> Cache
    Cache --> Serialize
    style Init fill:#c8e6c9
    style Cache fill:#ffccbc
    style Serialize fill:#b3e5fc

Key Classes

Data Structures

Interactions

Configuration

Directory Map

submod_name/
├── file_a.ext                 ← Role: brief annotation
├── file_b.ext                 ← Role: brief annotation
├── file_c.ext                 ← Role: brief annotation
└── index.ext                  ← Role: entry point

📑 Annotated Code Walkthrough

The most important code in this sub-module, annotated with WHY each piece exists:

// Replace with actual code from the source
void key_function() {
    // ← WHY: Explain the purpose of this line
    // ← WHY: What constraint or requirement drives this?
}

⚠️ Edge Cases & Boundaries

Deep-Dive Highlights

Core mechanisms from this sub-module have been extracted into dedicated focus pages for in-depth exploration. Each page covers one algorithm, protocol, or subsystem with diagrams, code walks, and configuration details.

Deep-Dive Pages

Code Examples

Example: Typical Usage

// Replace with actual code example
void example() {
    // ...
}

Component Lifecycle in Detail

Each component instance goes through a well-defined lifecycle from instantiation to execution to cleanup. Understanding this helps with debugging state management issues.

Phase 1: Instantiation

• Trigger: Canvas.load() encounters component spec in DSL with type="component_type"
• Registry lookup: ComponentRegistry.get("component_type") returns factory function
• Factory call: Factory(component_id, config_dict) instantiates component; stores config in self._config
• Outcome: Component object created but not yet validated; stored in Canvas._components[component_id]

Phase 2: Validation

• Trigger: Canvas.load() calls component.validate_params() after instantiation
• Schema check: For each parameter in component._schema, verify:
  • Required params are present in self._config
  • Parameter type matches schema (string, int, list, dict, etc.)
  • Custom validators (min/max, regex, enum) pass
• Outcome: If valid, component is ready. If invalid, ValidationError raised; Canvas.load() fails; workflow not executable.

Phase 3: Execution

• Trigger: Canvas.execute() determines component has all dependencies resolved
• Input prep: Canvas resolves all variable references in parameters; builds inputs dict
• Run: component.run(inputs) called; component logic executes
• Output capture: Component returns output dict; Canvas stores in _outputs[component_id]
• Error handling: If exception raised:
  • Check if retriable (network error, timeout, API rate limit)
  • If retriable, sleep(backoff_ms) then call run() again (max 5 attempts)
  • If not retriable or retries exhausted, use exception_default_value or exception_goto if configured
  • If no fallback, exception propagates; workflow halts

Phase 4: History Recording

• Trigger: After component.run() completes (success or error)
• Record: Canvas appends execution step to _history list: {step_id, component_id, inputs, outputs, error, timestamp, duration_ms}
• Use case: Post-execution audit, debugging, compliance logging, performance analysis
• Cost: O(N) memory where N = total executed nodes; disable if memory constrained (set history_enabled=False in Canvas init)

Component Registry & Plugin System

RAGFlow uses a dynamic registry pattern to load components. The system supports both built-in and custom plugins, enabling extensibility without modifying core code.

Registry Architecture

• Centralized Registry: ComponentRegistry singleton maintains type → class mapping. Populated at runtime via imports and decorators.
• Lazy Loading: Components loaded on first DSL reference; avoids circular imports and unused overhead.
• Plugin Discovery: Custom components in agent/components/custom/ auto-discovered via __init__.py exports; decorated with @register_component("type_name").
• Fallback Logic: If component type not in registry at execution time, raises ComponentNotFound immediately. No silent defaults; explicit error handling required.

Extending with Custom Components

Component Init Order

When Canvas.load() executes, components are instantiated in dependency order:

1. DSL parsed into Graph object with component specs
2. Topological sort on the DAG
3. Each component class looked up in registry by type name
4. __init__() called with merged config (DSL defaults + runtime overrides)
5. validate_params() invokes schema validation; raises ValueError if invalid
6. Component instance added to _components[component_id]; ready to execute