Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

Add WebSocket reconnection for remote browser CDP connections

Saurav Pandaabd0326a6f9b
diff --git a/browser_use/agent/service.py b/browser_use/agent/service.py
index 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 exceptions
include_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.py
index 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.py
index 5fd6f596e..ab2a3ae8c 100644
--- a/browser_use/browser/session.py
+++ b/browser_use/browser/session.py
@@ -2,6 +2,7 @@
import asyncio
import logging
+import time
from functools import cached_property
from pathlib import Path
from 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
+
@property
def 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 = False
self.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 duplicates
from 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 = True
self.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 = True
self.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 configured
await 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 working
if 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.py
index 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 asyncio
import inspect
import time
from 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/stop
if 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 else
parent_event = event_bus.event_history.get(event.event_parent_id) if event.event_parent_id else None