Run Inspector & Execution UI
Relevant source files
The following files were used as context for generating this wiki page:
The Run Inspector & Execution UI is the primary observability interface within the Flow platform, designed to provide real-time insights into agentic workflows. It enables developers and users to monitor the internal state of the LangGraph pipeline, track tool invocations, and verify knowledge retrieval through detailed citation panels. The system is built to handle high-concurrency streaming data via Server-Sent Events (SSE), ensuring that execution states are reflected in the UI with minimal latency.
This module serves as a bridge between the backend execution engine—which processes tasks through a "planner → worker → synthesizer" pipeline—and the user, offering a transparent view of the agent's "thinking" process. Key functionalities include pipeline visualization, tool execution logging, and a source inspector for RAG (Retrieval-Augmented Generation) validation.
Sources: README.md:1-10, apps/web/src/components/flow/RunInspector.tsx:10-25, AGENTS.md:15-25
Component Architecture
The execution UI is composed of several specialized components that synchronize via a central state store to display the current status of an active agent run.
The Run Inspector
The RunInspector acts as a side-panel container that organizes execution data into three logical tabs: Pipeline, Tools, and Sources. It monitors the activeExecutionId from the global store to determine if an execution is currently in progress.
The inspector includes a "collapsed" state to maximize screen real estate when detailed metrics are not required.
Sources: apps/web/src/components/flow/RunInspector.tsx:43-100
Execution Pipeline Visualization
The Pipeline tab visualizes the progression of the agent through its defined graph nodes. Typical nodes in the Flow pipeline include the planner, worker, synthesizer, and reflector. Each node's state is tracked through a set of statuses: idle, thinking, streaming, done, or error.
| Status | UI Representation | Description |
|---|---|---|
| Thinking | Pulse Animation | The node is processing logic or awaiting an LLM response. |
| Streaming | Pulse Animation | Tokens are actively being emitted from the node. |
| Done | Static Success Color | The node has completed its phase of the execution. |
| Error | Static Error Color | The node encountered a failure during processing. |
Sources: apps/web/src/components/flow/RunInspector.tsx:110-150, README.md:85-90
Data Flow & Integration
The Execution UI relies on a combination of persistent storage in PostgreSQL and real-time streaming updates.
Streaming via SSE
Flow utilizes Server-Sent Events (SSE) to stream execution events. Because standard browser EventSource implementations do not support custom headers, authentication tokens are passed via query strings during the connection phase.
Sources: AGENTS.md:23-28, README.md:95-105
Observability & Tool Logging
The ToolCallLog component captures every external interaction initiated by the agent. This includes knowledge retrieval (pgvector/Qdrant), sandbox code execution, and long-term memory recalls. Each log entry provides transparency into the arguments passed to the tool and the resulting output.
Sources: apps/web/src/components/flow/RunInspector.tsx:155-165, apps/web/src/components/flow/ToolCallLog.tsx
Knowledge Retrieval & Citations
A critical feature of the Execution UI is the validation of Retrieval-Augmented Generation (RAG). The CitationsPanel displays the specific document chunks used by the agent to generate its response.
- Source Mapping: The synthesizer emits a
citationsSSE frame containingsource_id,title, andchunk_index. - Inline Markers: The frontend renders markers like
[1]or[2]in the streamed text. - Source Inspection: Clicking a citation allows the user to view the exact text snippet stored in the
pgvectoror Qdrant database.
Sources: README.md:90-95, apps/web/src/components/flow/RunInspector.tsx:165-175, apps/web/src/components/flow/CitationsPanel.tsx
Knowledge Graph Integration
Executions are not ephemeral; they are mapped into a global Knowledge Graph. The system uses semantic clustering and PageRank to relate executions to other entities like agents, skills, and topics.
The GraphPage allows users to explore these relationships, where "Execution" nodes are connected to the "Agent" that ran them and the "Skills" utilized during the run.
Sources: apps/web/src/app/(app)/graph/page.tsx:25-50, apps/web/src/app/(app)/dashboard/page.tsx:120-150
Conclusion
The Run Inspector & Execution UI provides the necessary transparency for building and debugging complex agentic workflows in Flow. By combining real-time node tracking, detailed tool logs, and verifiable RAG citations, it ensures that agent behavior is observable and grounded in provided knowledge sources.