Principle:FlowiseAI Flowise Agentflow Node Status Monitoring
| Property | Value |
|---|---|
| Page ID | FlowiseAI_Flowise_Agentflow_Node_Status_Monitoring |
| Source Repository | FlowiseAI/Flowise |
| Domain | Real-Time Communication, Event-Driven Architecture, Visual Workflow Monitoring |
| Last Updated | 2026-02-12 14:00 GMT |
Overview
Technique for real-time monitoring of individual node execution status during agent flow processing via WebSocket events. When an agent flow executes, each node processes sequentially or in parallel. Real-time status updates are delivered via socket.io WebSocket events. Each update includes the node ID, execution status (running, completed, error), and any error information. The canvas visually reflects these status changes on each node.
Description
During agent flow execution, the server processes nodes according to the DAG topology. As each node begins processing, completes, or encounters an error, the server emits a status event through a socket.io WebSocket connection. The client receives these events and updates the corresponding node's visual state in the ReactFlow canvas in real time.
The status lifecycle for a node:
- running: The node has begun execution. The canvas can show a loading indicator or highlight on this node.
- completed: The node has finished processing successfully. The canvas can show a success indicator.
- error: The node encountered an error during processing. The canvas can show an error indicator along with the error message.
Key characteristics of this pattern:
- Per-node granularity: Status updates are emitted for individual nodes, not for the entire flow. This allows the UI to show precisely which node is currently executing in a multi-node workflow.
- WebSocket-based delivery: Using socket.io for status delivery provides low-latency, push-based updates without requiring the client to poll the server.
- Immutable state update pattern: The node data is updated using the spread operator (
...node.data) to create new data objects, which is compatible with React's state change detection and triggers re-renders. - Status clearing: Before each new execution, all node statuses are cleared via a companion function (
clearAgentflowNodeStatus), ensuring stale status indicators from previous runs do not persist.
Usage
Use this pattern when implementing real-time execution monitoring in a visual agent flow canvas. This is applicable in scenarios where:
- Users need to observe which node in a workflow is currently being executed.
- Visual feedback is required during long-running multi-step agent workflows.
- Error information needs to be displayed on the specific node that failed, aiding in debugging.
Theoretical Basis
This pattern implements an event-driven status propagation pattern using WebSocket pub/sub. The core principles are:
1. Server-Sent Events via WebSocket: The server acts as the event producer, emitting nextAgentFlow events through the socket.io connection during flow execution. The client subscribes to these events and processes them reactively.
2. Unidirectional Data Flow: Status updates flow in one direction: server emits event, client receives event, client updates ReactFlow node state, React re-renders the affected node. This aligns with React's unidirectional data flow philosophy.
3. Event Payload Structure: Each event carries a minimal payload containing:
nodeId: Identifies which node the status applies to.status: The execution state ("running","completed","error").error: Optional error message when status is"error".
4. Optimistic Node Matching: The update function iterates all nodes in the canvas and matches by nodeId. For the matched node, it merges the status into the node's data object. Unmatched nodes are returned unchanged. This O(n) scan is acceptable because:
- Agent flows typically contain tens to low hundreds of nodes.
- Status updates arrive at human-perceptible intervals (seconds, not milliseconds).
5. Integration with React State: Using reactFlowInstance.setNodes() with a mapping function ensures React detects the state change and re-renders only the affected node. The spread operator creates a new data object reference, which is essential for React's shallow comparison.