Browser-Use 浏览器代理

WHENWhen designing or coding any browser-use workflow that touches admin tools, file management, settings pages, or any UI where confirm dialogs may guard irreversible operations

ACTIONEither (a) register a custom @tools.action that intercepts dialogs BEFORE popups_watchdog dispatches them (override dispatch order); (b) write a custom watchdog subclassing BaseWatchdog that LISTENS_TO Page.javascriptDialogOpening and overrides should_accept logic with semantic dialog-text classification; or (c) explicitly tell the LLM in the system prompt extension that destructive operations require a separate user-confirmation step recorded in todo.md before any click that could surface a confirm dialog. Document this as a hard prerequisite in your skill — host AI cannot rely on the framework to refuse destructive confirms.

CONSEQUENCEundefined behavior

WHENWhen constructing an Agent and passing the sensitive_data parameter (passwords, API keys, PII, financial credentials)

ACTIONWrap Agent construction in your own factory that explicitly raises ValueError if sensitive_data is provided AND browser_profile.allowed_domains is empty/None. Recommended pattern: def make_agent(task, llm, sensitive_data, allowed_domains): assert allowed_domains, 'allowed_domains REQUIRED when sensitive_data set'; return Agent(task=task, llm=llm, sensitive_data=sensitive_data, browser=Browser(allowed_domains=allowed_domains)). Treat the framework's warning as documentation, not as protection.

CONSEQUENCEundefined behavior

WHENWhen designing an agent task targeting a SPA — single-page-application, React/Vue/Angular routing, or any site with frequent client-side DOM rerenders that do not change the URL

ACTIONSet max_actions_per_step=1 for SPA-heavy targets so each LLM step is forced to re-read state before the next click. Alternatively, write a custom Layer-3 guard: subclass BaseWatchdog, LISTENS_TO ActionExecutedEvent, run a CDP DOMSnapshot.captureSnapshot pre/post and compare a hash of the interactive subtree; emit a synthetic PageChangedEvent on diff so multi_act breaks. Do NOT trust the default Layer-2 guard for SPA flows.

CONSEQUENCEundefined behavior