Skip to content

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

add-variable-substitution-in-rerun

Saurav Panda8948c4741667
diff --git a/browser_use/agent/service.py b/browser_use/agent/service.py
index d7951df8d..cf0fdad3d 100644
--- a/browser_use/agent/service.py
+++ b/browser_use/agent/service.py
@@ -906,7 +906,8 @@ class Agent(Generic[Context, AgentStructuredOutput]):
if last_history_item.metadata:
previous_end_time = last_history_item.metadata.step_end_time
- step_interval = max(0, self.step_start_time - previous_end_time)
+ previous_start_time = last_history_item.metadata.step_start_time
+ step_interval = max(0, previous_end_time - previous_start_time)
metadata = StepMetadata(
step_number=self.state.n_steps,
step_start_time=self.step_start_time,
@@ -2195,7 +2196,25 @@ class Agent(Generic[Context, AgentStructuredOutput]):
goal = history_item.model_output.current_state.next_goal if history_item.model_output else ''
step_num = history_item.metadata.step_number if history_item.metadata else i
step_name = 'Initial actions' if step_num == 0 else f'Step {step_num}'
- self.logger.info(f'Replaying {step_name} ({i + 1}/{len(history.history)}): {goal}')
+
+ # Determine step delay
+ if history_item.metadata and history_item.metadata.step_interval is not None:
+ step_delay = history_item.metadata.step_interval
+ # Format delay nicely - show ms for values < 1s, otherwise show seconds
+ if step_delay < 1.0:
+ delay_str = f'{step_delay * 1000:.0f}ms'
+ else:
+ delay_str = f'{step_delay:.1f}s'
+ delay_source = f'using saved step_interval={delay_str}'
+ else:
+ step_delay = delay_between_actions
+ if step_delay < 1.0:
+ delay_str = f'{step_delay * 1000:.0f}ms'
+ else:
+ delay_str = f'{step_delay:.1f}s'
+ delay_source = f'using default delay={delay_str}'
+
+ self.logger.info(f'Replaying {step_name} ({i + 1}/{len(history.history)}) [{delay_source}]: {goal}')
if (
not history_item.model_output
@@ -2206,11 +2225,6 @@ class Agent(Generic[Context, AgentStructuredOutput]):
results.append(ActionResult(error='No action to replay'))
continue
- if history_item.metadata and history_item.metadata.step_interval is not None:
- step_delay = history_item.metadata.step_interval
- else:
- step_delay = delay_between_actions
-
retry_count = 0
while retry_count < max_retries:
try:
@@ -2339,17 +2353,28 @@ class Agent(Generic[Context, AgentStructuredOutput]):
return action
- async def load_and_rerun(self, history_file: str | Path | None = None, **kwargs) -> list[ActionResult]:
+ async def load_and_rerun(
+ self,
+ history_file: str | Path | None = None,
+ variables: dict[str, str] | None = None,
+ **kwargs,
+ ) -> list[ActionResult]:
"""
- Load history from file and rerun it.
+ Load history from file and rerun it, optionally substituting variables.
Args:
- history_file: Path to the history file
- **kwargs: Additional arguments passed to rerun_history
+ history_file: Path to the history file
+ variables: Optional dict mapping variable names to new values (e.g. {'email': '[email protected]'})
+ **kwargs: Additional arguments passed to rerun_history
"""
if not history_file:
history_file = 'AgentHistory.json'
history = AgentHistoryList.load_from_file(history_file, self.AgentOutput)
+
+ # Substitute variables if provided
+ if variables:
+ history = self._substitute_variables_in_history(history, variables)
+
return await self.rerun_history(history, **kwargs)
def save_history(self, file_path: str | Path | None = None) -> None:
@@ -2499,7 +2524,91 @@ class Agent(Generic[Context, AgentStructuredOutput]):
return asyncio.run(self.run(max_steps=max_steps, on_step_start=on_step_start, on_step_end=on_step_end))
def detect_variables(self) -> dict[str, DetectedVariable]:
- """Detect variables in current agent history"""
+ """Detect reusable variables in agent history"""
from browser_use.agent.variable_detector import detect_variables_in_history
return detect_variables_in_history(self.history)
+
+ def _substitute_variables_in_history(self, history: AgentHistoryList, variables: dict[str, str]) -> AgentHistoryList:
+ """Substitute variables in history with new values for rerunning with different data"""
+ from browser_use.agent.variable_detector import detect_variables_in_history
+
+ # Detect variables in the history
+ detected_vars = detect_variables_in_history(history)
+
+ # Build a mapping of original values to new values
+ value_replacements: dict[str, str] = {}
+ for var_name, new_value in variables.items():
+ if var_name in detected_vars:
+ old_value = detected_vars[var_name].original_value
+ value_replacements[old_value] = new_value
+ else:
+ self.logger.warning(f'Variable "{var_name}" not found in history, skipping substitution')
+
+ if not value_replacements:
+ self.logger.info('No variables to substitute')
+ return history
+
+ # Create a deep copy of history to avoid modifying the original
+ import copy
+
+ modified_history = copy.deepcopy(history)
+
+ # Substitute values in all actions
+ substitution_count = 0
+ for history_item in modified_history.history:
+ if not history_item.model_output or not history_item.model_output.action:
+ continue
+
+ for action in history_item.model_output.action:
+ # Handle both Pydantic models and dicts
+ if hasattr(action, 'model_dump'):
+ action_dict = action.model_dump()
+ elif isinstance(action, dict):
+ action_dict = action
+ else:
+ action_dict = vars(action) if hasattr(action, '__dict__') else {}
+
+ # Substitute in all string fields
+ substitution_count += self._substitute_in_dict(action_dict, value_replacements)
+
+ # Update the action with modified values
+ if hasattr(action, 'model_dump'):
+ # For Pydantic RootModel, we need to recreate from the modified dict
+ if hasattr(action, 'root'):
+ # This is a RootModel - recreate it from the modified dict
+ new_action = type(action).model_validate(action_dict)
+ # Replace the root field in-place using object.__setattr__ to bypass Pydantic's immutability
+ object.__setattr__(action, 'root', getattr(new_action, 'root'))
+ else:
+ # Regular Pydantic model - update fields in-place
+ for key, val in action_dict.items():
+ if hasattr(action, key):
+ setattr(action, key, val)
+ elif isinstance(action, dict):
+ action.update(action_dict)
+
+ self.logger.info(f'Substituted {substitution_count} value(s) in {len(value_replacements)} variable type(s) in history')
+ return modified_history
+
+ def _substitute_in_dict(self, data: dict, replacements: dict[str, str]) -> int:
+ """Recursively substitute values in a dictionary, returns count of substitutions made"""
+ count = 0
+ for key, value in data.items():
+ if isinstance(value, str):
+ # Replace if exact match
+ if value in replacements:
+ data[key] = replacements[value]
+ count += 1
+ elif isinstance(value, dict):
+ # Recurse into nested dicts
+ count += self._substitute_in_dict(value, replacements)
+ elif isinstance(value, list):
+ # Handle lists
+ for i, item in enumerate(value):
+ if isinstance(item, str) and item in replacements:
+ value[i] = replacements[item]
+ count += 1
+ elif isinstance(item, dict):
+ count += self._substitute_in_dict(item, replacements)
+ return count
diff --git a/examples/features/rerun_history.py b/examples/features/rerun_history.py
index 623070d32..92d9ae0c0 100644
--- a/examples/features/rerun_history.py
+++ b/examples/features/rerun_history.py
@@ -1,15 +1,16 @@
"""
-Example: Rerunning saved agent history with variable detection
+Example: Rerunning saved agent history with variable detection and substitution
This example shows how to:
1. Run an agent and save its history (including initial URL navigation)
2. Detect variables in the saved history (emails, names, dates, etc.)
-3. Load and rerun the history with a new agent instance
+3. Rerun the history with original values
+4. Rerun the history with substituted values (different data)
Useful for:
- Debugging agent behavior
- Testing changes with consistent scenarios
-- Replaying successful workflows
+- Replaying successful workflows with different data
- Understanding what values can be substituted in reruns
Note: Initial actions (like opening URLs from tasks) are now automatically
@@ -27,13 +28,13 @@ from browser_use.llm import ChatBrowserUse
async def main():
# Example task to demonstrate history saving and rerunning
history_file = Path('agent_history.json')
- task = 'Go to https://browser-use.github.io/stress-tests/challenges/ember-form.html and fill the form with example data.'
+ task = 'Go to https://browser-use.github.io/stress-tests/challenges/reference-number-form.html and fill the form with example data and submit.'
llm = ChatBrowserUse()
# Step 1: Run the agent and save history
print('=== Running Agent ===')
agent = Agent(task=task, llm=llm, max_actions_per_step=1)
- await agent.run(max_steps=5)
+ await agent.run(max_steps=10)
agent.save_history(history_file)
print(f'✓ History saved to {history_file}')
@@ -48,12 +49,44 @@ async def main():
else:
print('No variables detected in history')
- # Step 3: Rerun the history with a new agent
- print('\n=== Rerunning History ===')
+ # Step 3: Rerun the history with original values
+ print('\n=== Rerunning History (Original Values) ===')
rerun_agent = Agent(task='', llm=llm)
await rerun_agent.load_and_rerun(history_file)
print('✓ History rerun complete')
+ # Step 4: Rerun the history with substituted values
+ if variables:
+ print('\n=== Rerunning History (Substituted Values) ===')
+ # Create new values for the detected variables
+ new_values = {}
+ for var_name, var_info in variables.items():
+ # Map detected variables to new values
+ if var_name == 'email':
+ new_values[var_name] = '[email protected]'
+ elif var_name == 'full_name':
+ new_values[var_name] = 'Jane Smith'
+ elif var_name.startswith('full_name_'):
+ new_values[var_name] = 'Sales Department'
+ elif var_name == 'first_name':
+ new_values[var_name] = 'Jane'
+ elif var_name == 'date':
+ new_values[var_name] = '1995-05-15'
+ elif var_name == 'country':
+ new_values[var_name] = 'Canada'
+ # You can add more variable substitutions as needed
+
+ if new_values:
+ print(f'Substituting {len(new_values)} variable(s):')
+ for var_name, new_value in new_values.items():
+ old_value = variables[var_name].original_value
+ print(f' • {var_name}: "{old_value}" → "{new_value}"')
+
+ # Rerun with substituted values
+ substitute_agent = Agent(task='', llm=llm)
+ await substitute_agent.load_and_rerun(history_file, variables=new_values)
+ print('✓ History rerun with substituted values complete')
+
if __name__ == '__main__':
asyncio.run(main())
diff --git a/tests/ci/test_history_wait_time.py b/tests/ci/test_history_wait_time.py
index a718f0844..37597b6cf 100644
--- a/tests/ci/test_history_wait_time.py
+++ b/tests/ci/test_history_wait_time.py
@@ -21,18 +21,18 @@ def test_step_metadata_step_interval_optional():
def test_step_interval_calculation():
- """Test step_interval calculation logic"""
- # Step 1 ends at 100.5
- step1_end = 100.5
+ """Test step_interval calculation logic (step duration)"""
+ # Step starts at 100.0
+ step_start = 100.0
- # Step 2 starts at 103.2
- step2_start = 103.2
+ # Step ends at 102.5
+ step_end = 102.5
- # Wait time should be 2.7 seconds
- expected_wait = 2.7
- calculated_wait = step2_start - step1_end
+ # Step duration should be 2.5 seconds
+ expected_duration = 2.5
+ calculated_duration = step_end - step_start
- assert abs(calculated_wait - expected_wait) < 0.001 # Float comparison
+ assert abs(calculated_duration - expected_duration) < 0.001 # Float comparison
def test_step_metadata_serialization_with_step_interval():
diff --git a/tests/ci/test_variable_substitution.py b/tests/ci/test_variable_substitution.py
new file mode 100644
index 000000000..ff5be9421
--- /dev/null
+++ b/tests/ci/test_variable_substitution.py
@@ -0,0 +1,272 @@
+"""Unit tests for variable substitution in agent history"""
+
+from types import SimpleNamespace
+
+from browser_use.agent.service import Agent
+from browser_use.dom.views import DOMInteractedElement, NodeType
+
+
+def create_test_element(attributes: dict[str, str] | None = None) -> DOMInteractedElement:
+ """Helper to create a DOMInteractedElement for testing"""
+ return DOMInteractedElement(
+ node_id=1,
+ backend_node_id=1,
+ frame_id='frame1',
+ node_type=NodeType.ELEMENT_NODE,
+ node_value='',
+ node_name='input',
+ attributes=attributes or {},
+ bounds=None,
+ x_path='//*[@id="test"]',
+ element_hash=12345,
+ )
+
+
+def create_mock_history(actions_with_elements: list[tuple[dict, DOMInteractedElement | None]]):
+ """Helper to create mock history for testing"""
+ history_items = []
+ for action_dict, element in actions_with_elements:
+ mock_action = SimpleNamespace(**action_dict)
+ mock_output = SimpleNamespace(action=[mock_action])
+ mock_state = SimpleNamespace(interacted_element=[element] if element else None)
+ mock_history_item = SimpleNamespace(model_output=mock_output, state=mock_state)
+ history_items.append(mock_history_item)
+
+ return SimpleNamespace(history=history_items)
+
+
+def test_substitute_single_variable(mock_llm):
+ """Test substitution of a single variable"""
+ agent = Agent(task='test', llm=mock_llm)
+
+ # Create mock history with email
+ element = create_test_element(attributes={'type': 'email'})
+ history = create_mock_history(
+ [
+ ({'input': {'index': 1, 'text': '[email protected]'}}, element),
+ ]
+ )
+
+ # Substitute the email
+ modified_history = agent._substitute_variables_in_history(
+ history, # type: ignore[arg-type]
+ {'email': '[email protected]'},
+ )
+
+ # Check that the value was substituted
+ action = modified_history.history[0].model_output.action[0] # type: ignore[attr-defined]
+ action_dict = vars(action)
+ assert action_dict['input']['text'] == '[email protected]'
+
+
+def test_substitute_multiple_variables(mock_llm):
+ """Test substitution of multiple variables"""
+ agent = Agent(task='test', llm=mock_llm)
+
+ # Create mock history with email and name
+ history = create_mock_history(
+ [
+ ({'input': {'index': 1, 'text': '[email protected]'}}, create_test_element(attributes={'type': 'email'})),
+ ({'input': {'index': 2, 'text': 'John'}}, create_test_element(attributes={'name': 'first_name'})),
+ ({'input': {'index': 3, 'text': '1990-01-01'}}, create_test_element(attributes={'type': 'date'})),
+ ]
+ )
+
+ # Substitute all variables
+ modified_history = agent._substitute_variables_in_history(
+ history, # type: ignore[arg-type]
+ {
+ 'email': '[email protected]',
+ 'first_name': 'Jane',
+ 'date': '1995-05-15',
+ },
+ )
+
+ # Check that all values were substituted
+ action1 = modified_history.history[0].model_output.action[0] # type: ignore[attr-defined]
+ action2 = modified_history.history[1].model_output.action[0] # type: ignore[attr-defined]
+ action3 = modified_history.history[2].model_output.action[0] # type: ignore[attr-defined]
+
+ assert vars(action1)['input']['text'] == '[email protected]'
+ assert vars(action2)['input']['text'] == 'Jane'
+ assert vars(action3)['input']['text'] == '1995-05-15'
+
+
+def test_substitute_partial_variables(mock_llm):
+ """Test substitution of only some variables"""
+ agent = Agent(task='test', llm=mock_llm)
+
+ # Create mock history with email and name
+ history = create_mock_history(
+ [
+ ({'input': {'index': 1, 'text': '[email protected]'}}, create_test_element(attributes={'type': 'email'})),
+ ({'input': {'index': 2, 'text': 'John'}}, create_test_element(attributes={'name': 'first_name'})),
+ ]
+ )
+
+ # Substitute only email
+ modified_history = agent._substitute_variables_in_history(
+ history, # type: ignore[arg-type]
+ {'email': '[email protected]'},
+ )
+
+ # Check that only email was substituted
+ action1 = modified_history.history[0].model_output.action[0] # type: ignore[attr-defined]
+ action2 = modified_history.history[1].model_output.action[0] # type: ignore[attr-defined]
+
+ assert vars(action1)['input']['text'] == '[email protected]'
+ assert vars(action2)['input']['text'] == 'John' # Unchanged
+
+
+def test_substitute_nonexistent_variable(mock_llm):
+ """Test that substituting a nonexistent variable doesn't break things"""
+ agent = Agent(task='test', llm=mock_llm)
+
+ # Create mock history with email
+ element = create_test_element(attributes={'type': 'email'})
+ history = create_mock_history(
+ [
+ ({'input': {'index': 1, 'text': '[email protected]'}}, element),
+ ]
+ )
+
+ # Try to substitute a variable that doesn't exist
+ modified_history = agent._substitute_variables_in_history(
+ history, # type: ignore[arg-type]
+ {'nonexistent_var': 'some_value'},
+ )
+
+ # Check that nothing changed
+ action = modified_history.history[0].model_output.action[0] # type: ignore[attr-defined]
+ action_dict = vars(action)
+ assert action_dict['input']['text'] == '[email protected]'
+
+
+def test_substitute_in_nested_dict(mock_llm):
+ """Test substitution in nested dictionary structures"""
+ agent = Agent(task='test', llm=mock_llm)
+
+ # Create a more complex action with nested structure
+ complex_action = {
+ 'search_google': {
+ 'query': '[email protected]',
+ 'metadata': {'user': '[email protected]'},
+ }
+ }
+
+ element = create_test_element(attributes={'type': 'email'})
+ history = create_mock_history([(complex_action, element)])
+
+ # Substitute the email
+ modified_history = agent._substitute_variables_in_history(
+ history, # type: ignore[arg-type]
+ {'email': '[email protected]'},
+ )
+
+ # Check that values in nested structures were substituted
+ action = modified_history.history[0].model_output.action[0] # type: ignore[attr-defined]
+ action_dict = vars(action)
+ assert action_dict['search_google']['query'] == '[email protected]'
+ assert action_dict['search_google']['metadata']['user'] == '[email protected]'
+
+
+def test_substitute_in_list(mock_llm):
+ """Test substitution in list structures"""
+ agent = Agent(task='test', llm=mock_llm)
+
+ # Create history with an input action first (so email is detected)
+ # Then an action with a list containing the same email
+ history = create_mock_history(
+ [
+ ({'input': {'index': 1, 'text': '[email protected]'}}, create_test_element(attributes={'type': 'email'})),
+ ({'some_action': {'items': ['[email protected]', 'other_value', '[email protected]']}}, None),
+ ]
+ )
+
+ # Substitute the email
+ modified_history = agent._substitute_variables_in_history(
+ history, # type: ignore[arg-type]
+ {'email': '[email protected]'},
+ )
+
+ # Check that values in the first action were substituted
+ action1 = modified_history.history[0].model_output.action[0] # type: ignore[attr-defined]
+ assert vars(action1)['input']['text'] == '[email protected]'
+
+ # Check that values in lists were also substituted
+ action2 = modified_history.history[1].model_output.action[0] # type: ignore[attr-defined]
+ action_dict = vars(action2)
+ assert action_dict['some_action']['items'] == ['[email protected]', 'other_value', '[email protected]']
+
+
+def test_substitute_preserves_original_history(mock_llm):
+ """Test that substitution doesn't modify the original history"""
+ agent = Agent(task='test', llm=mock_llm)
+
+ # Create mock history
+ element = create_test_element(attributes={'type': 'email'})
+ history = create_mock_history(
+ [
+ ({'input': {'index': 1, 'text': '[email protected]'}}, element),
+ ]
+ )
+
+ # Get original value
+ original_action = history.history[0].model_output.action[0]
+ original_value = vars(original_action)['input']['text']
+
+ # Substitute
+ agent._substitute_variables_in_history(history, {'email': '[email protected]'}) # type: ignore[arg-type]
+
+ # Check that original history is unchanged
+ current_value = vars(original_action)['input']['text']
+ assert current_value == original_value
+ assert current_value == '[email protected]'
+
+
+def test_substitute_empty_variables(mock_llm):
+ """Test substitution with empty variables dict"""
+ agent = Agent(task='test', llm=mock_llm)
+
+ # Create mock history
+ element = create_test_element(attributes={'type': 'email'})
+ history = create_mock_history(
+ [
+ ({'input': {'index': 1, 'text': '[email protected]'}}, element),
+ ]
+ )
+
+ # Substitute with empty dict
+ modified_history = agent._substitute_variables_in_history(history, {}) # type: ignore[arg-type]
+
+ # Check that nothing changed
+ action = modified_history.history[0].model_output.action[0] # type: ignore[attr-defined]
+ action_dict = vars(action)
+ assert action_dict['input']['text'] == '[email protected]'
+
+
+def test_substitute_same_value_multiple_times(mock_llm):
+ """Test that the same value is substituted across multiple actions"""
+ agent = Agent(task='test', llm=mock_llm)
+
+ # Create history where same email appears twice
+ element = create_test_element(attributes={'type': 'email'})
+ history = create_mock_history(
+ [
+ ({'input': {'index': 1, 'text': '[email protected]'}}, element),
+ ({'input': {'index': 2, 'text': '[email protected]'}}, element),
+ ]
+ )
+
+ # Substitute the email
+ modified_history = agent._substitute_variables_in_history(
+ history, # type: ignore[arg-type]
+ {'email': '[email protected]'},
+ )
+
+ # Check that both occurrences were substituted
+ action1 = modified_history.history[0].model_output.action[0] # type: ignore[attr-defined]
+ action2 = modified_history.history[1].model_output.action[0] # type: ignore[attr-defined]
+
+ assert vars(action1)['input']['text'] == '[email protected]'
+ assert vars(action2)['input']['text'] == '[email protected]'