Skip to content

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

Dispatch Rust step-end hooks per turn

Magnus Müller23edd6f48346
diff --git a/RUST_AGENT_INTEGRATION_FEATURES.md b/RUST_AGENT_INTEGRATION_FEATURES.md
index 19445bb98..ed1a4e6f3 100644
--- a/RUST_AGENT_INTEGRATION_FEATURES.md
+++ b/RUST_AGENT_INTEGRATION_FEATURES.md
@@ -1021,10 +1021,15 @@ Terminal core branch: `magnus/browser-use-rust-main-integration` at terminal mai
- Callback step numbers use the Browser Use-facing cumulative step counter, and repeated callback dispatch for the same history object is idempotent.
- Proof: `test_rust_agent_invokes_new_step_callback_for_each_terminal_turn`.
+202. Rust Agent per-terminal-turn step-end hook parity
+ - Rust-backed runs now invoke `on_step_end` once for each reconstructed terminal model turn instead of only once after the whole terminal subprocess finishes.
+ - Repeated step-end hook dispatch for the same history object is idempotent, preserving the run/follow-up finalization path while matching Browser Use's per-step hook cardinality.
+ - Proof: `test_rust_agent_invokes_on_step_end_for_each_terminal_turn`.
+
## Current Verification
- `python3 -m py_compile browser_use/agent/service.py 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` (170 tests)
+- `uv run pytest -q tests/ci/test_rust_agent.py` (171 tests)
- `cargo build -q -p browser-use-cli` on terminal branch `magnus/browser-use-rust-main-integration`
- `cargo test -q -p browser-use-cli run_codex_session_command_accepts_task_id_and_model -- --nocapture`
- `CARGO_INCREMENTAL=0 cargo test -q -p browser-use-agent selected_remote_cdp_mode_allows_remote_cdp_connect -- --nocapture`
@@ -1107,6 +1112,9 @@ Terminal core branch: `magnus/browser-use-rust-main-integration` at terminal mai
- Per-terminal-turn callback Python API end-to-end:
- Source `/home/exedev/.evaluation_tool_env`, set `BROWSER_USE_TERMINAL_BINARY=/home/exedev/Developer/terminal/target/debug/browser-use-terminal`, set `BROWSER_USE_RUST_BROWSER_MODE=managed-headless`, and construct `Agent(..., register_new_step_callback=..., step_timeout=300)`.
- Output: final result `Example Domain`, `history.number_of_steps()` is `5`, callback count is `5`, and callback step numbers are `[2, 3, 4, 5, 6]`.
+- Per-terminal-turn step-end hook Python API end-to-end:
+ - Source `/home/exedev/.evaluation_tool_env`, set `BROWSER_USE_TERMINAL_BINARY=/home/exedev/Developer/terminal/target/debug/browser-use-terminal`, set `BROWSER_USE_RUST_BROWSER_MODE=managed-headless`, and run `Agent(..., on_step_end=..., step_timeout=300)`.
+ - Output: final result `Example Domain`, `history.number_of_steps()` is `3`, and `on_step_end` callback count is `3`.
- Parallel managed-headless Python API smoke batch:
- Source `/home/exedev/.evaluation_tool_env`, set `BROWSER_USE_TERMINAL_BINARY=/home/exedev/Developer/terminal/target/debug/browser-use-terminal`, set `BROWSER_USE_RUST_BROWSER_MODE=managed-headless`, and run two `uv run python - <<'PY' ...` Agent scripts in parallel.
- Follow-up/callback script output: `{"smoke": "python_api_followup_callbacks", "first": "Example Domain", "second": "example.com", "callback_kinds": ["step", "done", "step", "done"], "conversation_files": 2}`.
diff --git a/browser_use/rust/service.py b/browser_use/rust/service.py
index 1c9844028..d3bc97011 100644
--- a/browser_use/rust/service.py
+++ b/browser_use/rust/service.py
@@ -2666,6 +2666,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
self.last_stderr = ''
self._last_synced_history_id: int | None = None
self._last_step_callback_history_id: int | None = None
+ self._last_step_end_callback_history_id: int | None = None
self._external_pause_event = asyncio.Event()
self._external_pause_event.set()
@@ -3102,7 +3103,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
await self._check_and_update_downloads('run')
await self._save_conversation_if_requested()
await self._call_new_step_callback()
- await self._call_callback(on_step_end, self)
+ await self._call_step_end_callbacks(on_step_end)
await self._call_done_callback()
await self._generate_gif_if_requested()
self._log_final_outcome_messages()
@@ -3177,7 +3178,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
await self._check_and_update_downloads('follow_up')
await self._save_conversation_if_requested()
await self._call_new_step_callback()
- await self._call_callback(on_step_end, self)
+ await self._call_step_end_callbacks(on_step_end)
await self._call_done_callback()
await self._generate_gif_if_requested()
self._log_final_outcome_messages()
@@ -4142,6 +4143,16 @@ class Agent(Generic[Context, AgentStructuredOutput]):
await result
self._last_step_callback_history_id = history_id
+ async def _call_step_end_callbacks(self, callback: AgentHookFunc | None) -> None:
+ if callback is None or not self.history.history:
+ return
+ history_id = id(self.history)
+ if history_id == self._last_step_end_callback_history_id:
+ return
+ for _history_item in self.history.history:
+ await self._call_callback(callback, self)
+ self._last_step_end_callback_history_id = history_id
+
def _sync_state_from_history(self) -> None:
if not self.history.history:
return
diff --git a/tests/ci/test_rust_agent.py b/tests/ci/test_rust_agent.py
index 0f78736ff..d4a67ddb8 100644
--- a/tests/ci/test_rust_agent.py
+++ b/tests/ci/test_rust_agent.py
@@ -5231,6 +5231,69 @@ async def test_rust_agent_invokes_new_step_callback_for_each_terminal_turn(monke
]
+async def test_rust_agent_invokes_on_step_end_for_each_terminal_turn(monkeypatch):
+ from browser_use.rust import Agent
+
+ monkeypatch.setenv('BROWSER_USE_TERMINAL_BINARY', '/tmp/browser-use-terminal')
+ seen = []
+ agent = Agent(task='run terminal turn end hooks', llm=type('LLM', (), {'model': 'gpt-test'})())
+ starting_steps = agent.state.n_steps
+
+ def on_step_end(callback_agent):
+ seen.append(
+ (
+ callback_agent.state.n_steps,
+ callback_agent.history.number_of_steps(),
+ callback_agent.history.final_result(),
+ )
+ )
+
+ async def fake_run_process(argv, timeout_seconds=None):
+ assert timeout_seconds == agent.settings.step_timeout
+ return 0, 'Session: 12345678-1234-1234-1234-123456789abc\n', ''
+
+ async def fake_load_events():
+ return [
+ {'type': 'model.turn.request', 'ts_ms': 1_000, 'payload': {'model': 'gpt-test'}},
+ {'type': 'browser.state', 'ts_ms': 1_010, 'payload': {'url': 'https://first.example', 'title': 'First'}},
+ {
+ 'type': 'tool.started',
+ 'ts_ms': 1_020,
+ 'payload': {'name': 'browser', 'tool_call_id': 'call-browser', 'arguments': {'cmd': 'observe'}},
+ },
+ {
+ 'type': 'tool.output',
+ 'ts_ms': 1_030,
+ 'payload': {'name': 'browser', 'tool_call_id': 'call-browser', 'text': 'first turn observed'},
+ },
+ {'type': 'model.turn.request', 'ts_ms': 2_000, 'payload': {'model': 'gpt-test'}},
+ {'type': 'browser.state', 'ts_ms': 2_010, 'payload': {'url': 'https://example.com', 'title': 'Example'}},
+ {
+ 'type': 'tool.started',
+ 'ts_ms': 2_020,
+ 'payload': {
+ 'name': 'done',
+ 'tool_call_id': 'call-done',
+ 'arguments': {'text': 'Example Domain', 'success': True},
+ },
+ },
+ {'type': 'session.done', 'ts_ms': 2_030, 'payload': {'result': 'Example Domain'}},
+ ]
+
+ agent._run_process = fake_run_process
+ agent._load_events = fake_load_events
+
+ history = await agent.run(max_steps=4, on_step_end=on_step_end)
+ await agent._call_step_end_callbacks(on_step_end)
+
+ assert history.number_of_steps() == 2
+ assert agent.state.n_steps == starting_steps + 2
+ assert seen == [
+ (starting_steps + 2, 2, 'Example Domain'),
+ (starting_steps + 2, 2, 'Example Domain'),
+ ]
+
+
def test_rust_agent_run_sync_delegates_to_async_run(monkeypatch):
from browser_use.rust import Agent