Real-time Event Streaming

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/convexClient.ts
• src/test-demo-site.ts
• src/engine/parallelRunner.ts
• src/engine/reportGenerator.ts
• plan.md
• README.md

Real-time Event Streaming in SynthCrowd is a critical infrastructure component that enables the live tracking and persistence of autonomous browser agent activities. As agents navigate target websites, they emit granular "step events" that are streamed to a Convex backend. This allows for live dashboard updates, high-fidelity persona evaluation, and post-run analysis.

The system is designed to handle parallel execution of multiple agents, ensuring that every click, scroll, and cognitive state (such as confusion or frustration) is captured and associated with the correct test run and persona.

Sources: plan.md:32-34, README.md:143-150

Architecture and Data Flow

The event streaming architecture follows a producer-consumer pattern where the AgentRunner acts as the producer and the ConvexEventSink acts as the primary interface for data persistence.

Event Lifecycle

1. Generation: The autonomous browser agent performs an action (e.g., clicking a button) using the Browser Use SDK.
2. Capture: The agent records its current URL, the next goal, its evaluation of the previous step, and its emotional state (is_confused, is_frustrated).
3. Transmission: The ConvexEventSink sends this payload to the Convex cloud via a mutation.
4. Persistence: The event is stored in the agent_events table, indexed by run_id and persona_index.
5. Consumption: The live dashboard (frontend) subscribes to these updates, and the ReportGenerator fetches them once the run is complete.

Sources: README.md:143-157, src/lib/convexClient.ts:54-65

Flow Diagram: Agent to Backend

The following diagram illustrates the path of a single step event from the browser environment to the persistent storage layer.

Key Components

ConvexEventSink Class

Located in src/lib/convexClient.ts, this class provides the primary API for interacting with the Convex backend. It abstracts the complexity of managing run IDs and formatting event data.

Method	Purpose
createRun	Initializes a new test run record in the runs table.
pushStepEvent	Streams a single agent action/thought to the agent_events table.
setRunStatus	Updates the final status and conversion rate of a completed run.
fetchEventsForRun	Retrieves all streamed events for analysis and reporting.
storeResult	Persists aggregated metrics and narratives to the results table.

Sources: src/lib/convexClient.ts:13-90

Event Data Structure

The schema for streamed events is optimized for both real-time display and deep UX analysis.

Field	Type	Description
run_id	Id<"runs">	The unique identifier for the current test session.
persona_index	number	Identifies which specific AI agent generated the event.
step_number	number	Incremental counter of the agent's progress.
page_url	string	The current URL the agent is visiting.
is_confused	boolean	Set to true if the agent's internal monologue indicates confusion.
is_frustrated	boolean	Set to true if the agent experiences UI friction.
evaluation	string	The agent's subjective assessment of its last action.

Sources: src/engine/reportGenerator.ts:46-55, src/lib/convexClient.ts:54-65

Integration in Parallel Execution

The runAgentsParallel function manages the concurrent streaming of events from multiple agents. To prevent API rate limiting and ensure orderly data flow, agents are launched in batches with a staggered delay.

Data Aggregation and Analysis

Once the real-time stream concludes, the ReportGenerator fetches the entire event history for a given run_id. It maps events back to their specific persona snapshots to generate a comprehensive friction report.

• Friction Points: Aggregated from events where is_confused or is_frustrated is true.
• Persona Narratives: Synthesized from the narration and evaluation fields of sequential steps.
• Conversion Tracking: Determined by the final event status (e.g., converted vs abandoned).

Sources: src/engine/reportGenerator.ts:114-145, README.md:152-162

Real-time event streaming serves as the telemetry backbone of the SynthCrowd platform, transforming transient browser interactions into durable data for UX optimization. By leveraging Convex's serverless architecture, the system maintains a live link between autonomous agents and the user-facing dashboard.

Sources: plan.md:32-38, README.md:21-29