Skip to content

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

add step budget awareness to prompt

Saurav Panda65c59be26314
diff --git a/browser_use/agent/service.py b/browser_use/agent/service.py
index 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 completed
self.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.md
index 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.md
index 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.md
index 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.py
new file mode 100644
index 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()