Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
add step budget awareness to prompt
Saurav Panda65c59be26314
diff --git a/browser_use/agent/service.py b/browser_use/agent/service.pyindex e542f3014..abaf23eec 100644--- a/browser_use/agent/service.py+++ b/browser_use/agent/service.py@@ -1057,6 +1057,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):unavailable_skills_info=unavailable_skills_info,)+ await self._inject_budget_warning(step_info)await self._force_done_after_last_step(step_info)await self._force_done_after_failure()return browser_state_summary@@ -1229,6 +1230,31 @@ class Agent(Generic[Context, AgentStructuredOutput]):# Increment step counter after step is fully completedself.state.n_steps += 1+ async def _inject_budget_warning(self, step_info: AgentStepInfo | None = None) -> None:+ """Inject a prominent budget warning when the agent has used >= 75% of its step budget.++ This gives the LLM advance notice to wrap up, save partial results, and call done+ rather than exhausting all steps with nothing saved.+ """+ if step_info is None:+ return++ steps_used = step_info.step_number + 1 # Convert 0-indexed to 1-indexed+ budget_ratio = steps_used / step_info.max_steps++ if budget_ratio >= 0.75 and not step_info.is_last_step():+ steps_remaining = step_info.max_steps - steps_used+ pct = int(budget_ratio * 100)+ msg = (+ f'BUDGET WARNING: You have used {steps_used}/{step_info.max_steps} steps '+ f'({pct}%). {steps_remaining} steps remaining. '+ f'If the task cannot be completed in the remaining steps, prioritize: '+ f'(1) save all partial results to files, (2) call done with what you have. '+ f'Partial results are far more valuable than exhausting all steps with nothing saved.'+ )+ self.logger.info(f'Step budget warning: {steps_used}/{step_info.max_steps} ({pct}%)')+ self._message_manager._add_context_message(UserMessage(content=msg))+async def _force_done_after_last_step(self, step_info: AgentStepInfo | None = None) -> None:"""Handle special processing for the last step"""if step_info and step_info.is_last_step():diff --git a/browser_use/agent/system_prompts/system_prompt.md b/browser_use/agent/system_prompts/system_prompt.mdindex 86248e26a..01f065a3b 100644--- a/browser_use/agent/system_prompts/system_prompt.md+++ b/browser_use/agent/system_prompts/system_prompt.md@@ -106,6 +106,11 @@ The `done` action is your opportunity to terminate and share your findings with- You are ONLY ALLOWED to call `done` as a single action. Don't call it together with other actions.- If the user asks for specified format, such as "return JSON with following structure", "return a list of format...", MAKE sure to use the right format in your answer.- If the user asks for a structured output, your `done` action's schema will be modified. Take this schema into account when solving the task!+- When you reach 75% of your step budget, critically evaluate whether you can complete the full task.+ If not, immediately save all partial results and call `done` with what you have.+ Partial results are far more valuable than exhausting all steps with nothing saved.+- For large multi-item tasks (e.g. "search 50 items"), estimate the per-item cost from the first few items.+ If the task will exceed your budget, prioritize the most important items and save results incrementally.</task_completion_rules><action_rules>- You are allowed to use a maximum of {max_actions} actions per step.diff --git a/browser_use/agent/system_prompts/system_prompt_anthropic.md b/browser_use/agent/system_prompts/system_prompt_anthropic.mdindex 252eff9c1..b69559931 100644--- a/browser_use/agent/system_prompts/system_prompt_anthropic.md+++ b/browser_use/agent/system_prompts/system_prompt_anthropic.md@@ -109,6 +109,11 @@ The `done` action is your opportunity to terminate and share your findings with- You are ONLY ALLOWED to call `done` as a single action. Don't call it together with other actions.- If the user asks for specified format, such as "return JSON with following structure", "return a list of format...", MAKE sure to use the right format in your answer.- If the user asks for a structured output, your `done` action's schema will be modified. Take this schema into account when solving the task!+- When you reach 75% of your step budget, critically evaluate whether you can complete the full task.+ If not, immediately save all partial results and call `done` with what you have.+ Partial results are far more valuable than exhausting all steps with nothing saved.+- For large multi-item tasks (e.g. "search 50 items"), estimate the per-item cost from the first few items.+ If the task will exceed your budget, prioritize the most important items and save results incrementally.</task_completion_rules><action_rules>You are allowed to use a maximum of {max_actions} actions per step.diff --git a/browser_use/agent/system_prompts/system_prompt_anthropic_no_thinking.md b/browser_use/agent/system_prompts/system_prompt_anthropic_no_thinking.mdindex 6f279349d..0a3e05a9f 100644--- a/browser_use/agent/system_prompts/system_prompt_anthropic_no_thinking.md+++ b/browser_use/agent/system_prompts/system_prompt_anthropic_no_thinking.md@@ -109,6 +109,11 @@ The `done` action is your opportunity to terminate and share your findings with- You are ONLY ALLOWED to call `done` as a single action. Don't call it together with other actions.- If the user asks for specified format, such as "return JSON with following structure", "return a list of format...", MAKE sure to use the right format in your answer.- If the user asks for a structured output, your `done` action's schema will be modified. Take this schema into account when solving the task!+- When you reach 75% of your step budget, critically evaluate whether you can complete the full task.+ If not, immediately save all partial results and call `done` with what you have.+ Partial results are far more valuable than exhausting all steps with nothing saved.+- For large multi-item tasks (e.g. "search 50 items"), estimate the per-item cost from the first few items.+ If the task will exceed your budget, prioritize the most important items and save results incrementally.</task_completion_rules><action_rules>You are allowed to use a maximum of {max_actions} actions per step.diff --git a/tests/ci/test_budget_warning.py b/tests/ci/test_budget_warning.pynew file mode 100644index 000000000..74727b7ba--- /dev/null+++ b/tests/ci/test_budget_warning.py@@ -0,0 +1,156 @@+"""Tests for step budget warning injection (IMP-7a)."""++from browser_use.agent.service import Agent+from browser_use.agent.views import AgentStepInfo+from browser_use.llm.messages import UserMessage+from tests.ci.conftest import create_mock_llm+++def _get_context_messages(agent: Agent) -> list[str]:+ """Extract text content from the agent's context messages."""+ msgs = agent._message_manager.state.history.context_messages+ return [m.content for m in msgs if isinstance(m, UserMessage) and isinstance(m.content, str)]+++async def test_budget_warning_injected_at_75_percent():+ """Budget warning should be injected when step >= 75% of max_steps."""+ llm = create_mock_llm()+ agent = Agent(task='Test task', llm=llm)++ step_info = AgentStepInfo(step_number=74, max_steps=100) # step 75/100 = 75%+ await agent._inject_budget_warning(step_info)++ messages = _get_context_messages(agent)+ assert len(messages) == 1+ assert 'BUDGET WARNING' in messages[0]+ assert '75/100' in messages[0]+ assert '25 steps remaining' in messages[0]+++async def test_budget_warning_injected_at_90_percent():+ """Budget warning should fire at 90% too."""+ llm = create_mock_llm()+ agent = Agent(task='Test task', llm=llm)++ step_info = AgentStepInfo(step_number=89, max_steps=100) # step 90/100 = 90%+ await agent._inject_budget_warning(step_info)++ messages = _get_context_messages(agent)+ assert len(messages) == 1+ assert 'BUDGET WARNING' in messages[0]+ assert '90/100' in messages[0]+ assert '10 steps remaining' in messages[0]+++async def test_no_budget_warning_below_75_percent():+ """No warning should be injected when step < 75% of max_steps."""+ llm = create_mock_llm()+ agent = Agent(task='Test task', llm=llm)++ step_info = AgentStepInfo(step_number=73, max_steps=100) # step 74/100 = 74%+ await agent._inject_budget_warning(step_info)++ messages = _get_context_messages(agent)+ assert len(messages) == 0+++async def test_no_budget_warning_on_last_step():+ """No budget warning on the last step — _force_done_after_last_step handles that."""+ llm = create_mock_llm()+ agent = Agent(task='Test task', llm=llm)++ step_info = AgentStepInfo(step_number=99, max_steps=100) # last step+ assert step_info.is_last_step()+ await agent._inject_budget_warning(step_info)++ messages = _get_context_messages(agent)+ assert len(messages) == 0+++async def test_no_budget_warning_when_step_info_is_none():+ """No warning when step_info is None."""+ llm = create_mock_llm()+ agent = Agent(task='Test task', llm=llm)++ await agent._inject_budget_warning(None)++ messages = _get_context_messages(agent)+ assert len(messages) == 0+++async def test_budget_warning_exact_threshold():+ """The warning should fire at exactly 75% (step 15/20)."""+ llm = create_mock_llm()+ agent = Agent(task='Test task', llm=llm)++ # step_number=14 means step 15 (1-indexed), 15/20 = 75%+ step_info = AgentStepInfo(step_number=14, max_steps=20)+ await agent._inject_budget_warning(step_info)++ messages = _get_context_messages(agent)+ assert len(messages) == 1+ assert '15/20' in messages[0]+ assert '5 steps remaining' in messages[0]+++async def test_budget_warning_just_below_threshold():+ """No warning at 74% — just below threshold."""+ llm = create_mock_llm()+ agent = Agent(task='Test task', llm=llm)++ # step_number=13 means step 14 (1-indexed), 14/20 = 70%+ step_info = AgentStepInfo(step_number=13, max_steps=20)+ await agent._inject_budget_warning(step_info)++ messages = _get_context_messages(agent)+ assert len(messages) == 0+++async def test_budget_warning_small_max_steps():+ """Budget warning works correctly with small max_steps values."""+ llm = create_mock_llm()+ agent = Agent(task='Test task', llm=llm)++ # step_number=3 means step 4 (1-indexed), 4/4 = 100% but is_last_step+ step_info = AgentStepInfo(step_number=3, max_steps=4)+ assert step_info.is_last_step()+ await agent._inject_budget_warning(step_info)+ messages = _get_context_messages(agent)+ assert len(messages) == 0 # last step, no warning++ # step_number=2 means step 3 (1-indexed), 3/4 = 75%+ step_info = AgentStepInfo(step_number=2, max_steps=4)+ await agent._inject_budget_warning(step_info)+ messages = _get_context_messages(agent)+ assert len(messages) == 1+ assert '3/4' in messages[0]+++async def test_budget_warning_percentage_display():+ """The percentage in the warning should be integer (no decimals)."""+ llm = create_mock_llm()+ agent = Agent(task='Test task', llm=llm)++ # step 76/100 = 76%+ step_info = AgentStepInfo(step_number=75, max_steps=100)+ await agent._inject_budget_warning(step_info)++ messages = _get_context_messages(agent)+ assert '76%' in messages[0]+ # Should not have decimal+ assert '76.0%' not in messages[0]+++async def test_budget_warning_contains_actionable_guidance():+ """The warning message should include actionable guidance for the agent."""+ llm = create_mock_llm()+ agent = Agent(task='Test task', llm=llm)++ step_info = AgentStepInfo(step_number=74, max_steps=100)+ await agent._inject_budget_warning(step_info)++ messages = _get_context_messages(agent)+ msg = messages[0]+ assert 'save all partial results' in msg.lower()+ assert 'done' in msg.lower()+ assert 'partial results' in msg.lower()