Browser Use SDK Details

The Browser Use SDK serves as the core execution engine for synthetic agents within the Abee platform. It enables autonomous browser agents to navigate target websites, interact with UI elements, and execute complex workflows based on high-level goals and structured persona configurations. The integration facilitates real-time event streaming and behavioral simulation by combining LLM-driven reasoning (Claude) with a programmable browser automation layer.

Sources: README.md:121-125, src/engine/agentRunner.ts

Core Architecture and Integration

The integration is centered around the BrowserUse client, which manages the lifecycle of autonomous agents. Each agent is initialized with a specific CompiledPersona, a target URL, and a conversion goal (CTA). The SDK allows agents to operate with vision-augmented reasoning, enabling them to "see" the page and make decisions based on both visual layout and underlying DOM structure.

The diagram above illustrates the flow from persona compilation to browser execution and eventual data persistence.
Sources: src/engine/agentRunner.ts, README.md:14-25

Key Components

Sources: src/engine/agentRunner.ts:1-25, src/engine/promptCompiler.ts:403-407

Agent Lifecycle and Execution Logic

Agents follow a strictly defined execution loop. Upon launching, an agent opens the target_url and attempts to achieve the defined goal within a maximum number of steps. The step count is often dynamic, scaled by the persona's patience trait.

Step Execution Flow

For every step in the browser session, the SDK captures a detailed state:

1. Observation: The agent observes the current URL and page content.
2. Reasoning: Using the system_prompt, the agent evaluates the previous action and determines the next goal.
3. Action: The agent performs an action (click, scroll, type, etc.) to move closer to the CTA.
4. Narration: The agent generates an internal monologue explaining its thought process.

This sequence diagram details the interaction between the runner, the SDK, and the LLM during the navigation loop.
Sources: src/engine/agentRunner.ts, README.md:112-118

Persona Fidelity and Behavioral Constraints

A critical aspect of the Browser Use integration is ensuring agents adhere to the behavioral rules defined during the Prompt Compiler phase. The SDK does not just perform automated clicks; it simulates human-like limitations and preferences.

Dynamic Behavioral Constraints

The agentRunner and promptCompiler work together to inject traits into the SDK's execution context:

• Patience Scaling: max_steps is calculated as Math.round(15 + 35 * config.patience), ensuring impatient personas abandon the site sooner.
• Rule Enforcement: Behavioral rules (e.g., "You do NOT understand hamburger menus") are injected into the system prompt, forcing the Browser Use agent to struggle or succeed based on its persona.
• Fidelity Evaluation: After execution, the evaluatePersonaFidelity function checks if the agent's actions in the SDK match the expected behavioral traits (e.g., checking if a "cautious" persona actually visited the pricing page).

Sources: src/engine/optimizationLoop.ts:32-34, src/engine/promptCompiler.ts:435-442, src/test-agent-techbro.ts:60-90

Event Streaming and Persistence

As the Browser Use agent navigates, it streams AgentEvent objects. These events are the raw data for the platform's analysis engine.

Data Model: AgentEvent

Each step recorded by the SDK includes the following fields:

• step_number: The current iteration of the loop.
• page_url: The URL where the action took place.
• evaluation: The agent's assessment of whether the last action worked.
• memory: The agent's persistent state across steps.
• next_goal: What the agent intends to do next.

Sources: src/engine/agentRunner.ts, README.md:104-108, src/engine/reportGenerator.ts:40-49

Integration with Convex

The agentRunner optionally accepts a ConvexEventSink. If provided, every step recorded by the SDK is pushed to a real-time database in the agent_events table, allowing for live dashboard monitoring.

Conclusion

The Browser Use SDK integration provides the "muscle" for the Abee platform, turning static persona configurations into active, autonomous participants in a user testing environment. By mapping internal traits to browser-level constraints and step-by-step narration, the system captures not just whether a user converts, but the specific friction points encountered during the journey.