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
Improve multiact for agent
Saurav Pandadefe37dd286e
diff --git a/browser_use/agent/service.py b/browser_use/agent/service.pyindex f9b8c9c22..398096fa1 100644--- a/browser_use/agent/service.py+++ b/browser_use/agent/service.py@@ -170,7 +170,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):generate_gif: bool | str = False,available_file_paths: list[str] | None = None,include_attributes: list[str] | None = None,- max_actions_per_step: int = 3,+ max_actions_per_step: int = 5,use_thinking: bool = True,flash_mode: bool = False,demo_mode: bool | None = None,@@ -2394,7 +2394,14 @@ class Agent(Generic[Context, AgentStructuredOutput]):@observe_debug(ignore_input=True, ignore_output=True)@time_execution_async('--multi_act')async def multi_act(self, actions: list[ActionModel]) -> list[ActionResult]:- """Execute multiple actions"""+ """Execute multiple actions with page-change guards.++ Two layers of protection prevent executing actions against stale DOM:+ 1. Static flag: actions tagged with terminates_sequence=True (navigate, search, go_back, switch)+ automatically abort remaining queued actions.+ 2. Runtime detection: after every action, the current URL and focused target are compared+ to pre-action values. Any change aborts the remaining queue.+ """results: list[ActionResult] = []time_elapsed = 0total_actions = len(actions)@@ -2437,6 +2444,10 @@ class Agent(Generic[Context, AgentStructuredOutput]):# Log action before executionawait self._log_action(action, action_name, i + 1, total_actions)+ # Capture pre-action state for runtime page-change detection+ pre_action_url = await self.browser_session.get_current_page_url()+ pre_action_focus = self.browser_session.agent_focus_target_id+time_start = time.time()result = await self.tools.act(@@ -2472,6 +2483,24 @@ class Agent(Generic[Context, AgentStructuredOutput]):if results[-1].is_done or results[-1].error or i == total_actions - 1:break+ # --- Page-change guards (only when more actions remain) ---++ # Layer 1: Static flag — action metadata declares it changes the page+ registered_action = self.tools.registry.registry.actions.get(action_name)+ if registered_action and registered_action.terminates_sequence:+ self.logger.info(+ f'Action "{action_name}" terminates sequence — skipping {total_actions - i - 1} remaining action(s)'+ )+ break++ # Layer 2: Runtime detection — URL or focus target changed+ post_action_url = await self.browser_session.get_current_page_url()+ post_action_focus = self.browser_session.agent_focus_target_id++ if post_action_url != pre_action_url or post_action_focus != pre_action_focus:+ self.logger.info(f'Page changed after "{action_name}" — skipping {total_actions - i - 1} remaining action(s)')+ break+except Exception as e:# Handle any exceptions during action executionself.logger.error(f'❌ Executing action {i + 1} failed -> {type(e).__name__}: {e}')diff --git a/browser_use/agent/system_prompts/system_prompt.md b/browser_use/agent/system_prompts/system_prompt.mdindex f19b6ed32..04926ca81 100644--- a/browser_use/agent/system_prompts/system_prompt.md+++ b/browser_use/agent/system_prompts/system_prompt.md@@ -122,21 +122,26 @@ The `done` action is your opportunity to terminate and share your findings with<action_rules>- You are allowed to use a maximum of {max_actions} actions per step.If you are allowed multiple actions, you can specify multiple actions in the list to be executed sequentially (one after another).-- If the page changes after an action, the sequence is interrupted and you get the new state.-Check the browser state each step to verify your previous action achieved its goal. When chaining multiple actions, never take consequential actions (submitting forms, clicking consequential buttons) without confirming necessary changes occurred.+- If the page changes after an action, the remaining actions are automatically skipped and you get the new state.+Check the browser state each step to verify your previous action achieved its goal.</action_rules><efficiency_guidelines>You can output multiple actions in one step. Try to be efficient where it makes sense. Do not predict actions which do not make sense for the current page.-**Recommended Action Combinations:**-- `input` + `click` → Fill form field and submit/search in one step++**Action categories:**+- **Page-changing (always last):** `navigate`, `search`, `go_back`, `switch` — these always change the page. Remaining actions after them are skipped automatically.+- **Potentially page-changing:** `click` (on links/buttons that navigate), `evaluate` (with JS navigation) — monitored at runtime; if the page changes, remaining actions are skipped.+- **Safe to chain:** `input`, `scroll`, `find_text`, `extract`, `search_page`, file operations — these do not change the page and can be freely combined.++**Recommended combinations:**+- `input` + `input` + `input` + `click` → Fill multiple form fields then submit- `input` + `input` → Fill multiple form fields-- `click` + `click` → Navigate through multi-step flows (when the page does not navigate between clicks)+- `scroll` + `scroll` → Scroll further down the page+- `click` + `click` → Navigate multi-step flows (only when clicks do not navigate)- File operations + browser actions+Do not try multiple different paths in one step. Always have one clear goal per step.-Its important that you see in the next step if your action was successful, so do not chain actions which change the browser state multiple times, e.g.-- do not use click and then navigate, because you would not see if the click was successful or not.-- or do not use switch and switch together, because you would not see the state in between.-- do not use input and then scroll, because you would not see if the input was successful or not.+Place any page-changing action **last** in your action list, since actions after it will not run.</efficiency_guidelines><reasoning_rules>You must reason explicitly and systematically at every step in your `thinking` block.diff --git a/browser_use/agent/views.py b/browser_use/agent/views.pyindex 0131a0f7e..dcc6ab8e1 100644--- a/browser_use/agent/views.py+++ b/browser_use/agent/views.py@@ -41,7 +41,7 @@ class AgentSettings(BaseModel):override_system_message: str | None = Noneextend_system_message: str | None = Noneinclude_attributes: list[str] | None = DEFAULT_INCLUDE_ATTRIBUTES- max_actions_per_step: int = 3+ max_actions_per_step: int = 5use_thinking: bool = Trueflash_mode: bool = False # If enabled, disables evaluation_previous_goal and next_goal, and sets use_thinking = Falseuse_judge: bool = Truediff --git a/browser_use/tools/registry/service.py b/browser_use/tools/registry/service.pyindex 6b155a5f7..9a0a78bed 100644--- a/browser_use/tools/registry/service.py+++ b/browser_use/tools/registry/service.py@@ -293,6 +293,7 @@ class Registry(Generic[Context]):param_model: type[BaseModel] | None = None,domains: list[str] | None = None,allowed_domains: list[str] | None = None,+ terminates_sequence: bool = False,):"""Decorator for registering actions"""# Handle aliases: domains and allowed_domains are the same parameter@@ -315,6 +316,7 @@ class Registry(Generic[Context]):function=normalized_func,param_model=actual_param_model,domains=final_domains,+ terminates_sequence=terminates_sequence,)self.registry.actions[func.__name__] = actiondiff --git a/browser_use/tools/registry/views.py b/browser_use/tools/registry/views.pyindex d0bc2bc3c..f91b6453d 100644--- a/browser_use/tools/registry/views.py+++ b/browser_use/tools/registry/views.py@@ -19,6 +19,10 @@ class RegisteredAction(BaseModel):function: Callableparam_model: type[BaseModel]+ # If True, this action is known to change the page (e.g. navigate, search, go_back, switch).+ # multi_act() will abort remaining queued actions after executing a terminates_sequence action.+ terminates_sequence: bool = False+# filters: provide specific domains to determine whether the action should be available on the given URL or notdomains: list[str] | None = None # e.g. ['*.google.com', 'www.bing.com', 'yahoo.*]diff --git a/browser_use/tools/service.py b/browser_use/tools/service.pyindex 1ef6b1650..86a3a44da 100644--- a/browser_use/tools/service.py+++ b/browser_use/tools/service.py@@ -359,6 +359,7 @@ class Tools(Generic[Context]):@self.registry.action('',param_model=SearchAction,+ terminates_sequence=True,)async def search(params: SearchAction, browser_session: BrowserSession):import urllib.parse@@ -402,6 +403,7 @@ class Tools(Generic[Context]):@self.registry.action('',param_model=NavigateAction,+ terminates_sequence=True,)async def navigate(params: NavigateAction, browser_session: BrowserSession):try:@@ -446,7 +448,7 @@ class Tools(Generic[Context]):# Return error in ActionResult instead of re-raisingreturn ActionResult(error=f'Navigation failed: {str(e)}')- @self.registry.action('Go back', param_model=NoParamsAction)+ @self.registry.action('Go back', param_model=NoParamsAction, terminates_sequence=True)async def go_back(_: NoParamsAction, browser_session: BrowserSession):try:event = browser_session.event_bus.dispatch(GoBackEvent())@@ -854,6 +856,7 @@ class Tools(Generic[Context]):@self.registry.action('Switch to another open tab by tab_id. Tab IDs are shown in browser state tabs list (last 4 chars of target_id). Use when you need to work with content in a different tab.',param_model=SwitchTabAction,+ terminates_sequence=True,)async def switch(params: SwitchTabAction, browser_session: BrowserSession):# Simple switch tab logicdiff --git a/tests/ci/test_multi_act_guards.py b/tests/ci/test_multi_act_guards.pynew file mode 100644index 000000000..17b5e8ef1--- /dev/null+++ b/tests/ci/test_multi_act_guards.py@@ -0,0 +1,283 @@+"""+Tests for multi_act() page-change guards.++Verifies:+1. Metadata: terminates_sequence flags are set correctly on built-in actions+2. Static guard: actions tagged terminates_sequence abort remaining queued actions+3. Runtime guard: URL/focus changes detected after click-on-link abort remaining actions+4. Safe chain: multiple inputs execute without interruption++Usage:+ uv run pytest tests/ci/test_multi_act_guards.py -v -s+"""++import asyncio++import pytest+from pytest_httpserver import HTTPServer++from browser_use.agent.service import Agent+from browser_use.browser import BrowserSession+from browser_use.browser.profile import BrowserProfile+from browser_use.tools.service import Tools+from tests.ci.conftest import create_mock_llm++# ---------------------------------------------------------------------------+# Fixtures+# ---------------------------------------------------------------------------++[email protected](scope='session')+def http_server():+ """Test HTTP server with pages for guard tests."""+ server = HTTPServer()+ server.start()++ server.expect_request('/form').respond_with_data(+ """<html><head><title>Form Page</title></head><body>+ <h1>Form</h1>+ <input id="field1" type="text" placeholder="Field 1" />+ <input id="field2" type="text" placeholder="Field 2" />+ <input id="field3" type="text" placeholder="Field 3" />+ <button id="submit" type="submit">Submit</button>+ </body></html>""",+ content_type='text/html',+ )++ server.expect_request('/page_a').respond_with_data(+ """<html><head><title>Page A</title></head><body>+ <h1>Page A</h1>+ <a id="link_b" href="/page_b">Go to Page B</a>+ </body></html>""",+ content_type='text/html',+ )++ server.expect_request('/page_b').respond_with_data(+ """<html><head><title>Page B</title></head><body>+ <h1>Page B</h1>+ <p>You arrived at Page B</p>+ </body></html>""",+ content_type='text/html',+ )++ server.expect_request('/static').respond_with_data(+ """<html><head><title>Static Page</title></head><body>+ <h1>Static</h1>+ <p>Nothing changes here</p>+ <input id="safe_input" type="text" />+ </body></html>""",+ content_type='text/html',+ )++ yield server+ server.stop()++[email protected](scope='session')+def base_url(http_server):+ return f'http://{http_server.host}:{http_server.port}'++[email protected](scope='module')+async def browser_session():+ session = BrowserSession(+ browser_profile=BrowserProfile(+ headless=True,+ user_data_dir=None,+ keep_alive=True,+ )+ )+ await session.start()+ yield session+ await session.kill()+ await session.event_bus.stop(clear=True, timeout=5)++[email protected](scope='function')+def tools():+ return Tools()+++# ---------------------------------------------------------------------------+# 1. Metadata tests — verify terminates_sequence flags+# ---------------------------------------------------------------------------+++class TestTerminatesSequenceMetadata:+ """Verify that built-in actions have correct terminates_sequence flags."""++ def test_navigate_terminates(self, tools):+ action = tools.registry.registry.actions.get('navigate')+ assert action is not None+ assert action.terminates_sequence is True++ def test_search_terminates(self, tools):+ action = tools.registry.registry.actions.get('search')+ assert action is not None+ assert action.terminates_sequence is True++ def test_go_back_terminates(self, tools):+ action = tools.registry.registry.actions.get('go_back')+ assert action is not None+ assert action.terminates_sequence is True++ def test_switch_terminates(self, tools):+ action = tools.registry.registry.actions.get('switch')+ assert action is not None+ assert action.terminates_sequence is True++ def test_click_does_not_terminate(self, tools):+ action = tools.registry.registry.actions.get('click')+ assert action is not None+ assert action.terminates_sequence is False++ def test_input_does_not_terminate(self, tools):+ action = tools.registry.registry.actions.get('input')+ assert action is not None+ assert action.terminates_sequence is False++ def test_scroll_does_not_terminate(self, tools):+ action = tools.registry.registry.actions.get('scroll')+ assert action is not None+ assert action.terminates_sequence is False++ def test_extract_does_not_terminate(self, tools):+ action = tools.registry.registry.actions.get('extract')+ assert action is not None+ assert action.terminates_sequence is False+++# ---------------------------------------------------------------------------+# 2. Static guard — navigate as non-last action skips remaining+# ---------------------------------------------------------------------------+++class TestStaticGuard:+ """Verify that terminates_sequence actions abort the remaining queue."""++ async def test_navigate_aborts_remaining_actions(self, browser_session, base_url, tools):+ """When navigate is action 2/3, action 3 should never execute."""+ # Start on a known page+ await tools.navigate(url=f'{base_url}/static', new_tab=False, browser_session=browser_session)+ await asyncio.sleep(0.5)++ # Build action models: [scroll_down, navigate_to_page_a, scroll_down]+ ActionModel = tools.registry.create_action_model()+ actions = [+ ActionModel.model_validate({'scroll': {'down': True, 'pages': 1}}),+ ActionModel.model_validate({'navigate': {'url': f'{base_url}/page_a'}}),+ ActionModel.model_validate({'scroll': {'down': True, 'pages': 1}}),+ ]++ mock_llm = create_mock_llm()+ agent = Agent(task='test', llm=mock_llm, browser_session=browser_session, tools=tools)++ results = await agent.multi_act(actions)++ # Should have executed exactly 2 actions (scroll + navigate), third skipped+ assert len(results) == 2, f'Expected 2 results but got {len(results)}: {results}'++ # Verify we actually navigated+ url = await browser_session.get_current_page_url()+ assert '/page_a' in url++ async def test_go_back_aborts_remaining_actions(self, browser_session, base_url, tools):+ """go_back should abort remaining queued actions."""+ # Navigate to page_a then page_b so go_back has somewhere to go+ await tools.navigate(url=f'{base_url}/page_a', new_tab=False, browser_session=browser_session)+ await asyncio.sleep(0.3)+ await tools.navigate(url=f'{base_url}/page_b', new_tab=False, browser_session=browser_session)+ await asyncio.sleep(0.3)++ ActionModel = tools.registry.create_action_model()+ actions = [+ ActionModel.model_validate({'go_back': {}}),+ ActionModel.model_validate({'scroll': {'down': True, 'pages': 1}}),+ ]++ mock_llm = create_mock_llm()+ agent = Agent(task='test', llm=mock_llm, browser_session=browser_session, tools=tools)++ results = await agent.multi_act(actions)++ # go_back should terminate the sequence — only 1 result+ assert len(results) == 1, f'Expected 1 result but got {len(results)}: {results}'+++# ---------------------------------------------------------------------------+# 3. Runtime guard — click on link changes URL, remaining actions skipped+# ---------------------------------------------------------------------------+++class TestRuntimeGuard:+ """Verify that URL/focus changes detected at runtime abort remaining actions."""++ async def test_click_link_aborts_remaining(self, browser_session, base_url, tools):+ """Click a link that navigates to another page — remaining actions skipped."""+ await tools.navigate(url=f'{base_url}/page_a', new_tab=False, browser_session=browser_session)+ await asyncio.sleep(0.5)++ # Get the selector map to find the link index+ state = await browser_session.get_browser_state_summary()+ assert state.dom_state is not None+ selector_map = state.dom_state.selector_map++ # Find the link element (a#link_b)+ link_index = None+ for idx, element in selector_map.items():+ if hasattr(element, 'tag_name') and element.tag_name == 'a':+ link_index = idx+ break++ assert link_index is not None, 'Could not find link element in selector map'++ ActionModel = tools.registry.create_action_model()+ actions = [+ ActionModel.model_validate({'click': {'index': link_index}}),+ ActionModel.model_validate({'scroll': {'down': True, 'pages': 1}}),+ ActionModel.model_validate({'scroll': {'down': True, 'pages': 1}}),+ ]++ mock_llm = create_mock_llm()+ agent = Agent(task='test', llm=mock_llm, browser_session=browser_session, tools=tools)++ results = await agent.multi_act(actions)++ # Click navigated to page_b — runtime guard should stop at 1+ assert len(results) == 1, f'Expected 1 result but got {len(results)}: {results}'++ # Verify we're on page_b+ url = await browser_session.get_current_page_url()+ assert '/page_b' in url+++# ---------------------------------------------------------------------------+# 4. Safe chain — multiple non-page-changing actions all execute+# ---------------------------------------------------------------------------+++class TestSafeChain:+ """Verify that non-page-changing actions execute without interruption."""++ async def test_multiple_scrolls_all_execute(self, browser_session, base_url, tools):+ """Multiple scroll actions should all execute."""+ await tools.navigate(url=f'{base_url}/static', new_tab=False, browser_session=browser_session)+ await asyncio.sleep(0.5)++ ActionModel = tools.registry.create_action_model()+ actions = [+ ActionModel.model_validate({'scroll': {'down': True, 'pages': 0.5}}),+ ActionModel.model_validate({'scroll': {'down': True, 'pages': 0.5}}),+ ActionModel.model_validate({'scroll': {'down': False, 'pages': 0.5}}),+ ]++ mock_llm = create_mock_llm()+ agent = Agent(task='test', llm=mock_llm, browser_session=browser_session, tools=tools)++ results = await agent.multi_act(actions)++ # All 3 scrolls should execute+ assert len(results) == 3, f'Expected 3 results but got {len(results)}: {results}'+ # None should have errors+ for r in results:+ assert r.error is None, f'Unexpected error: {r.error}'