Skip to content

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

agent(prompts): move per-step metadata out of <agent_state> into a tail block

Saurav Pandaa3bae60ed28f
diff --git a/browser_use/agent/prompts.py b/browser_use/agent/prompts.py
index 803b3547d..3a0fb2be5 100644
--- a/browser_use/agent/prompts.py
+++ b/browser_use/agent/prompts.py
@@ -322,14 +322,6 @@ Available tabs:
return browser_state
def _get_agent_state_description(self) -> str:
- if self.step_info:
- step_info_description = f'Step{self.step_info.step_number + 1} maximum:{self.step_info.max_steps}\n'
- else:
- step_info_description = ''
-
- time_str = datetime.now().strftime('%Y-%m-%d')
- step_info_description += f'Today:{time_str}'
-
_todo_contents = self.file_system.get_todo_contents() if self.file_system else ''
if not len(_todo_contents):
_todo_contents = '[empty todo.md, fill it when applicable]'
@@ -351,12 +343,22 @@ Available tabs:
if self.sensitive_data:
agent_state += f'<sensitive_data>{self.sensitive_data}</sensitive_data>\n'
- agent_state += f'<step_info>{step_info_description}</step_info>\n'
if self.available_file_paths:
available_file_paths_text = '\n'.join(self.available_file_paths)
agent_state += f'<available_file_paths>{available_file_paths_text}\nUse with absolute paths</available_file_paths>\n'
return agent_state
+ def _get_step_meta_description(self) -> str:
+ # Per-step varying metadata (step counter, wall-clock date). Kept out of <agent_state> so it
+ # lives at the tail of the user message — anything before this block can in principle be
+ # treated as the cacheable prefix.
+ if self.step_info:
+ step_info_description = f'Step{self.step_info.step_number + 1} maximum:{self.step_info.max_steps}\n'
+ else:
+ step_info_description = ''
+ step_info_description += f'Today:{datetime.now().strftime("%Y-%m-%d")}'
+ return f'<step_info>{step_info_description}</step_info>\n'
+
def _resize_screenshot(self, screenshot_b64: str) -> str:
"""Resize screenshot to llm_screenshot_size if configured."""
if not self.llm_screenshot_size:
@@ -419,6 +421,10 @@ Available tabs:
if self.unavailable_skills_info:
state_description += '\n' + self.unavailable_skills_info + '\n'
+ # Per-step varying metadata (step counter, date) lives at the tail of the message so that
+ # everything above can in principle be treated as a cacheable prefix.
+ state_description += self._get_step_meta_description()
+
# Sanitize surrogates from all text content
state_description = sanitize_surrogates(state_description)
diff --git a/tests/ci/test_prompt_step_meta_suffix.py b/tests/ci/test_prompt_step_meta_suffix.py
new file mode 100644
index 000000000..30ce6842a
--- /dev/null
+++ b/tests/ci/test_prompt_step_meta_suffix.py
@@ -0,0 +1,93 @@
+"""Lock per-step varying metadata (step counter, wall-clock date) at the tail of the user message.
+
+The agent's user message looks roughly:
+ <agent_history>...</agent_history>
+ <agent_state>...</agent_state>
+ <browser_state>...</browser_state>
+ [<read_state>...</read_state>]
+ [<page_specific_actions>...</page_specific_actions>]
+ [unavailable skills info]
+ <step_info>...</step_info> <-- new home
+
+`<step_info>` carries a step counter and `datetime.now()`, both of which change between
+calls. Keeping it at the very end means everything above it can in principle be cached;
+moving it back into `<agent_state>` would silently shrink the cacheable prefix.
+"""
+
+from browser_use.agent.prompts import AgentMessagePrompt
+from browser_use.agent.views import AgentStepInfo
+from browser_use.browser.views import BrowserStateSummary, PageInfo, TabInfo
+from browser_use.dom.views import SerializedDOMState
+from browser_use.filesystem.file_system import FileSystem
+
+
+def _make_prompt(tmp_path, step_number: int = 3) -> AgentMessagePrompt:
+ dom_state = SerializedDOMState(_root=None, selector_map={})
+ bs = BrowserStateSummary(
+ url='https://example.test/foo',
+ title='Test',
+ tabs=[TabInfo(target_id='abcd1234', url='https://example.test/foo', title='Test')],
+ page_info=PageInfo(
+ viewport_width=1280,
+ viewport_height=720,
+ page_width=1280,
+ page_height=1440,
+ scroll_x=0,
+ scroll_y=0,
+ pixels_above=0,
+ pixels_below=720,
+ pixels_left=0,
+ pixels_right=0,
+ ),
+ dom_state=dom_state,
+ is_pdf_viewer=False,
+ recent_events=None,
+ closed_popup_messages=[],
+ screenshot=None,
+ )
+ fs = FileSystem(base_dir=str(tmp_path), create_default_files=False)
+ return AgentMessagePrompt(
+ browser_state_summary=bs,
+ file_system=fs,
+ agent_history_description='<step>existing history</step>',
+ task='Do the test thing',
+ step_info=AgentStepInfo(step_number=step_number, max_steps=50),
+ )
+
+
+def test_step_info_lives_at_suffix(tmp_path):
+ content = _make_prompt(tmp_path).get_user_message(use_vision=False).content
+ assert isinstance(content, str)
+
+ assert '<step_info>' in content
+ # Suffix: step_info must come after agent_state and browser_state.
+ assert content.index('<agent_state>') < content.index('<step_info>')
+ assert content.index('<browser_state>') < content.index('<step_info>')
+
+ # And it must NOT live inside <agent_state> any more.
+ state_start = content.index('<agent_state>')
+ state_end = content.index('</agent_state>')
+ assert '<step_info>' not in content[state_start:state_end], 'per-step metadata leaked into <agent_state> prefix region'
+
+
+def test_prefix_up_to_step_info_is_stable_across_steps(tmp_path):
+ """Step number and date can change; the bytes before <step_info> must not."""
+ a = _make_prompt(tmp_path, step_number=3).get_user_message(use_vision=False).content
+ b = _make_prompt(tmp_path, step_number=4).get_user_message(use_vision=False).content
+ assert isinstance(a, str) and isinstance(b, str)
+ prefix_end = a.index('<step_info>')
+ assert a[:prefix_end] == b[:prefix_end], 'message bytes diverged before <step_info> — step counter is leaking into the prefix'
+ # Sanity: the tails do differ (step counter advanced).
+ assert a[prefix_end:] != b[prefix_end:]
+
+
+def test_agent_state_block_unaffected_by_step_change(tmp_path):
+ """<agent_state> should not include per-step-varying metadata."""
+ a = _make_prompt(tmp_path, step_number=3).get_user_message(use_vision=False).content
+ b = _make_prompt(tmp_path, step_number=4).get_user_message(use_vision=False).content
+ assert isinstance(a, str) and isinstance(b, str)
+
+ def agent_state_block(s: str) -> str:
+ return s[s.index('<agent_state>') : s.index('</agent_state>')]
+
+ assert agent_state_block(a) == agent_state_block(b)