Skip to content

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

Add Rust agent step finalization parity

Magnus Müller68ff692ad412
diff --git a/RUST_AGENT_INTEGRATION_FEATURES.md b/RUST_AGENT_INTEGRATION_FEATURES.md
index a2983e1e0..f640235c7 100644
--- a/RUST_AGENT_INTEGRATION_FEATURES.md
+++ b/RUST_AGENT_INTEGRATION_FEATURES.md
@@ -491,10 +491,15 @@ Terminal core branch: `magnus/browser-use-rust-integration` at terminal main `ee
- Telemetry is emitted from reconstructed Rust history, preserving URLs, errors, usage tokens, final result, timing, and Browser Use model/session metadata where available.
- Proof: `test_rust_agent_exposes_logging_helper_methods`.
+97. Rust Agent step finalization helper parity
+ - The Rust-backed `Agent` now exposes Browser Use's `_post_process()`, `_handle_step_error(...)`, `_finalize(...)`, `_force_done_after_last_step(...)`, `_force_done_after_failure()`, and `_make_history_item(...)` helpers.
+ - The helpers preserve failure bookkeeping, done-result logging, screenshot-backed history item creation, file-system state persistence, step counting, and done-only output switching for Rust-backed helper execution.
+ - Proof: `test_rust_agent_exposes_step_finalization_helper_methods`.
+
## Current Verification
- `python3 -m py_compile browser_use/rust/service.py browser_use/rust/__init__.py browser_use/__init__.py tests/ci/test_rust_agent.py examples/rust_agent/basic.py examples/rust_agent/real_v8_smoke.py`
-- `uv run pytest -q tests/ci/test_rust_agent.py` (70 tests)
+- `uv run pytest -q tests/ci/test_rust_agent.py` (71 tests)
- `cargo build -q -p browser-use-cli`
- `CARGO_INCREMENTAL=0 cargo test -q -p browser-use-agent selected_remote_cdp_mode_allows_remote_cdp_connect -- --nocapture`
- `CARGO_INCREMENTAL=0 cargo test -q -p browser-use-agent bare_browser_connect_resolves_to_selected_managed_mode_with_launch_args -- --nocapture`
diff --git a/browser_use/rust/service.py b/browser_use/rust/service.py
index 32e460c38..abf4319aa 100644
--- a/browser_use/rust/service.py
+++ b/browser_use/rust/service.py
@@ -25,6 +25,7 @@ from browser_use.agent.message_manager.service import MessageManager
from browser_use.agent.prompts import SystemPrompt
from browser_use.agent.views import (
ActionResult,
+ AgentError,
AgentHistory,
AgentHistoryList,
AgentOutput,
@@ -1786,6 +1787,123 @@ class Agent(Generic[AgentStructuredOutput]):
"""Save current Browser Use file system state back onto AgentState."""
self.state.file_system_state = self.file_system.get_state()
+ async def _make_history_item(
+ self,
+ model_output: AgentOutput | None,
+ browser_state_summary: Any,
+ result: list[ActionResult],
+ metadata: StepMetadata | None = None,
+ state_message: str | None = None,
+ ) -> None:
+ """Create and store a Browser Use history item from a browser-state summary."""
+ if model_output:
+ selector_map = getattr(getattr(browser_state_summary, 'dom_state', None), 'selector_map', {})
+ interacted_elements = AgentHistory.get_interacted_element(model_output, selector_map)
+ else:
+ interacted_elements = [None]
+
+ screenshot_path = None
+ screenshot = getattr(browser_state_summary, 'screenshot', None)
+ if screenshot:
+ screenshot_path = await self.screenshot_service.store_screenshot(screenshot, self.state.n_steps)
+
+ state_history = BrowserStateHistory(
+ url=getattr(browser_state_summary, 'url', ''),
+ title=getattr(browser_state_summary, 'title', ''),
+ tabs=getattr(browser_state_summary, 'tabs', []),
+ interacted_element=interacted_elements,
+ screenshot_path=screenshot_path,
+ )
+ self.history.add_item(
+ AgentHistory(
+ model_output=model_output,
+ result=result,
+ state=state_history,
+ metadata=metadata,
+ state_message=state_message,
+ )
+ )
+
+ async def _post_process(self) -> None:
+ """Handle Browser Use-style post-action bookkeeping."""
+ await self._check_and_update_downloads('after executing actions')
+ if self.state.last_result and len(self.state.last_result) == 1 and self.state.last_result[-1].error:
+ self.state.consecutive_failures += 1
+ self.logger.debug(f'Step {self.state.n_steps}: Consecutive failures: {self.state.consecutive_failures}')
+ return
+ if self.state.consecutive_failures > 0:
+ self.state.consecutive_failures = 0
+ self.logger.debug(f'Step {self.state.n_steps}: Consecutive failures reset to: {self.state.consecutive_failures}')
+ if self.state.last_result and self.state.last_result[-1].is_done:
+ self.logger.info(f'\nFinal Result:\n{self.state.last_result[-1].extracted_content}\n')
+ if self.state.last_result[-1].attachments:
+ total_attachments = len(self.state.last_result[-1].attachments)
+ for index, file_path in enumerate(self.state.last_result[-1].attachments):
+ label = f'Attachment {index + 1}' if total_attachments > 1 else 'Attachment'
+ self.logger.info(f'{label}: {file_path}')
+
+ async def _handle_step_error(self, error: Exception) -> None:
+ """Convert a step exception into Browser Use-style state.last_result."""
+ if isinstance(error, InterruptedError):
+ self.logger.error('The agent was interrupted mid-step' + (f' - {error}' if str(error) else ''))
+ return
+ include_trace = self.logger.isEnabledFor(logging.DEBUG)
+ error_msg = AgentError.format_error(error, include_trace=include_trace)
+ self.state.consecutive_failures += 1
+ self.logger.error(
+ f'Result failed {self.state.consecutive_failures}/{self.settings.max_failures + int(self.settings.final_response_after_failure)} times:\n {error_msg}'
+ )
+ self.state.last_result = [ActionResult(error=error_msg)]
+
+ async def _finalize(self, browser_state_summary: Any | None) -> None:
+ """Finalize one Browser Use-style step after Rust-backed helper execution."""
+ step_end_time = time.time()
+ if not self.state.last_result:
+ return
+ if browser_state_summary is not None:
+ step_start_time = getattr(self, 'step_start_time', step_end_time)
+ metadata = StepMetadata(
+ step_number=self.state.n_steps,
+ step_start_time=step_start_time,
+ step_end_time=step_end_time,
+ )
+ state_message = getattr(self._message_manager, 'last_state_message_text', None)
+ await self._make_history_item(
+ self.state.last_model_output,
+ browser_state_summary,
+ self.state.last_result,
+ metadata,
+ state_message=state_message,
+ )
+ self._log_step_completion_summary(step_start_time, self.state.last_result)
+ self.save_file_system_state()
+ self.state.n_steps += 1
+
+ async def _force_done_after_last_step(self, step_info: AgentStepInfo | None = None) -> None:
+ """Switch to done-only output on the last configured step."""
+ if not (step_info and step_info.is_last_step()):
+ return
+ from browser_use.llm.messages import UserMessage
+
+ msg = 'You reached max_steps - this is your last step. Your only tool available is the "done" tool. No other tool is available.'
+ msg += '\nIf the task is not yet fully finished as requested by the user, set success in "done" to false. Else success to true.'
+ msg += '\nInclude everything you found out for the ultimate task in the done text.'
+ self._message_manager._add_context_message(UserMessage(content=msg))
+ self.AgentOutput = self.DoneAgentOutput
+
+ async def _force_done_after_failure(self) -> None:
+ """Switch to done-only output after max failures when final response is enabled."""
+ if self.state.consecutive_failures < self.settings.max_failures or not self.settings.final_response_after_failure:
+ return
+ from browser_use.llm.messages import UserMessage
+
+ msg = f'You failed {self.settings.max_failures} times. Therefore we terminate the agent.'
+ msg += '\nYour only tool available is the "done" tool. No other tool is available.'
+ msg += '\nIf the task is not yet fully finished as requested by the user, set success in "done" to false. Else success to true.'
+ msg += '\nInclude everything you found out for the ultimate task in the done text.'
+ self._message_manager._add_context_message(UserMessage(content=msg))
+ self.AgentOutput = self.DoneAgentOutput
+
async def step(self, step_info: AgentStepInfo | None = None) -> None:
"""Execute one Browser Use-style step through the Rust terminal core."""
await self.take_step(step_info)
diff --git a/tests/ci/test_rust_agent.py b/tests/ci/test_rust_agent.py
index b675af28c..b16a100ec 100644
--- a/tests/ci/test_rust_agent.py
+++ b/tests/ci/test_rust_agent.py
@@ -1008,6 +1008,57 @@ async def test_rust_agent_exposes_logging_helper_methods(monkeypatch):
assert captured_events[0].error_message == 'manual-error'
+async def test_rust_agent_exposes_step_finalization_helper_methods(tmp_path):
+ import base64
+ import time
+
+ from browser_use.agent.views import ActionResult, AgentStepInfo
+ from browser_use.rust import Agent
+
+ class DomState:
+ selector_map = {}
+
+ class BrowserStateSummary:
+ url = 'https://example.com/final'
+ title = 'Final'
+ tabs = []
+ screenshot = base64.b64encode(b'png-bytes').decode('utf-8')
+ dom_state = DomState()
+
+ agent = Agent(task='Finalize helper parity.', file_system_path=str(tmp_path / 'agent-files'))
+
+ await agent._handle_step_error(ValueError('bad step'))
+ assert agent.state.consecutive_failures == 1
+ assert agent.state.last_result is not None
+ assert agent.state.last_result[-1].error == 'bad step'
+
+ await agent._post_process()
+ assert agent.state.consecutive_failures == 2
+
+ agent.state.last_result = [
+ ActionResult(is_done=True, success=True, extracted_content='final answer', attachments=['file:///tmp/report.txt'])
+ ]
+ await agent._post_process()
+ assert agent.state.consecutive_failures == 0
+
+ agent.step_start_time = time.time() - 0.1
+ await agent._finalize(BrowserStateSummary())
+
+ assert agent.state.n_steps == 2
+ assert agent.state.file_system_state is not None
+ assert agent.history.final_result() == 'final answer'
+ assert agent.history.urls() == ['https://example.com/final']
+ assert Path(agent.history.history[0].state.screenshot_path).read_bytes() == b'png-bytes'
+
+ await agent._force_done_after_last_step(AgentStepInfo(step_number=2, max_steps=3))
+ assert agent.AgentOutput is agent.DoneAgentOutput
+
+ agent.state.consecutive_failures = agent.settings.max_failures
+ agent.AgentOutput = None
+ await agent._force_done_after_failure()
+ assert agent.AgentOutput is agent.DoneAgentOutput
+
+
def test_rust_agent_initializes_message_manager_and_followup_state():
from browser_use.agent.message_manager.service import MessageManager
from browser_use.rust import Agent