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 lifecycle helpers

Magnus Müller4ee73118fc5f
diff --git a/RUST_AGENT_INTEGRATION_FEATURES.md b/RUST_AGENT_INTEGRATION_FEATURES.md
index 503863aff..98dae8716 100644
--- a/RUST_AGENT_INTEGRATION_FEATURES.md
+++ b/RUST_AGENT_INTEGRATION_FEATURES.md
@@ -42,10 +42,15 @@ Terminal core branch: `magnus/browser-use-rust-integration` at latest pulled mai
- Proof: `test_real_v8_smoke_selects_case_by_index_and_task_id`.
- Proof: remote-CDP e2e smoke on real_v8 `task_id=18` returned `Paramjit Uppal, Founder`.
+8. Browser Use lifecycle helpers
+ - The Rust-backed `Agent` now supports Browser Use-style `on_step_start`, `on_step_end`, `register_done_callback`, `run_sync()`, `save_history()`, `pause()`, `resume()`, `stop()`, `close()`, and `add_new_task()`.
+ - The run hooks receive the agent object, matching the Python Agent API, and the done callback receives the reconstructed `AgentHistoryList`.
+ - Proof: `test_rust_agent_invokes_browser_use_style_callbacks`, `test_rust_agent_run_sync_delegates_to_async_run`, and `test_rust_agent_lifecycle_state_and_save_history`.
+
## 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`
+- `uv run pytest -q tests/ci/test_rust_agent.py` (12 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`
- Managed-headless end-to-end:
diff --git a/browser_use/rust/service.py b/browser_use/rust/service.py
index e504d347f..412c71750 100644
--- a/browser_use/rust/service.py
+++ b/browser_use/rust/service.py
@@ -1,6 +1,7 @@
from __future__ import annotations
import asyncio
+import inspect
import json
import os
import shutil
@@ -11,15 +12,17 @@ from typing import Any, Generic
from pydantic import BaseModel
from typing_extensions import TypeVar
+from uuid_extensions import uuid7str
-from browser_use.agent.views import ActionResult, AgentHistory, AgentHistoryList, StepMetadata
+from browser_use.agent.views import ActionResult, AgentHistory, AgentHistoryList, AgentState, 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]
+AgentHookFunc = Callable[[Any], Awaitable[None] | None]
+AgentDoneCallback = Callable[[AgentHistoryList], Awaitable[None] | None]
class RustAgentError(RuntimeError):
@@ -246,8 +249,13 @@ class Agent(Generic[AgentStructuredOutput]):
browser: BrowserSession | None = None,
tools: Any | None = None,
controller: Any | None = None,
+ sensitive_data: dict[str, str | dict[str, str]] | None = None,
initial_actions: list[dict[str, dict[str, Any]]] | None = None,
+ register_done_callback: AgentDoneCallback | None = None,
+ register_external_agent_status_raise_error_callback: Callable[[], Awaitable[bool]] | None = None,
+ register_should_stop_callback: Callable[[], Awaitable[bool]] | None = None,
output_model_schema: type[AgentStructuredOutput] | None = None,
+ injected_agent_state: AgentState | None = None,
task_id: str | None = None,
source: str | None = None,
**kwargs: Any,
@@ -256,22 +264,30 @@ class Agent(Generic[AgentStructuredOutput]):
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.id = task_id or uuid7str()
+ self.task_id = self.id
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.sensitive_data = sensitive_data
+ self.register_done_callback = register_done_callback
+ self.register_external_agent_status_raise_error_callback = register_external_agent_status_raise_error_callback
+ self.register_should_stop_callback = register_should_stop_callback
self.output_model_schema = output_model_schema
- self.task_id = task_id
self.source = source
self.kwargs = kwargs
self.model = _model_name(llm)
+ self.state = injected_agent_state or AgentState(agent_id=self.id)
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]] = []
self.last_stdout = ''
self.last_stderr = ''
+ self._external_pause_event = asyncio.Event()
+ self._external_pause_event.set()
async def run(
self,
@@ -279,25 +295,47 @@ class Agent(Generic[AgentStructuredOutput]):
on_step_start: AgentHookFunc | None = None,
on_step_end: AgentHookFunc | None = None,
) -> AgentHistoryList[AgentStructuredOutput]:
- _ = on_step_start
+ await self._call_callback(on_step_start, self)
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()
+ if await self._should_stop_before_run():
+ finished = time.time()
+ self.result = _history_from_events(
+ [],
+ model=self.model,
+ started=started,
+ finished=finished,
+ output_model_schema=self.output_model_schema,
+ process_error='Rust agent stopped before terminal run.',
+ )
+ self.history = self.result
+ await self._call_callback(on_step_end, self)
+ return self.history
+ if self.state.paused:
+ finished = time.time()
+ self.result = _history_from_events(
+ [],
+ model=self.model,
+ started=started,
+ finished=finished,
+ output_model_schema=self.output_model_schema,
+ process_error='Rust agent is paused before terminal run.',
+ )
+ self.history = self.result
+ await self._call_callback(on_step_end, self)
+ return self.history
+ if self.state.follow_up_task and self.session_id:
+ self.state.follow_up_task = False
+ return await self.follow_up(self.task, max_steps=max_steps)
+
+ returncode, stdout_text, stderr_text = await self._run_process(self._run_argv(max_steps))
finished = time.time()
- stdout_text = stdout.decode(errors='replace')
- stderr_text = stderr.decode(errors='replace')
self.last_stdout = stdout_text
self.last_stderr = stderr_text
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}'
+ if returncode:
+ process_error = stderr_text.strip() or f'browser-use-terminal exited with code {returncode}'
elif not self.session_id:
process_error = 'browser-use-terminal did not print a session id.'
self.last_events = events
@@ -310,41 +348,27 @@ class Agent(Generic[AgentStructuredOutput]):
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
+ await self._call_callback(on_step_end, self)
+ await self._call_done_callback()
return self.history
- async def follow_up(self, task: str) -> AgentHistoryList[AgentStructuredOutput]:
+ async def follow_up(self, task: str, max_steps: int | None = None) -> AgentHistoryList[AgentStructuredOutput]:
if not self.session_id:
raise RustAgentError('No active Rust session. Call run() before follow_up().')
started = time.time()
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(),
+ returncode, stdout_text, stderr_text = await self._run_process(
+ [binary, *self._state_dir_args(), 'followup', self.session_id, task]
)
- stdout, stderr = await proc.communicate()
- if proc.returncode:
- raise RustAgentError(stderr.decode(errors='replace') or stdout.decode(errors='replace'))
- proc = await asyncio.create_subprocess_exec(
- *self._run_existing_argv(self.kwargs.get('max_steps', 100)),
- stdout=asyncio.subprocess.PIPE,
- stderr=asyncio.subprocess.PIPE,
- env=self._run_env(),
+ if returncode:
+ raise RustAgentError(stderr_text or stdout_text)
+ returncode, _stdout_text, stderr_text = await self._run_process(
+ self._run_existing_argv(max_steps if max_steps is not None else self.kwargs.get('max_steps', 100))
)
- stdout, stderr = await proc.communicate()
finished = time.time()
process_error = None
- if proc.returncode:
- process_error = stderr.decode(errors='replace').strip() or f'browser-use-terminal exited with code {proc.returncode}'
+ if returncode:
+ process_error = stderr_text.strip() or f'browser-use-terminal exited with code {returncode}'
self.last_events = await self._load_events()
self.result = _history_from_events(
self.last_events,
@@ -355,6 +379,7 @@ class Agent(Generic[AgentStructuredOutput]):
process_error=process_error,
)
self.history = self.result
+ await self._call_done_callback()
return self.history
follow_up_task = follow_up
@@ -363,6 +388,52 @@ class Agent(Generic[AgentStructuredOutput]):
def usage(self) -> UsageSummary | None:
return self.history.usage
+ def add_new_task(self, new_task: str) -> None:
+ """Add a follow-up task while keeping the same Browser Use-style agent object."""
+ self.task = _task_with_schema(new_task, self.output_model_schema)
+ self.state.follow_up_task = True
+ self.state.stopped = False
+ self.state.paused = False
+ self._external_pause_event.set()
+
+ def save_history(self, file_path: str | Path | None = None) -> None:
+ """Save the current Browser Use history to disk."""
+ if not file_path:
+ file_path = 'AgentHistory.json'
+ self.history.save_to_file(file_path, sensitive_data=self.sensitive_data)
+
+ def pause(self) -> None:
+ """Pause the Rust-backed agent before the next terminal run."""
+ self.state.paused = True
+ self._external_pause_event.clear()
+
+ def resume(self) -> None:
+ """Resume a paused Rust-backed agent."""
+ self.state.paused = False
+ self._external_pause_event.set()
+
+ def stop(self) -> None:
+ """Stop the Rust-backed agent before the next terminal run."""
+ self.state.stopped = True
+ self._external_pause_event.set()
+
+ async def close(self) -> None:
+ """Browser Use-compatible close hook.
+
+ The Rust terminal owns browser lifecycle for managed modes, and remote CDP
+ browsers are owned by the caller, so the Python wrapper has nothing to close.
+ """
+ return None
+
+ def run_sync(
+ self,
+ max_steps: int = 100,
+ on_step_start: AgentHookFunc | None = None,
+ on_step_end: AgentHookFunc | None = None,
+ ) -> AgentHistoryList[AgentStructuredOutput]:
+ """Synchronous wrapper around the async run method."""
+ return asyncio.run(self.run(max_steps=max_steps, on_step_start=on_step_start, on_step_end=on_step_end))
+
def _run_argv(self, max_steps: int) -> list[str]:
binary = find_browser_use_terminal_binary()
return [
@@ -378,6 +449,49 @@ class Agent(Generic[AgentStructuredOutput]):
self.model,
]
+ async def _run_process(self, argv: list[str]) -> tuple[int, str, str]:
+ proc = await asyncio.create_subprocess_exec(
+ *argv,
+ stdout=asyncio.subprocess.PIPE,
+ stderr=asyncio.subprocess.PIPE,
+ env=self._run_env(),
+ )
+ stdout, stderr = await proc.communicate()
+ return proc.returncode or 0, stdout.decode(errors='replace'), stderr.decode(errors='replace')
+
+ async def _call_callback(self, callback: AgentHookFunc | None, *args: Any) -> None:
+ if callback is None:
+ return
+ result = callback(*args)
+ if inspect.isawaitable(result):
+ await result
+
+ async def _call_done_callback(self) -> None:
+ if self.register_done_callback is None or not self.history.is_done():
+ return
+ result = self.register_done_callback(self.history)
+ if inspect.isawaitable(result):
+ await result
+
+ async def _should_stop_before_run(self) -> bool:
+ if self.state.stopped:
+ return True
+ if self.register_should_stop_callback is not None:
+ should_stop = self.register_should_stop_callback()
+ if inspect.isawaitable(should_stop):
+ should_stop = await should_stop
+ if should_stop:
+ self.state.stopped = True
+ return True
+ if self.register_external_agent_status_raise_error_callback is not None:
+ should_stop = self.register_external_agent_status_raise_error_callback()
+ if inspect.isawaitable(should_stop):
+ should_stop = await should_stop
+ if should_stop:
+ self.state.stopped = True
+ return True
+ return False
+
def _run_existing_argv(self, max_steps: int) -> list[str]:
if not self.session_id:
raise RustAgentError('No active Rust session. Call run() before rerunning an existing session.')
diff --git a/tests/ci/test_rust_agent.py b/tests/ci/test_rust_agent.py
index 24f13c33a..e0f4068a8 100644
--- a/tests/ci/test_rust_agent.py
+++ b/tests/ci/test_rust_agent.py
@@ -133,6 +133,85 @@ def test_rust_agent_translates_followup_to_existing_terminal_session(monkeypatch
assert 'max_turns=9' in argv
+async def test_rust_agent_invokes_browser_use_style_callbacks(monkeypatch):
+ from browser_use.rust import Agent
+
+ monkeypatch.setenv('BROWSER_USE_TERMINAL_BINARY', '/tmp/browser-use-terminal')
+ seen = []
+
+ def done_callback(history):
+ seen.append(('done', history.final_result()))
+
+ agent = Agent(task='start', llm=type('LLM', (), {'model': 'gpt-test'})(), register_done_callback=done_callback)
+
+ async def fake_run_process(argv):
+ seen.append(('argv', argv[-4]))
+ return 0, 'Session: 12345678-1234-1234-1234-123456789abc\n', ''
+
+ async def fake_load_events():
+ return [{'event_type': 'session.done', 'payload': {'result': 'ok'}}]
+
+ async def on_step_start(callback_agent):
+ seen.append(('start', callback_agent is agent))
+
+ def on_step_end(callback_agent):
+ seen.append(('end', callback_agent is agent))
+
+ agent._run_process = fake_run_process
+ agent._load_events = fake_load_events
+
+ history = await agent.run(max_steps=3, on_step_start=on_step_start, on_step_end=on_step_end)
+
+ assert history.final_result() == 'ok'
+ assert seen == [
+ ('start', True),
+ ('argv', 'run-codex'),
+ ('end', True),
+ ('done', 'ok'),
+ ]
+
+
+def test_rust_agent_run_sync_delegates_to_async_run(monkeypatch):
+ from browser_use.rust import Agent
+
+ agent = Agent(task='start')
+
+ async def fake_run(max_steps=100, on_step_start=None, on_step_end=None):
+ agent.kwargs['seen_max_steps'] = max_steps
+ return agent.history
+
+ agent.run = fake_run
+
+ assert agent.run_sync(max_steps=7) is agent.history
+ assert agent.kwargs['seen_max_steps'] == 7
+
+
+def test_rust_agent_lifecycle_state_and_save_history(tmp_path):
+ from browser_use.rust import Agent
+ from browser_use.rust.service import _history_from_events
+
+ agent = Agent(task='start')
+ agent.pause()
+ assert agent.state.paused is True
+ agent.resume()
+ assert agent.state.paused is False
+ agent.stop()
+ assert agent.state.stopped is True
+
+ agent.history = _history_from_events(
+ [{'event_type': 'session.done', 'payload': {'result': 'saved answer'}}],
+ model='gpt-test',
+ started=1.0,
+ finished=2.0,
+ output_model_schema=None,
+ process_error=None,
+ )
+ history_file = tmp_path / 'history.json'
+ agent.save_history(history_file)
+
+ assert 'saved answer' in history_file.read_text(encoding='utf-8')
+
+
def test_rust_history_marks_process_failure_not_done():
from browser_use.rust.service import _history_from_events