Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
Add WebSocket reconnection for remote browser CDP connections
Saurav Pandaabd0326a6f9b
diff --git a/browser_use/agent/service.py b/browser_use/agent/service.pyindex 04cdfd4ea..e6a2fbee6 100644--- a/browser_use/agent/service.py+++ b/browser_use/agent/service.py@@ -1222,12 +1222,28 @@ class Agent(Generic[Context, AgentStructuredOutput]):self.logger.warning(f'{error_msg}')return- # Handle browser closed/disconnected errors - stop immediately instead of retrying- if self._is_browser_closed_error(error):- self.logger.warning(f'π Browser closed or disconnected: {error}')- self.state.stopped = True- self._external_pause_event.set()- return+ # Handle browser closed/disconnected errors+ if self._is_connection_like_error(error):+ # If reconnection is in progress, wait for it instead of stopping+ if self.browser_session.is_reconnecting:+ self.logger.warning(f'π Connection error during reconnection, waiting for reconnect: {error}')+ try:+ await asyncio.wait_for(self.browser_session._reconnect_event.wait(), timeout=20.0)+ except TimeoutError:+ pass++ # Check if reconnection succeeded+ if self.browser_session.is_cdp_connected:+ self.logger.info('π Reconnection succeeded, retrying step...')+ self.state.last_result = [ActionResult(error=f'Connection lost and recovered: {error}')]+ return++ # Not reconnecting or reconnection failed β check if truly terminal+ if self._is_browser_closed_error(error):+ self.logger.warning(f'π Browser closed or disconnected: {error}')+ self.state.stopped = True+ self._external_pause_event.set()+ return# Handle all other exceptionsinclude_trace = self.logger.isEnabledFor(logging.DEBUG)@@ -1251,14 +1267,35 @@ class Agent(Generic[Context, AgentStructuredOutput]):self.state.last_result = [ActionResult(error=error_msg)]return None+ def _is_connection_like_error(self, error: Exception) -> bool:+ """Check if the error looks like a CDP/WebSocket connection failure.++ Unlike _is_browser_closed_error(), this does NOT check if the CDP client is None+ or if reconnection is in progress β it purely looks at the error signature.+ """+ error_str = str(error).lower()+ return (+ isinstance(error, ConnectionError)+ or 'websocket connection closed' in error_str+ or 'connection closed' in error_str+ or 'browser has been closed' in error_str+ or 'browser closed' in error_str+ or 'no browser' in error_str+ )+def _is_browser_closed_error(self, error: Exception) -> bool:"""Check if the browser has been closed or disconnected.Only returns True when the error itself is a CDP/WebSocket connection failure- AND the CDP client is gone. Avoids false positives on unrelated errors- (element not found, timeouts, parse errors) that happen to coincide with- a transient None state during reconnects or resets.+ AND the CDP client is gone AND we're not actively reconnecting.+ Avoids false positives on unrelated errors (element not found, timeouts,+ parse errors) that happen to coincide with a transient None state during+ reconnects or resets."""+ # During reconnection, don't treat connection errors as terminal+ if self.browser_session.is_reconnecting:+ return False+error_str = str(error).lower()is_connection_error = (isinstance(error, ConnectionError)diff --git a/browser_use/browser/events.py b/browser_use/browser/events.pyindex afc492de3..723c51d92 100644--- a/browser_use/browser/events.py+++ b/browser_use/browser/events.py@@ -471,6 +471,26 @@ class BrowserErrorEvent(BaseEvent):event_timeout: float | None = Field(default_factory=lambda: _get_timeout('TIMEOUT_BrowserErrorEvent', 30.0)) # seconds+class BrowserReconnectingEvent(BaseEvent):+ """WebSocket reconnection attempt is starting."""++ cdp_url: str+ attempt: int+ max_attempts: int++ event_timeout: float | None = Field(default_factory=lambda: _get_timeout('TIMEOUT_BrowserReconnectingEvent', 30.0)) # seconds+++class BrowserReconnectedEvent(BaseEvent):+ """WebSocket reconnection succeeded."""++ cdp_url: str+ attempt: int+ downtime_seconds: float++ event_timeout: float | None = Field(default_factory=lambda: _get_timeout('TIMEOUT_BrowserReconnectedEvent', 30.0)) # seconds++# ============================================================================# Storage State Events# ============================================================================diff --git a/browser_use/browser/session.py b/browser_use/browser/session.pyindex 5fd6f596e..ab2a3ae8c 100644--- a/browser_use/browser/session.py+++ b/browser_use/browser/session.py@@ -2,6 +2,7 @@import asyncioimport logging+import timefrom functools import cached_propertyfrom pathlib import Pathfrom typing import TYPE_CHECKING, Any, Literal, Self, Union, cast, overload@@ -28,6 +29,8 @@ from browser_use.browser.events import (BrowserErrorEvent,BrowserLaunchEvent,BrowserLaunchResult,+ BrowserReconnectedEvent,+ BrowserReconnectingEvent,BrowserStartEvent,BrowserStateRequestEvent,BrowserStopEvent,@@ -458,6 +461,11 @@ class BrowserSession(BaseModel):except Exception:return False+ @property+ def is_reconnecting(self) -> bool:+ """Whether a WebSocket reconnection attempt is currently in progress."""+ return self._reconnecting+@propertydef cloud_browser(self) -> bool:"""Whether to use cloud browser service from browser profile."""@@ -508,6 +516,13 @@ class BrowserSession(BaseModel):_cloud_browser_client: CloudBrowserClient = PrivateAttr(default_factory=lambda: CloudBrowserClient())_demo_mode: 'DemoMode | None' = PrivateAttr(default=None)+ # WebSocket reconnection state+ _reconnecting: bool = PrivateAttr(default=False)+ _reconnect_event: asyncio.Event = PrivateAttr(default_factory=asyncio.Event)+ _reconnect_lock: asyncio.Lock = PrivateAttr(default_factory=asyncio.Lock)+ _reconnect_task: asyncio.Task | None = PrivateAttr(default=None)+ _intentional_stop: bool = PrivateAttr(default=False)+_logger: Any = PrivateAttr(default=None)@property@@ -544,6 +559,15 @@ class BrowserSession(BaseModel):async def reset(self) -> None:"""Clear all cached CDP sessions with proper cleanup."""+ # Suppress auto-reconnect callback during teardown+ self._intentional_stop = True+ # Cancel any in-flight reconnection task+ if self._reconnect_task and not self._reconnect_task.done():+ self._reconnect_task.cancel()+ self._reconnect_task = None+ self._reconnecting = False+ self._reconnect_event.set() # unblock any waiters+cdp_status = 'connected' if self._cdp_client_root else 'not connected'session_mgr_status = 'exists' if self.session_manager else 'None'self.logger.debug(@@ -588,11 +612,15 @@ class BrowserSession(BaseModel):self._demo_mode.reset()self._demo_mode = None+ self._intentional_stop = Falseself.logger.info('β Browser session reset complete')def model_post_init(self, __context) -> None:"""Register event handlers after model initialization."""self._connection_lock = asyncio.Lock()+ # Initialize reconnect event as set (no reconnection pending)+ self._reconnect_event = asyncio.Event()+ self._reconnect_event.set()# Check if handlers are already registered to prevent duplicatesfrom browser_use.browser.watchdog_base import BaseWatchdog@@ -627,6 +655,7 @@ class BrowserSession(BaseModel):async def kill(self) -> None:"""Kill the browser session and reset all state."""+ self._intentional_stop = Trueself.logger.debug('π kill() called - stopping browser with force=True and resetting state')# First save storage state while CDP is still connected@@ -650,6 +679,7 @@ class BrowserSession(BaseModel):This clears event buses and cached state but keeps the browser alive.Useful when you want to clean up resources but plan to reconnect later."""+ self._intentional_stop = Trueself.logger.debug('βΈοΈ stop() called - stopping browser gracefully (force=False) and resetting state')# First save storage state while CDP is still connected@@ -1732,6 +1762,10 @@ class BrowserSession(BaseModel):# Enable proxy authentication handling if configuredawait self._setup_proxy_auth()+ # Attach WS drop detection callback for auto-reconnection+ self._intentional_stop = False+ self._attach_ws_drop_callback()+# Verify the target is workingif self.agent_focus_target_id:target = self.session_manager.get_target(self.agent_focus_target_id)@@ -1937,6 +1971,179 @@ class BrowserSession(BaseModel):except Exception as e:self.logger.debug(f'Skipping proxy auth setup: {type(e).__name__}: {e}')+ async def reconnect(self) -> None:+ """Re-establish the CDP WebSocket connection to an already-running browser.++ This is a lightweight reconnection that:+ 1. Stops the old CDPClient (WS already dead, just clean state)+ 2. Clears SessionManager (all CDP sessions are invalid post-disconnect)+ 3. Creates a new CDPClient with the same cdp_url+ 4. Re-initializes SessionManager and re-enables autoAttach+ 5. Re-discovers page targets and restores agent focus+ 6. Re-enables proxy auth if configured+ """+ assert self.cdp_url, 'Cannot reconnect without a CDP URL'++ old_focus_target_id = self.agent_focus_target_id++ # 1. Stop old CDPClient (WS is already dead, this just cleans internal state)+ if self._cdp_client_root:+ try:+ await self._cdp_client_root.stop()+ except Exception as e:+ self.logger.debug(f'Error stopping old CDP client during reconnect: {e}')+ self._cdp_client_root = None++ # 2. Clear SessionManager (all sessions are stale)+ if self.session_manager:+ try:+ await self.session_manager.clear()+ except Exception as e:+ self.logger.debug(f'Error clearing SessionManager during reconnect: {e}')+ self.session_manager = None++ self.agent_focus_target_id = None++ # 3. Create new CDPClient with the same cdp_url+ headers = getattr(self.browser_profile, 'headers', None)+ self._cdp_client_root = CDPClient(+ self.cdp_url,+ additional_headers=headers,+ max_ws_frame_size=200 * 1024 * 1024,+ )+ await self._cdp_client_root.start()++ # 4. Re-initialize SessionManager+ from browser_use.browser.session_manager import SessionManager++ self.session_manager = SessionManager(self)+ await self.session_manager.start_monitoring()++ # 5. Re-enable autoAttach+ await self._cdp_client_root.send.Target.setAutoAttach(+ params={'autoAttach': True, 'waitForDebuggerOnStart': False, 'flatten': True}+ )++ # 6. Re-discover page targets and restore focus+ page_targets = self.session_manager.get_all_page_targets()++ # Prefer the old focus target if it still exists+ restored = False+ if old_focus_target_id:+ for target in page_targets:+ if target.target_id == old_focus_target_id:+ await self.get_or_create_cdp_session(old_focus_target_id, focus=True)+ restored = True+ self.logger.debug(f'π Restored agent focus to previous target {old_focus_target_id[:8]}...')+ break++ if not restored:+ if page_targets:+ fallback_id = page_targets[0].target_id+ await self.get_or_create_cdp_session(fallback_id, focus=True)+ self.logger.debug(f'π Agent focus set to fallback target {fallback_id[:8]}...')+ else:+ # No pages exist β create one+ new_target = await self._cdp_client_root.send.Target.createTarget(params={'url': 'about:blank'})+ target_id = new_target['targetId']+ await self.get_or_create_cdp_session(target_id, focus=True)+ self.logger.debug(f'π Created new blank page during reconnect: {target_id[:8]}...')++ # 7. Re-enable proxy auth if configured+ await self._setup_proxy_auth()++ # 8. Attach the WS drop detection callback to the new client+ self._attach_ws_drop_callback()++ async def _auto_reconnect(self, max_attempts: int = 3) -> None:+ """Attempt to reconnect with exponential backoff.++ Dispatches BrowserReconnectingEvent before each attempt and+ BrowserReconnectedEvent on success.+ """+ async with self._reconnect_lock:+ if self._reconnecting:+ return # already in progress from another caller+ self._reconnecting = True+ self._reconnect_event.clear()++ start_time = time.time()+ delays = [1.0, 2.0, 4.0]++ try:+ for attempt in range(1, max_attempts + 1):+ self.event_bus.dispatch(+ BrowserReconnectingEvent(+ cdp_url=self.cdp_url or '',+ attempt=attempt,+ max_attempts=max_attempts,+ )+ )+ self.logger.warning(f'π WebSocket reconnection attempt {attempt}/{max_attempts}...')++ try:+ await asyncio.wait_for(self.reconnect(), timeout=15.0)+ # Success+ downtime = time.time() - start_time+ self.event_bus.dispatch(+ BrowserReconnectedEvent(+ cdp_url=self.cdp_url or '',+ attempt=attempt,+ downtime_seconds=downtime,+ )+ )+ self.logger.info(f'π WebSocket reconnected after {downtime:.1f}s (attempt {attempt})')+ return+ except Exception as e:+ self.logger.warning(f'π Reconnection attempt {attempt} failed: {type(e).__name__}: {e}')+ if attempt < max_attempts:+ delay = delays[attempt - 1] if attempt - 1 < len(delays) else delays[-1]+ await asyncio.sleep(delay)++ # All attempts exhausted+ self.logger.error(f'π All {max_attempts} reconnection attempts failed')+ self.event_bus.dispatch(+ BrowserErrorEvent(+ error_type='ReconnectionFailed',+ message=f'Failed to reconnect after {max_attempts} attempts ({time.time() - start_time:.1f}s)',+ details={'cdp_url': self.cdp_url or '', 'max_attempts': max_attempts},+ )+ )+ finally:+ self._reconnecting = False+ self._reconnect_event.set() # wake up all waiters regardless of outcome++ def _attach_ws_drop_callback(self) -> None:+ """Attach a done callback to the CDPClient's message handler task to detect WS drops."""+ if not self._cdp_client_root or not hasattr(self._cdp_client_root, '_message_handler_task'):+ return++ task = self._cdp_client_root._message_handler_task+ if task is None or task.done():+ return++ def _on_message_handler_done(fut: asyncio.Future) -> None:+ # Guard: skip if intentionally stopped, already reconnecting, or no cdp_url+ if self._intentional_stop or self._reconnecting or not self.cdp_url:+ return++ # The message handler task exiting means the WS connection dropped+ exc = fut.exception() if not fut.cancelled() else None+ self.logger.warning(+ f'π CDP WebSocket message handler exited unexpectedly'+ f'{f": {type(exc).__name__}: {exc}" if exc else " (connection closed)"}'+ )++ # Fire auto-reconnect as an asyncio task+ try:+ loop = asyncio.get_running_loop()+ self._reconnect_task = loop.create_task(self._auto_reconnect())+ except RuntimeError:+ # No running event loop β can't reconnect+ self.logger.error('π No event loop available for auto-reconnect')++ task.add_done_callback(_on_message_handler_done)+async def get_tabs(self) -> list[TabInfo]:"""Get information about all open tabs using cached target data."""tabs = []diff --git a/browser_use/browser/watchdog_base.py b/browser_use/browser/watchdog_base.pyindex ce82df502..356bcf5c4 100644--- a/browser_use/browser/watchdog_base.py+++ b/browser_use/browser/watchdog_base.py@@ -1,5 +1,6 @@"""Base watchdog class for browser monitoring components."""+import asyncioimport inspectimport timefrom collections.abc import Iterable@@ -82,6 +83,8 @@ class BaseWatchdog(BaseModel):'BrowserLaunchEvent','BrowserErrorEvent','BrowserKillEvent',+ 'BrowserReconnectingEvent',+ 'BrowserReconnectedEvent',})@@ -93,10 +96,29 @@ class BaseWatchdog(BaseModel):# (prevents handlers from hanging on broken connections until timeout)# Lifecycle events are exempt β they manage browser start/stopif event.event_type not in LIFECYCLE_EVENT_NAMES and not browser_session.is_cdp_connected:- browser_session.logger.debug(- f'π [{watchdog_class_name}.{actual_handler.__name__}] β‘ Skipped β CDP not connected'- )- return None+ # If reconnection is in progress, wait for it instead of silently skipping+ if browser_session.is_reconnecting:+ browser_session.logger.debug(+ f'π [{watchdog_class_name}.{actual_handler.__name__}] β³ Waiting for reconnection...'+ )+ try:+ await asyncio.wait_for(browser_session._reconnect_event.wait(), timeout=20.0)+ except TimeoutError:+ raise ConnectionError(+ f'[{watchdog_class_name}.{actual_handler.__name__}] Reconnection wait timed out after 20s'+ )+ # After wait: check if reconnection actually succeeded+ if not browser_session.is_cdp_connected:+ raise ConnectionError(+ f'[{watchdog_class_name}.{actual_handler.__name__}] Reconnection failed β CDP still not connected'+ )+ # Reconnection succeeded β fall through to execute handler normally+ else:+ # Not reconnecting β intentional stop, backward compat silent skip+ browser_session.logger.debug(+ f'π [{watchdog_class_name}.{actual_handler.__name__}] β‘ Skipped β CDP not connected'+ )+ return None# just for debug logging, not used for anything elseparent_event = event_bus.event_history.get(event.event_parent_id) if event.event_parent_id else None