Struct BrowserAgentBuilder 

pub struct BrowserAgentBuilder<P: LlmProvider> {
    pub distill: DistillConfig,
    pub settle: SettleConfig,
    pub confirm: ConfirmPolicy,
    /* private fields */
}

Fluent builder assembling a browser AgentRunner from the harness pieces.

Fields

distill: DistillConfig

Distillation tuning (exposed for the caller’s observe step).

settle: SettleConfig

Settle tuning (exposed for the caller’s settle step).

confirm: ConfirmPolicy

Destructive-action policy (exposed for the caller’s confirm step).

Implementations

impl<P: LlmProvider> BrowserAgentBuilder<P>

pub fn new(provider: Arc<P>) -> Self

Start a builder for provider. The allowlist is empty (deny-all) until hosts are added — navigation is refused until the operator opts in.

pub fn on_approval(self, on_approval: Arc<OnApproval>) -> Self

Set the human-confirmation callback for destructive actions. When set, a mutating click whose target label is confidently classified as consequential/irreversible (per Self::confirm) is routed through on_approval before executing; a denial aborts the action. Off by default. See ConfirmActionTool.

pub fn goal(self, goal: GoalCondition) -> Self

Set a persistent GoalCondition: an INDEPENDENT judge decides — from the page snapshots in the transcript — whether the objective is met before the agent is allowed to finish, and otherwise re-prompts it to keep going (bounded by the goal’s max_continuations and the agent’s max_turns). This is the natural way to express “navigate until the page shows X”: the judge verifies the real page state rather than trusting the agent’s “I’m done”.

pub fn allow_host(self, host: impl Into<String>) -> Self

Allow navigation to host (and its subdomains).

pub fn allow_hosts( self, hosts: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Allow navigation to several hosts at once.

pub fn guardrail(self, guard: Arc<dyn Guardrail>) -> Self

Add an extra guardrail (composed after the domain allowlist).

pub fn system_prompt(self, prompt: impl Into<String>) -> Self

Override the default BROWSER_SYSTEM_PROMPT.

pub fn name(self, name: impl Into<String>) -> Self

Set the agent name.

pub fn max_turns(self, max_turns: usize) -> Self

Bound the ReAct loop: the agent stops after max_turns LLM turns. A browser agent should always cap this — an unbounded loop on a live site is a cost and safety hazard. Left unset, the underlying AgentRunner default applies.

pub fn chrome_executable(self, path: impl Into<String>) -> Self

Point chrome-devtools-mcp at a specific Chrome binary (passed as --executable-path). Set this when Chrome auto-detection fails (e.g. some CI/sandbox environments) or Chrome is installed at a non-standard path. Only affects Self::connect; ignored by Self::build_with_tools.

pub fn on_event(self, callback: Arc<OnEvent>) -> Self

Attach a lifecycle-event callback, forwarded to the underlying AgentRunner. Lets callers observe turns/tool-calls/usage — e.g. the benchmark uses it to capture a trace even when a task fails on max-turns.

pub fn tools_allow( self, names: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Restrict the agent to only the named tools — the single biggest input- token lever, since every tool definition is re-sent on every turn and the chrome-devtools preset ships ~26 of them. Pass the handful a task needs (e.g. navigate_page, take_snapshot, click, fill, wait_for). Empty (default) keeps all tools. Unknown names are simply absent.

pub fn max_identical_tool_calls(self, n: u32) -> Self

Break dithering loops: after n identical consecutive tool-call batches, the runner injects a “you’re repeating, stop and finish if done” warning and continues (it does NOT abort). This is the framework’s anti-loop recovery; for a browser agent it cures the dominant failure mode — re-snapshotting or re-wait_for-ing the same thing without making progress until the turn budget is exhausted. None (default) disables it.

pub fn session_prune(self, config: SessionPruneConfig) -> Self

Prune OLD tool results (stale page snapshots, whose uids are dead after a navigation anyway) to a head+tail summary, keeping the task and most recent results at full fidelity. The dominant token cost on long multi-page runs is re-sending every past snapshot each turn; this bounds it. Safe for extraction tasks — the reported value lives in a recent (preserved) snapshot. None (default) keeps full history.

pub fn distill_enabled(self, enabled: bool) -> Self

Enable/disable snapshot distillation of tool output (default: enabled). Distillation drops redundant echoed StaticText while preserving every interactive uid, shrinking what re-enters context each turn.

pub fn distill_config(self, cfg: DistillConfig) -> Self

Tune snapshot distillation.

pub fn settle_config(self, cfg: SettleConfig) -> Self

Tune settle.

pub fn confirm_policy(self, policy: ConfirmPolicy) -> Self

Tune the destructive-action policy.

pub fn build_with_tools( self, raw_tools: Vec<Arc<dyn Tool>>, ) -> Result<AgentRunner<P>, Error>

Assemble an AgentRunner from a caller-provided tool set (typically the chrome-devtools preset’s tools, but any Vec<Arc<dyn Tool>> works — this is what makes the assembly unit-testable without a browser). Wraps the tools for reliability and installs the guardrail stack + system prompt.

pub async fn connect(self) -> Result<AgentRunner<P>, Error>

Connect the bundled chrome-devtools MCP preset (spawns headless Chrome), then assemble the agent. The thin async shell over Self::build_with_tools; covered by a #[ignore] live test since it needs a real browser. If a chrome_executable was set, it is forwarded as --executable-path.