Skip to content

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

Add Rust-backed Browser Use agent wrapper

Magnus Müllerdc4318875b2f
diff --git a/browser_use/__init__.py b/browser_use/__init__.py
index 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 warnings
if 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 Agent
from 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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']
+