Agent & Parallel Runner

Relevant source files

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

• src/engine/agentRunner.ts
• src/engine/parallelRunner.ts
• plan.md
• README.md
• src/test-parallel.ts
• src/engine/optimizationLoop.ts

The Agent & Parallel Runner system is the core execution engine of the SynthCrowd platform. It is responsible for transforming static persona configurations into active, autonomous browser agents that navigate target websites to test conversion goals. By utilizing the Browser Use SDK and Claude LLM with vision capabilities, the system simulates realistic user behavior, including frustration, confusion, and methodical research.

To handle scale, the system implements a parallel execution architecture that manages agent lifecycles in staggered batches. This ensures high throughput while respecting API rate limits and providing real-time telemetry to the frontend via Convex. Sources: README.md:128-150, plan.md:16-30

Execution Architecture

The execution flow starts with a compiled persona and ends with a detailed trace of the agent's journey. The system uses a multi-layered approach to run these agents safely and efficiently.

Sources: plan.md:21-30, src/engine/parallelRunner.ts:63-100

Parallel Runner Logic

The ParallelRunner manages the complexity of running multiple agents simultaneously. It utilizes a batch-based approach where agents are grouped and launched with a configurable stagger delay to prevent simultaneous spikes in resource usage.

Component	Description
Batching	Groups agents (default size 5) to control concurrency.
Staggering	Introduces a delay (e.g., 2000ms) between agent launches within a batch.
Sandbox Isolation	Uses Daytona to provide unique, isolated environments for each agent.
Progress Tracking	Provides callbacks (on_progress) to track completed, failed, and remaining agents.

Sources: src/engine/parallelRunner.ts:102-120, plan.md:126-127, src/engine/optimizationLoop.ts:162-178

Individual Agent Lifecycle

Each agent is an instance of the runSingleAgent function, which initializes the Browser Use SDK with specific system prompts derived from the persona's traits.

Dynamic Step Calculation

Agents do not have a fixed step limit. Instead, the max_steps for an agent is dynamically calculated based on the persona's patience trait. An impatient persona (low patience) will have fewer steps before abandoning, while a patient one (high patience) will spend more time troubleshooting.

• Formula: max_steps = Math.round(15 + 35 * config.patience)

Sources: plan.md:104-106, src/engine/parallelRunner.ts:77-78

The Browsing Loop

The sequence below demonstrates how a single agent interacts with the target site and the telemetry system:

Sources: src/engine/agentRunner.ts:1-50, README.md:144-150

Configuration and Options

The ParallelRunnerOptions interface defines how the execution engine should behave during a run.

export interface ParallelRunnerOptions {
  batch_size?: number;          // Number of agents per batch (default 5)
  stagger_delay_ms?: number;    // Ms to wait between agent starts
  max_steps?: number;           // Hard limit on agent actions
  convex_sink?: ConvexEventSink; // Telemetry destination
  run_id?: Id<"runs">;          // Run identifier for database
  on_step?: (event: AgentStepEvent) => void;
  on_progress?: (progress: BatchProgress) => void;
}

Sources: src/engine/parallelRunner.ts:18-28

Telemetry and Fidelity

As agents run, they produce AgentStepEvent objects. These contain:

• Evaluation: The agent's internal monologue and reasoning.
• Status: Current state (e.g., running, success, error).
• Is Confused/Frustrated: Boolean flags triggered by LLM sentiment.

After a run, the system executes a Fidelity Eval to check if the agent actually followed its assigned persona rules (e.g., "Did the 'Grandma' persona actually get confused by the jargon as instructed?"). Sources: src/engine/parallelRunner.ts:85-95, src/test-parallel.ts:40-60

Error Handling and Resilience

The ParallelRunner is designed to be "fail-soft." If a single agent fails due to an LLM error or timeout, it is caught within runAgentWithHooks, logged as an error status, and the rest of the batch continues.

1. Sandbox Cleanup: Regardless of success or failure, the system ensures destroySandbox is called to free resources.
2. Status Reporting: Failures are reported back to the BatchProgress object and the Convex sink so the UI can reflect the error state.
3. Result Aggregation: All results, including errors with their associated stack traces or LLM messages, are collected in the allResults array.

Sources: src/engine/parallelRunner.ts:100-115, src/engine/optimizationLoop.ts:185-195

Summary

The Agent & Parallel Runner provides the necessary infrastructure to scale synthetic user testing. By combining batch management, sandboxed execution, and real-time telemetry, it allows SynthCrowd to simulate hundreds of diverse browsing sessions while providing granular data on exactly where and why users fail to convert.