Skip to content

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

feat: added exp backoff retry and minimum element load

Saurav Panda0da9457f6beb
diff --git a/browser_use/agent/service.py b/browser_use/agent/service.py
index aa0d1bada..9b1eec41d 100644
--- a/browser_use/agent/service.py
+++ b/browser_use/agent/service.py
@@ -2807,6 +2807,9 @@ class Agent(Generic[Context, AgentStructuredOutput]):
retry_count = 0
step_succeeded = False
+ # Exponential backoff: 5s base, doubling each retry, capped at 30s
+ base_retry_delay = 5.0
+ max_retry_delay = 30.0
while retry_count < max_retries:
try:
result = await self._execute_history_step(history_item, step_delay, ai_step_llm)
@@ -2825,8 +2828,12 @@ class Agent(Generic[Context, AgentStructuredOutput]):
raise RuntimeError(error_msg)
# With skip_failures=True, continue to next step
else:
- self.logger.warning(f'{step_name} failed (attempt {retry_count}/{max_retries}), retrying...')
- await asyncio.sleep(delay_between_actions)
+ # Exponential backoff: 5s, 10s, 20s, ... capped at 30s
+ retry_delay = min(base_retry_delay * (2 ** (retry_count - 1)), max_retry_delay)
+ self.logger.warning(
+ f'{step_name} failed (attempt {retry_count}/{max_retries}), retrying in {retry_delay}s...'
+ )
+ await asyncio.sleep(retry_delay)
# Update tracking for redundant retry detection
previous_item = history_item
@@ -2891,6 +2898,69 @@ class Agent(Generic[Context, AgentStructuredOutput]):
self.logger.debug('📝 Saved initial actions to history as step 0')
self.logger.debug('Initial actions completed')
+ async def _wait_for_minimum_elements(
+ self,
+ min_elements: int,
+ timeout: float = 30.0,
+ poll_interval: float = 1.0,
+ ) -> BrowserStateSummary | None:
+ """Wait for the page to have at least min_elements interactive elements.
+
+ This helps handle SPA pages where shadow DOM and dynamic content
+ may not be immediately available even when document.readyState is 'complete'.
+
+ Args:
+ min_elements: Minimum number of interactive elements to wait for
+ timeout: Maximum time to wait in seconds
+ poll_interval: Time between polling attempts in seconds
+
+ Returns:
+ BrowserStateSummary if minimum elements found, None if timeout
+ """
+ assert self.browser_session is not None, 'BrowserSession is not set up'
+
+ start_time = time.time()
+ last_count = 0
+
+ while (time.time() - start_time) < timeout:
+ state = await self.browser_session.get_browser_state_summary(include_screenshot=False)
+ if state and state.dom_state.selector_map:
+ current_count = len(state.dom_state.selector_map)
+ if current_count >= min_elements:
+ self.logger.debug(f'✅ Page has {current_count} elements (needed {min_elements}), proceeding with action')
+ return state
+ if current_count != last_count:
+ self.logger.debug(
+ f'⏳ Waiting for elements: {current_count}/{min_elements} '
+ f'(timeout in {timeout - (time.time() - start_time):.1f}s)'
+ )
+ last_count = current_count
+ await asyncio.sleep(poll_interval)
+
+ # Return last state even if we didn't reach min_elements
+ self.logger.warning(f'⚠️ Timeout waiting for {min_elements} elements, proceeding with {last_count} elements')
+ return await self.browser_session.get_browser_state_summary(include_screenshot=False)
+
+ def _count_expected_elements_from_history(self, history_item: AgentHistory) -> int:
+ """Estimate the minimum number of elements expected based on history.
+
+ Looks at the interacted elements and their indices to determine
+ a reasonable minimum element count for the page.
+ """
+ if not history_item.state.interacted_element:
+ return 0
+
+ max_index = 0
+ for elem in history_item.state.interacted_element:
+ if elem and elem.backend_node_id:
+ # Use backend_node_id as a rough indicator of element count
+ # Elements with higher indices suggest more elements on the page
+ max_index = max(max_index, elem.backend_node_id)
+
+ # Return a reasonable minimum - at least the max index we're trying to interact with
+ # but cap it to avoid waiting forever for very high indices
+ return min(max_index, 50) if max_index > 0 else 0
+
async def _execute_history_step(
self, history_item: AgentHistory, delay: float, ai_step_llm: BaseChatModel | None = None
) -> list[ActionResult]:
@@ -2901,7 +2971,31 @@ class Agent(Generic[Context, AgentStructuredOutput]):
assert self.browser_session is not None, 'BrowserSession is not set up'
await asyncio.sleep(delay)
- state = await self.browser_session.get_browser_state_summary(include_screenshot=False)
+
+ # Determine if we need to wait for elements (actions that interact with DOM elements)
+ needs_element_matching = False
+ if history_item.model_output:
+ for i, action in enumerate(history_item.model_output.action):
+ action_data = action.model_dump(exclude_unset=True)
+ action_name = next(iter(action_data.keys()), None)
+ # Actions that need element matching
+ if action_name in ('click', 'input', 'hover', 'select_option', 'drag_and_drop'):
+ historical_elem = (
+ history_item.state.interacted_element[i] if i < len(history_item.state.interacted_element) else None
+ )
+ if historical_elem is not None:
+ needs_element_matching = True
+ break
+
+ # If we need element matching, wait for minimum elements before proceeding
+ if needs_element_matching:
+ min_elements = self._count_expected_elements_from_history(history_item)
+ if min_elements > 0:
+ state = await self._wait_for_minimum_elements(min_elements, timeout=15.0, poll_interval=1.0)
+ else:
+ state = await self.browser_session.get_browser_state_summary(include_screenshot=False)
+ else:
+ state = await self.browser_session.get_browser_state_summary(include_screenshot=False)
if not state or not history_item.model_output:
raise ValueError('Invalid state or model output')
diff --git a/tests/ci/test_rerun_ai_summary.py b/tests/ci/test_rerun_ai_summary.py
index 784113f02..b10ffb0ab 100644
--- a/tests/ci/test_rerun_ai_summary.py
+++ b/tests/ci/test_rerun_ai_summary.py
@@ -862,3 +862,431 @@ async def test_is_redundant_retry_step_detection():
finally:
await agent.close()
+
+
+async def test_count_expected_elements_from_history():
+ """Test that _count_expected_elements_from_history correctly estimates element count."""
+ from browser_use.dom.views import DOMInteractedElement
+
+ llm = create_mock_llm(actions=None)
+ agent = Agent(task='Test task', llm=llm)
+ AgentOutput = agent.AgentOutput
+
+ # Create elements with different backend_node_ids
+ element_low_id = DOMInteractedElement(
+ node_id=1,
+ backend_node_id=5,
+ frame_id=None,
+ node_type=NodeType.ELEMENT_NODE,
+ node_value='',
+ node_name='INPUT',
+ attributes={'name': 'username'},
+ x_path='html/body/input[1]',
+ element_hash=12345,
+ bounds=DOMRect(x=0, y=0, width=100, height=30),
+ )
+
+ element_high_id = DOMInteractedElement(
+ node_id=2,
+ backend_node_id=25,
+ frame_id=None,
+ node_type=NodeType.ELEMENT_NODE,
+ node_value='',
+ node_name='BUTTON',
+ attributes={'id': 'submit'},
+ x_path='html/body/button',
+ element_hash=67890,
+ bounds=DOMRect(x=0, y=0, width=100, height=30),
+ )
+
+ element_very_high_id = DOMInteractedElement(
+ node_id=3,
+ backend_node_id=100, # Very high - should be capped at 50
+ frame_id=None,
+ node_type=NodeType.ELEMENT_NODE,
+ node_value='',
+ node_name='DIV',
+ attributes={},
+ x_path='html/body/div',
+ element_hash=11111,
+ bounds=DOMRect(x=0, y=0, width=100, height=30),
+ )
+
+ # Test 1: History with low backend_node_id
+ step_low = AgentHistory(
+ model_output=AgentOutput(
+ evaluation_previous_goal=None,
+ memory='Test',
+ next_goal=None,
+ action=[{'input': {'index': 5, 'text': 'test'}}], # type: ignore[arg-type]
+ ),
+ result=[ActionResult(long_term_memory='Done')],
+ state=BrowserStateHistory(
+ url='http://test.com',
+ title='Test',
+ tabs=[],
+ interacted_element=[element_low_id],
+ ),
+ metadata=StepMetadata(step_start_time=0, step_end_time=1, step_number=1, step_interval=0.1),
+ )
+
+ # Test 2: History with higher backend_node_id
+ step_high = AgentHistory(
+ model_output=AgentOutput(
+ evaluation_previous_goal=None,
+ memory='Test',
+ next_goal=None,
+ action=[{'click': {'index': 25}}], # type: ignore[arg-type]
+ ),
+ result=[ActionResult(long_term_memory='Done')],
+ state=BrowserStateHistory(
+ url='http://test.com',
+ title='Test',
+ tabs=[],
+ interacted_element=[element_high_id],
+ ),
+ metadata=StepMetadata(step_start_time=0, step_end_time=1, step_number=2, step_interval=0.1),
+ )
+
+ # Test 3: History with very high backend_node_id (should be capped)
+ step_very_high = AgentHistory(
+ model_output=AgentOutput(
+ evaluation_previous_goal=None,
+ memory='Test',
+ next_goal=None,
+ action=[{'click': {'index': 100}}], # type: ignore[arg-type]
+ ),
+ result=[ActionResult(long_term_memory='Done')],
+ state=BrowserStateHistory(
+ url='http://test.com',
+ title='Test',
+ tabs=[],
+ interacted_element=[element_very_high_id],
+ ),
+ metadata=StepMetadata(step_start_time=0, step_end_time=1, step_number=3, step_interval=0.1),
+ )
+
+ # Test 4: History with no interacted elements
+ step_no_elements = AgentHistory(
+ model_output=AgentOutput(
+ evaluation_previous_goal=None,
+ memory='Test',
+ next_goal=None,
+ action=[{'navigate': {'url': 'http://test.com'}}], # type: ignore[arg-type]
+ ),
+ result=[ActionResult(long_term_memory='Done')],
+ state=BrowserStateHistory(
+ url='http://test.com',
+ title='Test',
+ tabs=[],
+ interacted_element=[None],
+ ),
+ metadata=StepMetadata(step_start_time=0, step_end_time=1, step_number=4, step_interval=0.1),
+ )
+
+ try:
+ # Test 1: Low backend_node_id returns that id
+ assert agent._count_expected_elements_from_history(step_low) == 5
+
+ # Test 2: Higher backend_node_id returns that id
+ assert agent._count_expected_elements_from_history(step_high) == 25
+
+ # Test 3: Very high backend_node_id is capped at 50
+ assert agent._count_expected_elements_from_history(step_very_high) == 50
+
+ # Test 4: No interacted elements returns 0
+ assert agent._count_expected_elements_from_history(step_no_elements) == 0
+
+ finally:
+ await agent.close()
+
+
+async def test_wait_for_minimum_elements(httpserver):
+ """Test that _wait_for_minimum_elements waits for elements to appear."""
+ # Set up a simple test page with a button
+ test_html = """<!DOCTYPE html>
+ <html>
+ <body>
+ <button id="btn1">Button 1</button>
+ <button id="btn2">Button 2</button>
+ <input type="text" id="input1" />
+ </body>
+ </html>"""
+ httpserver.expect_request('/test').respond_with_data(test_html, content_type='text/html')
+ test_url = httpserver.url_for('/test')
+
+ llm = create_mock_llm(actions=None)
+ agent = Agent(task='Test task', llm=llm)
+
+ try:
+ await agent.browser_session.start()
+
+ # Navigate to the test page first
+ from browser_use.browser.events import NavigateToUrlEvent
+
+ await agent.browser_session.event_bus.dispatch(NavigateToUrlEvent(url=test_url, new_tab=False))
+
+ # Wait a bit for navigation
+ import asyncio
+
+ await asyncio.sleep(1.0)
+
+ # Test 1: Wait for 1 element (should succeed quickly)
+ state = await agent._wait_for_minimum_elements(min_elements=1, timeout=5.0, poll_interval=0.5)
+ assert state is not None
+ assert state.dom_state.selector_map is not None
+ assert len(state.dom_state.selector_map) >= 1
+
+ # Test 2: Wait for reasonable number of elements (should succeed)
+ state = await agent._wait_for_minimum_elements(min_elements=2, timeout=5.0, poll_interval=0.5)
+ assert state is not None
+ assert len(state.dom_state.selector_map) >= 2
+
+ # Test 3: Wait for too many elements (should timeout but still return state)
+ state = await agent._wait_for_minimum_elements(min_elements=100, timeout=2.0, poll_interval=0.5)
+ assert state is not None # Should still return a state even on timeout
+
+ finally:
+ await agent.close()
+
+
+async def test_rerun_waits_for_elements_before_matching(httpserver):
+ """Test that rerun_history waits for elements before attempting element matching.
+
+ This test verifies that for actions needing element matching (like click),
+ the rerun logic waits for the page to have enough elements before proceeding.
+ """
+ from browser_use.dom.views import DOMInteractedElement
+
+ # Set up a test page with elements
+ test_html = """<!DOCTYPE html>
+ <html>
+ <body>
+ <button id="test-btn" aria-label="Test Button">Click me</button>
+ </body>
+ </html>"""
+ httpserver.expect_request('/test').respond_with_data(test_html, content_type='text/html')
+ test_url = httpserver.url_for('/test')
+
+ # Create a mock LLM for summary
+ summary_action = RerunSummaryAction(
+ summary='Rerun completed',
+ success=True,
+ completion_status='complete',
+ )
+
+ async def custom_ainvoke(*args, **kwargs):
+ output_format = args[1] if len(args) > 1 else kwargs.get('output_format')
+ if output_format is RerunSummaryAction:
+ from browser_use.llm.views import ChatInvokeCompletion
+
+ return ChatInvokeCompletion(completion=summary_action, usage=None)
+ raise ValueError('Unexpected output_format')
+
+ mock_summary_llm = AsyncMock()
+ mock_summary_llm.ainvoke.side_effect = custom_ainvoke
+
+ llm = create_mock_llm(actions=None)
+ agent = Agent(task='Test task', llm=llm)
+ AgentOutput = agent.AgentOutput
+
+ # Create an element that matches the page
+ button_element = DOMInteractedElement(
+ node_id=1,
+ backend_node_id=5, # This will trigger waiting for at least 5 elements
+ frame_id=None,
+ node_type=NodeType.ELEMENT_NODE,
+ node_value='',
+ node_name='BUTTON',
+ attributes={'aria-label': 'Test Button', 'id': 'test-btn'},
+ x_path='html/body/button',
+ element_hash=12345,
+ stable_hash=12345,
+ bounds=DOMRect(x=0, y=0, width=100, height=50),
+ )
+
+ # Step 1: Navigate to test page
+ navigate_step = AgentHistory(
+ model_output=AgentOutput(
+ evaluation_previous_goal=None,
+ memory='Navigate to test page',
+ next_goal=None,
+ action=[{'navigate': {'url': test_url}}], # type: ignore[arg-type]
+ ),
+ result=[ActionResult(long_term_memory='Navigated')],
+ state=BrowserStateHistory(
+ url=test_url,
+ title='Test Page',
+ tabs=[],
+ interacted_element=[None],
+ ),
+ metadata=StepMetadata(
+ step_start_time=0,
+ step_end_time=1,
+ step_number=1,
+ step_interval=0.1,
+ ),
+ )
+
+ # Step 2: Click button (needs element matching, should wait for elements)
+ click_step = AgentHistory(
+ model_output=AgentOutput(
+ evaluation_previous_goal=None,
+ memory='Click button',
+ next_goal=None,
+ action=[{'click': {'index': 5}}], # type: ignore[arg-type]
+ ),
+ result=[ActionResult(long_term_memory='Clicked')],
+ state=BrowserStateHistory(
+ url=test_url,
+ title='Test Page',
+ tabs=[],
+ interacted_element=[button_element],
+ ),
+ metadata=StepMetadata(
+ step_start_time=1,
+ step_end_time=2,
+ step_number=2,
+ step_interval=0.1,
+ ),
+ )
+
+ history = AgentHistoryList(history=[navigate_step, click_step])
+
+ try:
+ # Run rerun - it should wait for elements before trying to match
+ results = await agent.rerun_history(
+ history,
+ skip_failures=True,
+ max_retries=1,
+ summary_llm=mock_summary_llm,
+ )
+
+ # Should have results: navigate + click (or error if element not found) + summary
+ assert len(results) >= 2
+
+ # First result should be navigation success
+ nav_result = results[0]
+ assert nav_result.error is None
+
+ finally:
+ await agent.close()
+
+
+async def test_rerun_uses_exponential_backoff_retry_delays(httpserver):
+ """Test that rerun uses exponential backoff delays between retries (5s, 10s, 20s, capped at 30s)."""
+ import time
+
+ from browser_use.dom.views import DOMInteractedElement
+
+ # Set up a test page with a button that won't match
+ test_html = """<!DOCTYPE html>
+ <html>
+ <body>
+ <button id="real-btn">Real Button</button>
+ </body>
+ </html>"""
+ httpserver.expect_request('/test').respond_with_data(test_html, content_type='text/html')
+ test_url = httpserver.url_for('/test')
+
+ llm = create_mock_llm(actions=None)
+ agent = Agent(task='Test task', llm=llm)
+ AgentOutput = agent.AgentOutput
+
+ # Create an element that WON'T match (different identifiers)
+ non_matching_element = DOMInteractedElement(
+ node_id=1,
+ backend_node_id=1, # Low to avoid long element waiting
+ frame_id=None,
+ node_type=NodeType.ELEMENT_NODE,
+ node_value='',
+ node_name='BUTTON',
+ attributes={'aria-label': 'Non-existent', 'id': 'fake-id'},
+ x_path='html/body/button[999]',
+ element_hash=99999,
+ stable_hash=99999,
+ bounds=DOMRect(x=0, y=0, width=100, height=50),
+ )
+
+ # Step 1: Navigate
+ navigate_step = AgentHistory(
+ model_output=AgentOutput(
+ evaluation_previous_goal=None,
+ memory='Navigate',
+ next_goal=None,
+ action=[{'navigate': {'url': test_url}}], # type: ignore[arg-type]
+ ),
+ result=[ActionResult(long_term_memory='Navigated')],
+ state=BrowserStateHistory(
+ url=test_url,
+ title='Test',
+ tabs=[],
+ interacted_element=[None],
+ ),
+ metadata=StepMetadata(step_start_time=0, step_end_time=1, step_number=1, step_interval=0.1),
+ )
+
+ # Step 2: Click non-matching element (will fail and retry)
+ failing_step = AgentHistory(
+ model_output=AgentOutput(
+ evaluation_previous_goal=None,
+ memory='Click',
+ next_goal=None,
+ action=[{'click': {'index': 1}}], # type: ignore[arg-type]
+ ),
+ result=[ActionResult(long_term_memory='Clicked')],
+ state=BrowserStateHistory(
+ url=test_url,
+ title='Test',
+ tabs=[],
+ interacted_element=[non_matching_element],
+ ),
+ metadata=StepMetadata(step_start_time=1, step_end_time=2, step_number=2, step_interval=0.1),
+ )
+
+ history = AgentHistoryList(history=[navigate_step, failing_step])
+
+ try:
+ start_time = time.time()
+
+ # Run rerun with 2 retries - should use exponential backoff (5s for first retry)
+ # Attempt 1 fails -> wait 5s -> Attempt 2 fails -> done
+ try:
+ await agent.rerun_history(
+ history,
+ skip_failures=False,
+ max_retries=2, # Will fail twice with 5s delay between (exponential: 5s * 2^0 = 5s)
+ )
+ except RuntimeError:
+ pass # Expected to fail
+
+ elapsed = time.time() - start_time
+
+ # Should have taken at least 5 seconds (the first retry delay with exponential backoff)
+ # Exponential backoff formula: base_delay * 2^(retry_count-1) = 5 * 2^0 = 5s
+ assert elapsed >= 4.5, f'Expected at least 4.5s elapsed (5s exponential backoff), got {elapsed:.1f}s'
+
+ finally:
+ await agent.close()
+
+
+async def test_exponential_backoff_calculation():
+ """Test that exponential backoff correctly calculates delays: 5s, 10s, 20s, capped at 30s."""
+ # Verify the exponential backoff formula: min(5 * 2^(retry-1), 30)
+ base_delay = 5.0
+ max_delay = 30.0
+
+ # Retry 1: 5 * 2^0 = 5s
+ assert min(base_delay * (2**0), max_delay) == 5.0
+
+ # Retry 2: 5 * 2^1 = 10s
+ assert min(base_delay * (2**1), max_delay) == 10.0
+
+ # Retry 3: 5 * 2^2 = 20s
+ assert min(base_delay * (2**2), max_delay) == 20.0
+
+ # Retry 4: 5 * 2^3 = 40s -> capped at 30s
+ assert min(base_delay * (2**3), max_delay) == 30.0
+
+ # Retry 5: 5 * 2^4 = 80s -> capped at 30s
+ assert min(base_delay * (2**4), max_delay) == 30.0