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 trace callbacks

Magnus Müller99b17621387c
diff --git a/RUST_AGENT_INTEGRATION_FEATURES.md b/RUST_AGENT_INTEGRATION_FEATURES.md
index ee06697e5..ebedf5a39 100644
--- a/RUST_AGENT_INTEGRATION_FEATURES.md
+++ b/RUST_AGENT_INTEGRATION_FEATURES.md
@@ -54,10 +54,16 @@ Terminal core branch: `magnus/browser-use-rust-integration` at latest pulled mai
- Ambiguous multi-URL tasks and file-like URLs are left untouched.
- Proof: `test_rust_agent_mirrors_direct_url_startup`, `test_rust_agent_skips_ambiguous_or_excluded_direct_urls`, and `test_rust_agent_exposes_browser_use_settings`.
+10. Trace and step callback helpers
+ - The Rust-backed `Agent` now supports `register_new_step_callback`, `get_trace_object()`, and `authenticate_cloud_sync()`.
+ - The step callback is invoked from reconstructed Rust terminal history with browser state, `None` for Python-only model output, and the reconstructed step number.
+ - `get_trace_object()` returns Browser Use-style `trace` and `trace_details` dictionaries from the reconstructed history.
+ - Proof: `test_rust_agent_invokes_new_step_callback` and `test_rust_agent_trace_and_cloud_auth_helpers`.
+
## 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` (16 tests)
+- `uv run pytest -q tests/ci/test_rust_agent.py` (18 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 e9b679c2a..752f94cbb 100644
--- a/browser_use/rust/service.py
+++ b/browser_use/rust/service.py
@@ -8,6 +8,7 @@ import re
import shutil
import time
from collections.abc import Awaitable, Callable
+from datetime import datetime
from pathlib import Path
from typing import Any, Generic, Literal
@@ -507,6 +508,7 @@ class Agent(Generic[AgentStructuredOutput]):
process_error=process_error,
)
self.history = self.result
+ await self._call_new_step_callback()
await self._call_callback(on_step_end, self)
await self._call_done_callback()
return self.history
@@ -538,6 +540,7 @@ class Agent(Generic[AgentStructuredOutput]):
process_error=process_error,
)
self.history = self.result
+ await self._call_new_step_callback()
await self._call_done_callback()
return self.history
@@ -593,6 +596,79 @@ class Agent(Generic[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))
+ async def authenticate_cloud_sync(self, show_instructions: bool = True) -> bool:
+ """Browser Use-compatible cloud-sync hook.
+
+ The upstream Python Agent currently reports cloud sync as unavailable.
+ The Rust wrapper mirrors that contract.
+ """
+ _ = show_instructions
+ return False
+
+ def get_trace_object(self) -> dict[str, Any]:
+ """Get Browser Use-style trace and trace_details data for the Rust-backed run."""
+
+ def extract_task_website(task_text: str) -> str | None:
+ match = re.search(r'https?://[^\s<>"\']+|www\.[^\s<>"\']+|[^\s<>"\']+\.[a-z]{2,}(?:/[^\s<>"\']*)?', task_text, re.IGNORECASE)
+ return match.group(0) if match else None
+
+ def json_default(value: Any) -> str:
+ return str(value)
+
+ def complete_history_without_screenshots() -> str:
+ history_data = self.history.model_dump(sensitive_data=self.sensitive_data)
+ for item in history_data.get('history', []):
+ state = item.get('state')
+ if isinstance(state, dict) and 'screenshot' in state:
+ state['screenshot'] = None
+ return json.dumps(history_data, default=json_default)
+
+ trace_id = uuid7str()
+ timestamp = datetime.now().isoformat()
+ structured_output = self.history.structured_output
+ structured_output_json = json.dumps(structured_output.model_dump(), default=json_default) if structured_output else None
+ final_result = self.history.final_result()
+ action_history = self.history.action_history()
+ action_errors = self.history.errors()
+ urls = self.history.urls()
+ usage = self.history.usage
+
+ return {
+ 'trace': {
+ 'trace_id': trace_id,
+ 'timestamp': timestamp,
+ 'browser_use_version': None,
+ 'git_info': None,
+ 'model': self.model,
+ 'settings': json.dumps(self.settings.model_dump(), default=json_default) if self.settings else None,
+ 'task_id': self.task_id,
+ 'task_truncated': self.task[:20000] if len(self.task) > 20000 else self.task,
+ 'task_website': extract_task_website(self.task),
+ 'structured_output_truncated': (
+ structured_output_json[:20000]
+ if structured_output_json and len(structured_output_json) > 20000
+ else structured_output_json
+ ),
+ 'action_history_truncated': json.dumps(action_history, default=json_default) if action_history else None,
+ 'action_errors': json.dumps(action_errors, default=json_default) if action_errors else None,
+ 'urls': json.dumps(urls, default=json_default) if urls else None,
+ 'final_result_response_truncated': final_result[:20000] if final_result and len(final_result) > 20000 else final_result,
+ 'self_report_completed': 1 if self.history.is_done() else 0,
+ 'self_report_success': 1 if self.history.is_successful() else 0,
+ 'duration': self.history.total_duration_seconds(),
+ 'steps_taken': self.history.number_of_steps(),
+ 'usage': json.dumps(usage.model_dump(), default=json_default) if usage else None,
+ },
+ 'trace_details': {
+ 'trace_id': trace_id,
+ 'timestamp': timestamp,
+ 'task': self.task,
+ 'structured_output': structured_output_json,
+ 'final_result_response': final_result,
+ 'complete_history': complete_history_without_screenshots(),
+ },
+ }
+
def _run_argv(self, max_steps: int) -> list[str]:
binary = find_browser_use_terminal_binary()
return [
@@ -632,6 +708,15 @@ class Agent(Generic[AgentStructuredOutput]):
if inspect.isawaitable(result):
await result
+ async def _call_new_step_callback(self) -> None:
+ if self.register_new_step_callback is None or not self.history.history:
+ return
+ history_item = self.history.history[-1]
+ step_number = history_item.metadata.step_number if history_item.metadata else len(self.history.history)
+ result = self.register_new_step_callback(history_item.state, None, step_number)
+ if inspect.isawaitable(result):
+ await result
+
async def _should_stop_before_run(self) -> bool:
if self.state.stopped:
return True
diff --git a/tests/ci/test_rust_agent.py b/tests/ci/test_rust_agent.py
index 4d280f0bc..e82a86210 100644
--- a/tests/ci/test_rust_agent.py
+++ b/tests/ci/test_rust_agent.py
@@ -230,6 +230,38 @@ async def test_rust_agent_invokes_browser_use_style_callbacks(monkeypatch):
]
+async def test_rust_agent_invokes_new_step_callback(monkeypatch):
+ from browser_use.rust import Agent
+
+ monkeypatch.setenv('BROWSER_USE_TERMINAL_BINARY', '/tmp/browser-use-terminal')
+ seen = []
+
+ def new_step_callback(browser_state, model_output, step_number):
+ seen.append((browser_state.url, model_output, step_number))
+
+ agent = Agent(
+ task='start',
+ llm=type('LLM', (), {'model': 'gpt-test'})(),
+ register_new_step_callback=new_step_callback,
+ )
+
+ async def fake_run_process(argv):
+ return 0, 'Session: 12345678-1234-1234-1234-123456789abc\n', ''
+
+ async def fake_load_events():
+ return [
+ {'event_type': 'browser.state', 'payload': {'url': 'https://example.com', 'title': 'Example'}},
+ {'event_type': 'session.done', 'payload': {'result': 'ok'}},
+ ]
+
+ agent._run_process = fake_run_process
+ agent._load_events = fake_load_events
+
+ await agent.run(max_steps=3)
+
+ assert seen == [('https://example.com', None, 2)]
+
+
def test_rust_agent_run_sync_delegates_to_async_run(monkeypatch):
from browser_use.rust import Agent
@@ -271,6 +303,35 @@ def test_rust_agent_lifecycle_state_and_save_history(tmp_path):
assert 'saved answer' in history_file.read_text(encoding='utf-8')
+async def test_rust_agent_trace_and_cloud_auth_helpers():
+ from browser_use.rust import Agent
+ from browser_use.rust.service import _history_from_events
+
+ agent = Agent(task='Open example.com', llm=type('LLM', (), {'model': 'gpt-test'})(), task_id='task-1')
+ agent.history = _history_from_events(
+ [
+ {'event_type': 'browser.state', 'payload': {'url': 'https://example.com', 'title': 'Example'}},
+ {'event_type': 'session.done', 'payload': {'result': 'trace answer'}},
+ ],
+ model='gpt-test',
+ started=1.0,
+ finished=3.0,
+ output_model_schema=None,
+ process_error=None,
+ )
+
+ trace_object = agent.get_trace_object()
+
+ assert await agent.authenticate_cloud_sync() is False
+ assert set(trace_object) == {'trace', 'trace_details'}
+ assert trace_object['trace']['model'] == 'gpt-test'
+ assert trace_object['trace']['task_id'] == 'task-1'
+ assert trace_object['trace']['final_result_response_truncated'] == 'trace answer'
+ assert trace_object['trace']['self_report_completed'] == 1
+ assert trace_object['trace_details']['final_result_response'] == 'trace answer'
+ assert 'trace answer' in trace_object['trace_details']['complete_history']
+
+
def test_rust_history_marks_process_failure_not_done():
from browser_use.rust.service import _history_from_events