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
Add Rust-backed Browser Use agent wrapper
Magnus Müllerdc4318875b2f
diff --git a/browser_use/__init__.py b/browser_use/__init__.pyindex 377586856..45b0cfdc4 100644--- a/browser_use/__init__.py+++ b/browser_use/__init__.py@@ -46,7 +46,7 @@ base_subprocess.BaseSubprocessTransport.__del__ = _patched_del# Type stubs for lazy imports - fixes linter warningsif TYPE_CHECKING:from browser_use.agent.prompts import SystemPrompt- from browser_use.agent.service import Agent+ from browser_use.rust.service import Agent# from browser_use.agent.service import Agentfrom browser_use.agent.views import ActionModel, ActionResult, AgentHistoryList@@ -72,7 +72,7 @@ _LAZY_IMPORTS = {# 'Agent': ('browser_use.agent.service', 'Agent'),# Code-use agent (Jupyter notebook-like execution)'CodeAgent': ('browser_use.code_use.service', 'CodeAgent'),- 'Agent': ('browser_use.agent.service', 'Agent'),+ 'Agent': ('browser_use.rust.service', 'Agent'),# System prompt (moderate weight due to agent.views imports)'SystemPrompt': ('browser_use.agent.prompts', 'SystemPrompt'),# Agent views (very heavy - over 1 second!)diff --git a/browser_use/rust/__init__.py b/browser_use/rust/__init__.pynew file mode 100644index 000000000..be6813883--- /dev/null+++ b/browser_use/rust/__init__.py@@ -0,0 +1,10 @@+"""Rust-core Browser Use integration."""++from browser_use.rust.service import Agent, RustAgentError, find_browser_use_terminal_binary++__all__ = [+ 'Agent',+ 'RustAgentError',+ 'find_browser_use_terminal_binary',+]+diff --git a/browser_use/rust/service.py b/browser_use/rust/service.pynew file mode 100644index 000000000..629a8dc4c--- /dev/null+++ b/browser_use/rust/service.py@@ -0,0 +1,403 @@+from __future__ import annotations++import asyncio+import json+import os+import shutil+import time+from collections.abc import Awaitable, Callable+from pathlib import Path+from typing import Any, Generic++from pydantic import BaseModel+from typing_extensions import TypeVar++from browser_use.agent.views import ActionResult, AgentHistory, AgentHistoryList, StepMetadata+from browser_use.browser import BrowserProfile, BrowserSession+from browser_use.browser.views import BrowserStateHistory, TabInfo+from browser_use.tokens.views import ModelUsageStats, UsageSummary+++AgentStructuredOutput = TypeVar('AgentStructuredOutput', bound=BaseModel)+AgentHookFunc = Callable[[AgentHistoryList], Awaitable[None] | None]+++class RustAgentError(RuntimeError):+ """Raised when the Rust terminal core cannot run a task."""+++def find_browser_use_terminal_binary() -> str:+ """Find the terminal binary used by the Rust-backed Browser Use Agent."""+ env_path = os.environ.get('BROWSER_USE_TERMINAL_BINARY')+ if env_path:+ return env_path+ path_binary = shutil.which('browser-use-terminal')+ if path_binary:+ return path_binary+ candidates = [+ Path.cwd() / 'target' / 'debug' / 'browser-use-terminal',+ Path.cwd().parent / 'terminal' / 'target' / 'debug' / 'browser-use-terminal',+ Path('/home/exedev/Developer/terminal/target/debug/browser-use-terminal'),+ ]+ for candidate in candidates:+ if candidate.exists():+ return str(candidate)+ raise RustAgentError(+ 'Could not find browser-use-terminal. Set BROWSER_USE_TERMINAL_BINARY or build the terminal CLI.'+ )+++def _model_name(llm: Any | None) -> str:+ for attr in ('model', 'model_name', 'name'):+ value = getattr(llm, attr, None)+ if isinstance(value, str) and value:+ return value+ return os.environ.get('BROWSER_USE_RUST_MODEL', 'gpt-5.1-codex')+++def _extract_cdp_url(browser_session: BrowserSession | None) -> str | None:+ if browser_session is None:+ return None+ for attr in ('cdp_url',):+ value = getattr(browser_session, attr, None)+ if isinstance(value, str) and value:+ return value+ profile = getattr(browser_session, 'browser_profile', None)+ value = getattr(profile, 'cdp_url', None)+ if isinstance(value, str) and value:+ return value+ return None+++def _initial_navigation_url(initial_actions: Any) -> str | None:+ if not isinstance(initial_actions, list):+ return None+ for action in initial_actions:+ if not isinstance(action, dict):+ continue+ for name, payload in action.items():+ if name in ('open_tab', 'go_to_url', 'navigate') and isinstance(payload, dict):+ url = payload.get('url')+ if isinstance(url, str) and url:+ return url+ return None+++def _task_with_initial_navigation(task: str, initial_actions: Any) -> str:+ url = _initial_navigation_url(initial_actions)+ if not url:+ return task+ return f'First navigate to {url!r}, then complete the task.\n\n{task}'+++def _task_with_schema(task: str, output_model_schema: type[BaseModel] | None) -> str:+ if output_model_schema is None:+ return task+ schema = json.dumps(output_model_schema.model_json_schema(), indent=2)+ return f'{task}\n\nExpected output JSON schema for the final answer:\n{schema}'+++def _event_type(event: dict[str, Any]) -> str:+ return str(event.get('event_type') or event.get('type') or '')+++def _event_payload(event: dict[str, Any]) -> dict[str, Any]:+ payload = event.get('payload')+ return payload if isinstance(payload, dict) else {}+++def _result_from_events(events: list[dict[str, Any]]) -> str | None:+ for event in reversed(events):+ if _event_type(event) != 'session.done':+ continue+ payload = _event_payload(event)+ result = payload.get('result')+ if isinstance(result, str) and result.strip():+ return result.strip()+ result_file = payload.get('result_file_url') or payload.get('result_file_path') or payload.get('result_file')+ if isinstance(result_file, str) and result_file:+ return f'Saved result file.\n\nFile:\n{result_file}'+ return None+++def _failure_from_events(events: list[dict[str, Any]]) -> str | None:+ for event in reversed(events):+ if _event_type(event) == 'session.failed':+ error = _event_payload(event).get('error')+ if isinstance(error, str) and error:+ return error+ return None+++def _browser_state_from_events(events: list[dict[str, Any]]) -> BrowserStateHistory:+ url = ''+ title = ''+ tabs: list[TabInfo] = []+ for event in events:+ if _event_type(event) not in ('browser.connected', 'browser.reconnected', 'browser.target_changed', 'browser.page', 'browser.state'):+ continue+ payload = _event_payload(event)+ url = str(payload.get('url') or url)+ title = str(payload.get('title') or title)+ raw_tabs = payload.get('tabs')+ if isinstance(raw_tabs, list):+ next_tabs = []+ for idx, raw in enumerate(raw_tabs):+ if isinstance(raw, dict):+ next_tabs.append(+ TabInfo(+ url=str(raw.get('url') or ''),+ title=str(raw.get('title') or ''),+ target_id=str(raw.get('target_id') or raw.get('tab_id') or f'tab-{idx}'),+ )+ )+ if next_tabs:+ tabs = next_tabs+ if not tabs and (url or title):+ tabs = [TabInfo(url=url, title=title, target_id='tab-0')]+ return BrowserStateHistory(url=url, title=title, tabs=tabs, interacted_element=[])+++def _usage_from_events(events: list[dict[str, Any]], model: str) -> UsageSummary:+ input_tokens = 0+ cached_input_tokens = 0+ output_tokens = 0+ cost = 0.0+ invocations = 0++ for event in events:+ if _event_type(event) != 'model.usage':+ continue+ payload = _event_payload(event)+ input_tokens += int(payload.get('input_tokens') or 0)+ cached_input_tokens += int(payload.get('input_cached_tokens') or payload.get('cached_input_tokens') or 0)+ output_tokens += int(payload.get('output_tokens') or 0)+ cost += float(payload.get('cost_usd') or payload.get('cost') or 0.0)+ invocations += 1++ total_tokens = input_tokens + output_tokens+ by_model = {+ model: ModelUsageStats(+ model=model,+ prompt_tokens=input_tokens,+ completion_tokens=output_tokens,+ total_tokens=total_tokens,+ cost=cost,+ invocations=invocations,+ )+ }+ return UsageSummary(+ total_prompt_tokens=input_tokens,+ total_prompt_cost=0.0,+ total_prompt_cached_tokens=cached_input_tokens,+ total_prompt_cached_cost=0.0,+ total_completion_tokens=output_tokens,+ total_completion_cost=0.0,+ total_tokens=total_tokens,+ total_cost=cost,+ entry_count=invocations,+ by_model=by_model,+ )+++def _history_from_events(+ events: list[dict[str, Any]],+ *,+ model: str,+ started: float,+ finished: float,+ output_model_schema: type[AgentStructuredOutput] | None,+ process_error: str | None,+) -> AgentHistoryList[AgentStructuredOutput]:+ final_result = _result_from_events(events)+ failure = process_error or _failure_from_events(events)+ is_done = final_result is not None and failure is None+ result = ActionResult(+ is_done=is_done,+ success=True if is_done else None,+ error=failure,+ extracted_content=final_result,+ )+ history = AgentHistory(+ model_output=None,+ result=[result],+ state=_browser_state_from_events(events),+ metadata=StepMetadata(step_start_time=started, step_end_time=finished, step_number=max(1, len(events))),+ )+ history_list: AgentHistoryList[AgentStructuredOutput] = AgentHistoryList(+ history=[history],+ usage=_usage_from_events(events, model),+ )+ history_list._output_model_schema = output_model_schema+ return history_list+++class Agent(Generic[AgentStructuredOutput]):+ """Browser Use-style Agent backed by the Rust browser-use-terminal core."""++ def __init__(+ self,+ task: str,+ llm: Any | None = None,+ browser_profile: BrowserProfile | None = None,+ browser_session: BrowserSession | None = None,+ browser: BrowserSession | None = None,+ tools: Any | None = None,+ controller: Any | None = None,+ initial_actions: list[dict[str, dict[str, Any]]] | None = None,+ output_model_schema: type[AgentStructuredOutput] | None = None,+ task_id: str | None = None,+ source: str | None = None,+ **kwargs: Any,+ ) -> None:+ if browser and browser_session:+ raise ValueError('Cannot specify both "browser" and "browser_session".')+ if tools is not None and controller is not None:+ raise ValueError('Cannot specify both "tools" and "controller".')+ self.task = _task_with_schema(_task_with_initial_navigation(task, initial_actions), output_model_schema)+ self.llm = llm+ self.browser_profile = browser_profile+ self.browser_session = browser or browser_session+ self.tools = controller or tools+ self.output_model_schema = output_model_schema+ self.task_id = task_id+ self.source = source+ self.kwargs = kwargs+ self.model = _model_name(llm)+ self.session_id: str | None = None+ self.history: AgentHistoryList[AgentStructuredOutput] = AgentHistoryList(history=[], usage=None)+ self.result: AgentHistoryList[AgentStructuredOutput] | None = None+ self.last_events: list[dict[str, Any]] = []++ async def run(+ self,+ max_steps: int = 100,+ on_step_start: AgentHookFunc | None = None,+ on_step_end: AgentHookFunc | None = None,+ ) -> AgentHistoryList[AgentStructuredOutput]:+ _ = on_step_start+ started = time.time()+ proc = await asyncio.create_subprocess_exec(+ *self._run_argv(max_steps),+ stdout=asyncio.subprocess.PIPE,+ stderr=asyncio.subprocess.PIPE,+ env=self._run_env(),+ )+ stdout, stderr = await proc.communicate()+ finished = time.time()+ stdout_text = stdout.decode(errors='replace')+ stderr_text = stderr.decode(errors='replace')+ self.session_id = self._session_id_from_stdout(stdout_text)+ events = await self._load_events()+ process_error = None+ if proc.returncode:+ process_error = stderr_text.strip() or f'browser-use-terminal exited with code {proc.returncode}'+ self.last_events = events+ self.result = _history_from_events(+ events,+ model=self.model,+ started=started,+ finished=finished,+ output_model_schema=self.output_model_schema,+ process_error=process_error,+ )+ self.history = self.result+ if on_step_end is not None:+ maybe_awaitable = on_step_end(self.history)+ if maybe_awaitable is not None:+ await maybe_awaitable+ return self.history++ async def follow_up(self, task: str) -> AgentHistoryList[AgentStructuredOutput]:+ if not self.session_id:+ raise RustAgentError('No active Rust session. Call run() before follow_up().')+ binary = find_browser_use_terminal_binary()+ proc = await asyncio.create_subprocess_exec(+ binary,+ *self._state_dir_args(),+ 'followup',+ self.session_id,+ task,+ stdout=asyncio.subprocess.PIPE,+ stderr=asyncio.subprocess.PIPE,+ env=self._run_env(),+ )+ stdout, stderr = await proc.communicate()+ if proc.returncode:+ raise RustAgentError(stderr.decode(errors='replace') or stdout.decode(errors='replace'))+ return await self.run(max_steps=self.kwargs.get('max_steps', 100))++ follow_up_task = follow_up++ @property+ def usage(self) -> UsageSummary | None:+ return self.history.usage++ def _run_argv(self, max_steps: int) -> list[str]:+ binary = find_browser_use_terminal_binary()+ return [+ binary,+ *self._state_dir_args(),+ '-c',+ f'max_turns={int(max_steps)}',+ '-c',+ f'browser_mode="{self._browser_mode()}"',+ 'run-codex',+ self.task,+ '--model',+ self.model,+ ]++ def _state_dir_args(self) -> list[str]:+ state_dir = os.environ.get('BROWSER_USE_RUST_STATE_DIR')+ return ['--state-dir', state_dir] if state_dir else []++ def _browser_mode(self) -> str:+ if _extract_cdp_url(self.browser_session):+ return 'managed-headless'+ value = os.environ.get('BROWSER_USE_RUST_BROWSER_MODE')+ if value:+ return value+ if self.browser_profile and getattr(self.browser_profile, 'cdp_url', None):+ return 'managed-headless'+ return os.environ.get('BROWSER_USE_BROWSER_MODE', 'managed-headless')++ def _run_env(self) -> dict[str, str]:+ env = os.environ.copy()+ cdp_url = _extract_cdp_url(self.browser_session)+ if cdp_url:+ env['BU_CDP_URL'] = cdp_url+ return env++ def _session_id_from_stdout(self, stdout: str) -> str | None:+ for line in reversed(stdout.splitlines()):+ token = line.strip().split()[-1:] or ['']+ candidate = token[0]+ if len(candidate) >= 8 and all(ch in '0123456789abcdef-' for ch in candidate.lower()):+ return candidate+ return None++ async def _load_events(self) -> list[dict[str, Any]]:+ if not self.session_id:+ return []+ binary = find_browser_use_terminal_binary()+ proc = await asyncio.create_subprocess_exec(+ binary,+ *self._state_dir_args(),+ 'events',+ self.session_id,+ stdout=asyncio.subprocess.PIPE,+ stderr=asyncio.subprocess.PIPE,+ env=self._run_env(),+ )+ stdout, _stderr = await proc.communicate()+ events = []+ for line in stdout.decode(errors='replace').splitlines():+ try:+ parsed = json.loads(line)+ except json.JSONDecodeError:+ continue+ if isinstance(parsed, dict):+ events.append(parsed)+ return events+diff --git a/tests/ci/test_rust_agent.py b/tests/ci/test_rust_agent.pynew file mode 100644index 000000000..6744e0152--- /dev/null+++ b/tests/ci/test_rust_agent.py@@ -0,0 +1,114 @@+from __future__ import annotations++from pydantic import BaseModel+++def test_top_level_agent_uses_rust_wrapper():+ from browser_use import Agent as TopLevelAgent+ from browser_use.rust import Agent as RustAgent++ assert TopLevelAgent is RustAgent+++def test_rust_events_reconstruct_browser_use_history():+ from browser_use.rust.service import _history_from_events++ events = [+ {+ 'event_type': 'browser.state',+ 'payload': {'url': 'https://example.com', 'title': 'Example'},+ },+ {+ 'event_type': 'model.usage',+ 'payload': {'input_tokens': 11, 'cached_input_tokens': 3, 'output_tokens': 7, 'cost_usd': 0.12},+ },+ {+ 'event_type': 'session.done',+ 'payload': {'result': 'final answer'},+ },+ ]++ history = _history_from_events(+ events,+ model='gpt-test',+ started=1.0,+ finished=2.5,+ output_model_schema=None,+ process_error=None,+ )++ assert history.final_result() == 'final answer'+ assert history.is_done() is True+ assert history.is_successful() is True+ assert history.urls() == ['https://example.com']+ assert history.usage is not None+ assert history.usage.total_prompt_tokens == 11+ assert history.usage.total_prompt_cached_tokens == 3+ assert history.usage.total_completion_tokens == 7+++def test_rust_history_supports_structured_output():+ from browser_use.rust.service import _history_from_events++ class Answer(BaseModel):+ answer: str++ history = _history_from_events(+ [{'event_type': 'session.done', 'payload': {'result': '{"answer": "ok"}'}}],+ model='gpt-test',+ started=1.0,+ finished=2.0,+ output_model_schema=Answer,+ process_error=None,+ )++ assert isinstance(history.structured_output, Answer)+ assert history.structured_output.answer == 'ok'+++def test_rust_agent_translates_browser_use_args_to_terminal(monkeypatch):+ from browser_use.rust import Agent++ class LLM:+ model = 'gpt-test'++ class Browser:+ cdp_url = 'wss://browser.example/devtools/browser/1'++ monkeypatch.setenv('BROWSER_USE_TERMINAL_BINARY', '/tmp/browser-use-terminal')+ agent = Agent(+ task='report title',+ llm=LLM(),+ browser_session=Browser(),+ initial_actions=[{'go_to_url': {'url': 'https://example.com'}}],+ )++ argv = agent._run_argv(max_steps=12)+ env = agent._run_env()++ assert argv[0] == '/tmp/browser-use-terminal'+ assert argv[-4:] == ['run-codex', agent.task, '--model', 'gpt-test']+ assert '-c' in argv+ assert 'max_turns=12' in argv+ assert 'browser_mode="managed-headless"' in argv+ assert "First navigate to 'https://example.com'" in agent.task+ assert env['BU_CDP_URL'] == 'wss://browser.example/devtools/browser/1'+++def test_rust_history_marks_process_failure_not_done():+ from browser_use.rust.service import _history_from_events++ history = _history_from_events(+ [],+ model='gpt-test',+ started=1.0,+ finished=2.0,+ output_model_schema=None,+ process_error='terminal failed',+ )++ assert history.final_result() is None+ assert history.is_done() is False+ assert history.is_successful() is None+ assert history.errors() == ['terminal failed']+