Deep Dive: Visual Graph Editor

The agent canvas editor is RAGFlow's flagship feature: a drag-drop interface for composing agent DSLs as directed graphs. Under the hood, it's powered by @xyflow/react (React Flow v12) with Zustand state management, real-time serialization to JSON, and node type registry for extensibility.

🎨 Canvas Architecture

Core Components

🔄 User Interaction Flow

1. Load Agent

// User clicks agent in list
const handleSelectAgent = (agentId: string) => {
    const { data: agent } = useAgentDetail(agentId);
    // Deserialize JSON → nodes[] + edges[]
    const { nodes, edges } = parseAgentDSL(agent.dsl);
    store.setNodes(nodes);
    store.setEdges(edges);
};

2. Add Node

// Drag from toolbar or double-click canvas
const handleCanvasClick = (event, pos) => {
    const nodeId = generateId();
    const newNode = {
        id: nodeId,
        type: 'llm',  // LLM node
        position: pos,
        data: { label: 'GPT-4', model: 'gpt-4' }
    };
    store.addNode(newNode);
    store.selectNode(nodeId);  // Highlight for editing
};

3. Connect Nodes

// React Flow handles drag from output port → input port
const onConnect = (connection) => {
    const edge = {
        id: `${connection.source}-${connection.target}`,
        source: connection.source,
        target: connection.target,
        animated: true
    };
    store.addEdge(edge);
};

4. Edit Node Config

// Double-click node → open edit panel
const handleNodeClick = (e, node) => {
    store.selectNode(node.id);
    store.openEditPanel(node.id);  // Show form with node config
};

// Form submission
const handleUpdateNode = (config) => {
    store.updateNodeData(selectedNodeId, config);
    // Form uses RagFlow dynamic form builder
};

5. Save Agent

// Click save button
const handleSave = async () => {
    const { nodes, edges } = store.getState();
    
    // Validate
    if (!validateGraph(nodes, edges)) {
        toast.error('Invalid graph');
        return;
    }
    
    // Serialize to JSON DSL
    const dsl = serializeGraph(nodes, edges);
    
    // Send to backend
    agentMutation.mutate({
        id: agentId,
        dsl: JSON.stringify(dsl)
    });
};

📊 Graph Serialization Format

JSON DSL structure: Backend expects this format.

{
  "version": "1.0",
  "nodes": [
    {
      "id": "node-1",
      "type": "llm",
      "config": {
        "model": "gpt-4",
        "temperature": 0.7,
        "system_prompt": "You are a helpful assistant"
      }
    },
    {
      "id": "node-2",
      "type": "tool",
      "config": {
        "name": "search",
        "params": ["query"]
      }
    }
  ],
  "edges": [
    {
      "source": "node-1",
      "target": "node-2",
      "label": "execute"
    }
  ]
}

🛠️ Advanced Features

Undo/Redo

Zustand store maintains history stack:

store.addToHistory(currentState);
// Ctrl+Z to undo
// Ctrl+Shift+Z to redo

Node Validation

Each node has JSON schema defining required fields:

const llmNodeSchema = {
  type: 'object',
  required: ['model', 'system_prompt'],
  properties: {
    model: { type: 'string', enum: ['gpt-4', 'gpt-3.5', 'claude'] },
    temperature: { type: 'number', min: 0, max: 2 },
    system_prompt: { type: 'string', minLength: 1 }
  }
};

Dynamic Node Types

Node registry is extensible. Register custom nodes:

// In node registry
registerNodeType('custom-tool', {
  component: CustomToolNode,
  category: 'tools',
  description: 'Custom integration tool',
  schema: customToolSchema
});

Multi-Select & Group

Select multiple nodes with Ctrl+Click; drag to move group. React Flow handles bounding box calculation.

Minimap

Small viewport showing full graph in corner; drag minimap selection to pan main canvas.

⚡ Performance Considerations

• Node limit: Tested up to 100+ nodes smoothly. Beyond that, consider node clustering.
• Layout algorithms: Auto-layout (dagre) runs on demand, not real-time, to avoid thrashing.
• React Flow hooks: Use useReactFlow() sparingly (causes re-renders); prefer Zustand for state.
• Large graphs: Virtualizing edges/nodes may be needed for 500+ node graphs (not yet implemented).

🐛 Common Issues & Debugging

📚 Reference

• React Flow Docs: https://reactflow.dev/api-reference/
• Zustand Store API: https://github.com/pmndrs/zustand
• Node/Edge Types: See src/pages/agent/nodeTypes/
• Validation Schema: Zod schema for each node type in src/pages/agent/schemas/

Next Steps

• Extend node types: Create custom integration node in nodeTypes/
• Add layout algorithms: Integrate ELK or Dagre for auto-arrangement
• Performance tuning: Profile large graphs (100+ nodes) and optimize rendering
• Back to Pages Module

{{TOPIC_NAME}}

Contents

Overview

flowchart TD
  A["Input / Trigger"] --> B["Phase 1"]
  B --> C["Phase 2"]
  C --> D["Phase 3"]
  D --> E["Output / Result"]

Replace with context-specific description of the overview diagram.

Decision Points

How It Works

Detailed explanation of the mechanism, algorithm, or protocol. This is where the focus page adds value over the brief L2 mention. Anchor every paragraph to concrete symbols, tables, masks, counters, or states from the real code.

Phase/Step 1

Detailed explanation of the first phase. Include specific variable names, thresholds, or conditions from the source code.

// Replace with actual code from the source
void step1_example() {
    // ...
}

Phase/Step 2

Continue with subsequent phases...

Behavior Diagram

stateDiagram-v2
    [*] --> Idle
    Idle --> Active : trigger
    Active --> Processing : start
    Processing --> Done : complete
    Processing --> Error : fail
    Error --> Idle : reset
    Done --> Idle : next

Replace with description of state transitions or message sequences specific to this topic.

Annotated Code Walkthrough

Walk through the actual source code step by step, with explanations between each snippet.

// Replace with real code snippet from source
void entry_point(Input& input) {
    if (!validate(input)) return;
    // ...
}

// Next real code snippet
Result process(Input& input) {
    // The critical branch:
    if (input.type == FAST_PATH) {
        return fast_process(input);
    }
    return slow_process(input);
}

Edge Cases & Error Handling

🔄 Why Not Alternatives?

Understanding why the current approach was chosen requires seeing what was rejected:

⚖️ Complexity & Tradeoffs

🚨 Failure Recovery

Configuration

Related Topics

See also:

• {{SUBMOD_NAME}} overview — the parent L2 page

Directory Map

submod_name/
├── relevant_file_a.ext        ← Role: brief annotation
├── relevant_file_b.ext        ← Role: brief annotation
└── relevant_file_c.ext        ← Role: brief annotation