Graph & Topology Visualizations
Relevant source files
The following files were used as context for generating this wiki page:
Graph and Topology Visualizations in the Flow project provide a multi-layered interface for understanding agent behaviors, knowledge structures, and execution pipelines. These visualizations range from high-level agent logic flows to granular, interconnected knowledge nodes derived from document retrieval and tool executions.
The system utilizes specialized canvases to represent different conceptual levels: the Knowledge Graph for semantic relationships and entity mapping, the Agent Topology for structural logic definitions, and the Flow Graph for real-time execution monitoring.
Knowledge Graph Architecture
The Knowledge Graph is a high-dimensional representation of the workspace's cognitive state. It maps various entity types—including agents, skills, execution traces, and knowledge concepts—into a unified 2D force-directed layout.
Data Structure and Entity Types
The graph is composed of KGNode and KGEdge objects. Nodes are categorized by their role within the system, such as agent, skill, execution, or concept. Each node carries metadata, PageRank scores for importance, and cluster IDs for semantic grouping.
| Node Type | Description | Primary Color |
|---|---|---|
agent | Registered AI agents within the workspace | #6366f1 |
skill | Specific capabilities assigned to agents | #5eead4 |
execution | History of specific agent runs | #f59e0b |
trace | Logical path taken during an execution | #38bdf8 |
concept | Extracted semantic entities from documents | #94a3b8 |
Sources: apps/web/src/app/(app)/graph/page.tsx:25-33, apps/web/src/components/kg/KnowledgeGraphCanvas.tsx:10-23
Force-Directed Visualization
The visualization is implemented using a 2D force-graph engine that calculates node positions based on physical simulations (charge, link strength, and centering).
The engine uses specific physics parameters to maintain a tight cluster:
- Charge Strength: Set to
-180to prevent excessive overlap. - Link Distance: Defaulted to
50for local connectivity. - Velocity Decay: Set to
0.4for smooth simulation settling.
Sources: apps/web/src/components/kg/KnowledgeGraphCanvas.tsx:125-144, apps/web/src/app/(app)/graph/page.tsx:75-84
Agent Topology and Pipeline Maps
Agent Topology Visualizations represent the static "wiring" of an agent's logic. These are used to inspect how different nodes (like planners, workers, and synthesizers) are connected.
Topology Catalog
The backend provides a graph-catalog that defines the structure for different graph templates, such as the agentic_rag pipeline. These topologies distinguish between fixed and conditional edges.
Figure: The structural layout of the Agentic RAG retrieval subgraph.
Sources: services/api/flow/interfaces/http/routes/meta.py:101-131, apps/web/src/components/agents/AgentTopologyCanvas.tsx:43-55
Rendering Components
Topology is rendered using React Flow-style canvases. AgentTopologyCanvas transforms backend CatalogNode and CatalogEdge data into interactive flow elements. Conditional edges are visually distinguished with animated dashed lines.
Sources: apps/web/src/components/agents/AgentTopologyCanvas.tsx:15-41
Real-time Execution Flow
The FlowGraph component provides a specialized visualization for active agent runs. Unlike the static topology or the sprawling Knowledge Graph, the Flow Graph focuses on the state of a single execution pipeline.
Execution States
Nodes in the flow graph change appearance based on their current status in the useStore state:
| Status | Visual Indicator | Meaning |
|---|---|---|
thinking | Violet Glow / Ping Animation | Node is processing logic |
streaming | Active Arc Gradient / Animated Dot | Node is generating output |
done | Green Stroke | Step completed successfully |
error | Red Glow | Execution failed at this node |
Sources: apps/web/src/components/flow/FlowGraph.tsx:32-47, apps/web/src/components/flow/FlowGraph.tsx:109-122
Sequential Flow Logic
The execution moves through a predefined path: Planner → Worker → Synthesizer → Reflector. Active transitions between these nodes are visualized using animated dots "riding" the arcs.
Integration and Data Synchronization
Visualizations are kept in sync with the backend through specific API routes and automated synchronization triggers.
Entity Synchronization
The system includes a synchronization mechanism to pull agents, skills, and genomes into the Knowledge Graph. This ensures that structural changes made in the management UI are reflected in the visual map.
- Endpoint:
POST /api/v1/kg/sync-entities - Trigger: Automatic on first load of the graph page or manual via the "Sync" button.
Sources: apps/web/src/app/(app)/graph/page.tsx:90-108
Metadata Metadata Exposure
Visualizations leverage the meta router to understand the underlying database schema and available graph templates. This metadata is used to build the "Database Overview" and "Graph Catalog" sections of the dashboard.
Sources: services/api/flow/interfaces/http/routes/meta.py:14-55
Summary
The Graph & Topology Visualizations serve as the primary diagnostic and exploratory interface for the Flow platform. By combining real-time execution feedback with long-term semantic mapping, the system allows developers to trace agent logic from high-level structural design down to individual document citations.