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
added basic planing to agents
Saurav Panda5ad365e31bfa
diff --git a/browser_use/agent/message_manager/service.py b/browser_use/agent/message_manager/service.pyindex d79903e70..3eff1bcfb 100644--- a/browser_use/agent/message_manager/service.py+++ b/browser_use/agent/message_manager/service.py@@ -299,6 +299,7 @@ class MessageManager:sensitive_data=None,available_file_paths: list[str] | None = None, # Always pass current available_file_pathsunavailable_skills_info: str | None = None, # Information about skills that cannot be used yet+ plan_description: str | None = None, # Rendered plan for injection into agent state) -> None:"""Create single state message with all content"""@@ -366,6 +367,7 @@ class MessageManager:read_state_images=self.state.read_state_images,llm_screenshot_size=self.llm_screenshot_size,unavailable_skills_info=unavailable_skills_info,+ plan_description=plan_description,).get_user_message(effective_use_vision)# Store state message text for historydiff --git a/browser_use/agent/prompts.py b/browser_use/agent/prompts.pyindex ef0be845a..7ce050ac5 100644--- a/browser_use/agent/prompts.py+++ b/browser_use/agent/prompts.py@@ -123,6 +123,7 @@ class AgentMessagePrompt:read_state_images: list[dict] | None = None,llm_screenshot_size: tuple[int, int] | None = None,unavailable_skills_info: str | None = None,+ plan_description: str | None = None,):self.browser_state: 'BrowserStateSummary' = browser_state_summaryself.file_system: 'FileSystem | None' = file_system@@ -141,6 +142,7 @@ class AgentMessagePrompt:self.sample_images = sample_images or []self.read_state_images = read_state_images or []self.unavailable_skills_info: str | None = unavailable_skills_info+ self.plan_description: str | None = plan_descriptionself.llm_screenshot_size = llm_screenshot_sizeassert self.browser_state@@ -339,6 +341,9 @@ Available tabs:{_todo_contents}</todo_contents>"""+ if self.plan_description:+ agent_state += f'<plan>\n{self.plan_description}\n</plan>\n'+if self.sensitive_data:agent_state += f'<sensitive_data>{self.sensitive_data}</sensitive_data>\n'diff --git a/browser_use/agent/service.py b/browser_use/agent/service.pyindex f9b8c9c22..7250106ab 100644--- a/browser_use/agent/service.py+++ b/browser_use/agent/service.py@@ -57,6 +57,7 @@ from browser_use.agent.views import (BrowserStateHistory,DetectedVariable,JudgementResult,+ PlanStep,StepMetadata,)from browser_use.browser.events import _get_timeout@@ -194,6 +195,8 @@ class Agent(Generic[Context, AgentStructuredOutput]):include_recent_events: bool = False,sample_images: list[ContentPartTextParam | ContentPartImageParam] | None = None,final_response_after_failure: bool = True,+ enable_planning: bool = True,+ planning_replan_on_stall: int = 3,llm_screenshot_size: tuple[int, int] | None = None,_url_shortening_limit: int = 25,**kwargs,@@ -387,6 +390,8 @@ class Agent(Generic[Context, AgentStructuredOutput]):final_response_after_failure=final_response_after_failure,use_judge=use_judge,ground_truth=ground_truth,+ enable_planning=enable_planning,+ planning_replan_on_stall=planning_replan_on_stall,)# Token cost service@@ -1051,6 +1056,9 @@ class Agent(Generic[Context, AgentStructuredOutput]):if self.skill_service is not None:unavailable_skills_info = await self._get_unavailable_skills_info()+ # Render plan description for injection into agent context+ plan_description = self._render_plan_description()+self._message_manager.create_state_messages(browser_state_summary=browser_state_summary,model_output=self.state.last_model_output,@@ -1061,9 +1069,11 @@ class Agent(Generic[Context, AgentStructuredOutput]):sensitive_data=self.sensitive_data,available_file_paths=self.available_file_paths, # Always pass current available_file_pathsunavailable_skills_info=unavailable_skills_info,+ plan_description=plan_description,)await self._inject_budget_warning(step_info)+ self._inject_replan_nudge()await self._force_done_after_last_step(step_info)await self._force_done_after_failure()return browser_state_summary@@ -1119,6 +1129,10 @@ class Agent(Generic[Context, AgentStructuredOutput]):# Check for new downloads after executing actionsawait self._check_and_update_downloads('after executing actions')+ # Update plan state from model output+ if self.state.last_model_output is not None:+ self._update_plan_from_model_output(self.state.last_model_output)+# check for action errors and len more than 1if self.state.last_result and len(self.state.last_result) == 1 and self.state.last_result[-1].error:self.state.consecutive_failures += 1@@ -1236,6 +1250,69 @@ class Agent(Generic[Context, AgentStructuredOutput]):# Increment step counter after step is fully completedself.state.n_steps += 1+ def _update_plan_from_model_output(self, model_output: AgentOutput) -> None:+ """Update the plan state from model output fields (current_plan_step, plan_update)."""+ if not self.settings.enable_planning:+ return++ # If model provided a new plan via plan_update, replace the current plan+ if model_output.plan_update is not None:+ self.state.plan = [PlanStep(text=step_text) for step_text in model_output.plan_update]+ self.state.current_plan_step_index = 0+ self.state.plan_generation_step = self.state.n_steps+ if self.state.plan:+ self.state.plan[0].status = 'current'+ self.logger.info(+ f'📋 Plan {"updated" if self.state.plan_generation_step else "created"} with {len(self.state.plan)} steps'+ )+ return++ # If model provided a step index update, advance the plan+ if model_output.current_plan_step is not None and self.state.plan is not None:+ new_idx = model_output.current_plan_step+ # Clamp to valid range+ new_idx = max(0, min(new_idx, len(self.state.plan) - 1))+ old_idx = self.state.current_plan_step_index++ # Mark steps between old and new as done+ for i in range(old_idx, new_idx):+ if i < len(self.state.plan) and self.state.plan[i].status in ('current', 'pending'):+ self.state.plan[i].status = 'done'++ # Mark the new step as current+ if new_idx < len(self.state.plan):+ self.state.plan[new_idx].status = 'current'++ self.state.current_plan_step_index = new_idx++ def _render_plan_description(self) -> str | None:+ """Render the current plan as a text description for injection into agent context."""+ if not self.settings.enable_planning or self.state.plan is None:+ return None++ markers = {'done': '[x]', 'current': '[>]', 'pending': '[ ]', 'skipped': '[-]'}+ lines = []+ for i, step in enumerate(self.state.plan):+ marker = markers.get(step.status, '[ ]')+ lines.append(f'{marker} {i}: {step.text}')+ return '\n'.join(lines)++ def _inject_replan_nudge(self) -> None:+ """Inject a replan nudge when stall detection threshold is met."""+ if not self.settings.enable_planning or self.state.plan is None:+ return+ if self.settings.planning_replan_on_stall <= 0:+ return+ if self.state.consecutive_failures >= self.settings.planning_replan_on_stall:+ msg = (+ 'REPLAN SUGGESTED: You have failed '+ f'{self.state.consecutive_failures} consecutive times. '+ 'Your current plan may need revision. '+ 'Output a new `plan_update` with revised steps to recover.'+ )+ self.logger.info(f'📋 Replan nudge injected after {self.state.consecutive_failures} consecutive failures')+ self._message_manager._add_context_message(UserMessage(content=msg))+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.diff --git a/browser_use/agent/system_prompts/system_prompt.md b/browser_use/agent/system_prompts/system_prompt.mdindex f19b6ed32..4c84d838a 100644--- a/browser_use/agent/system_prompts/system_prompt.md+++ b/browser_use/agent/system_prompts/system_prompt.md@@ -99,6 +99,13 @@ Strictly follow these rules while using the browser and navigating the web:- If the task is really long, initialize a `results.md` file to accumulate your results.- DO NOT use the file system if the task is less than 10 steps!</file_system>+<planning>+On your FIRST step, create a high-level plan by outputting `plan_update` with 3-10 steps.+On subsequent steps, `<plan>` in your input shows the current plan with status markers:+ [x]=done, [>]=current, [ ]=pending, [-]=skipped+Output `current_plan_step` (0-indexed integer) to indicate which step you are working on now.+Only output `plan_update` again if the plan needs significant revision (e.g. after unexpected obstacles).+</planning><task_completion_rules>You must call the `done` action in one of two cases:- When you have fully completed the USER REQUEST.@@ -195,10 +202,13 @@ You must ALWAYS respond with a valid JSON in this exact format:"thinking": "A structured <think>-style reasoning block that applies the <reasoning_rules> provided above.","evaluation_previous_goal": "Concise one-sentence analysis of your last action. Clearly state success, failure, or uncertain.","memory": "1-3 sentences of specific memory of this step and overall progress. You should put here everything that will help you track progress in future steps. Like counting pages visited, items found, etc.",- "next_goal": "State the next immediate goal and action to achieve it, in one clear sentence."+ "next_goal": "State the next immediate goal and action to achieve it, in one clear sentence.",+ "current_plan_step": 0,+ "plan_update": ["Step 1 description", "Step 2 description"],"action":[{{"navigate": {{ "url": "url_value"}}}}, // ... more actions in sequence]}}Action list should NEVER be empty.+`current_plan_step` and `plan_update` are optional. See <planning> for details.</output><critical_reminders>1. ALWAYS verify action success using the screenshot before proceedingdiff --git a/browser_use/agent/system_prompts/system_prompt_no_thinking.md b/browser_use/agent/system_prompts/system_prompt_no_thinking.mdindex 07391acb1..79d72b211 100644--- a/browser_use/agent/system_prompts/system_prompt_no_thinking.md+++ b/browser_use/agent/system_prompts/system_prompt_no_thinking.md@@ -96,6 +96,13 @@ Strictly follow these rules while using the browser and navigating the web:- If the task is really long, initialize a `results.md` file to accumulate your results.- DO NOT use the file system if the task is less than 10 steps!</file_system>+<planning>+On your FIRST step, create a high-level plan by outputting `plan_update` with 3-10 steps.+On subsequent steps, `<plan>` in your input shows the current plan with status markers:+ [x]=done, [>]=current, [ ]=pending, [-]=skipped+Output `current_plan_step` (0-indexed integer) to indicate which step you are working on now.+Only output `plan_update` again if the plan needs significant revision (e.g. after unexpected obstacles).+</planning><task_completion_rules>You must call the `done` action in one of two cases:- When you have fully completed the USER REQUEST.@@ -186,9 +193,12 @@ You must ALWAYS respond with a valid JSON in this exact format:"evaluation_previous_goal": "One-sentence analysis of your last action. Clearly state success, failure, or uncertain.","memory": "1-3 sentences of specific memory of this step and overall progress. You should put here everything that will help you track progress in future steps. Like counting pages visited, items found, etc.","next_goal": "State the next immediate goal and action to achieve it, in one clear sentence.",+ "current_plan_step": 0,+ "plan_update": ["Step 1 description", "Step 2 description"],"action":[{{"navigate": {{ "url": "url_value"}}}}, // ... more actions in sequence]}}Action list should NEVER be empty.+`current_plan_step` and `plan_update` are optional. See <planning> for details.</output><critical_reminders>1. ALWAYS verify action success using the screenshot before proceedingdiff --git a/browser_use/agent/views.py b/browser_use/agent/views.pyindex 0131a0f7e..d77db32b8 100644--- a/browser_use/agent/views.py+++ b/browser_use/agent/views.py@@ -47,6 +47,8 @@ class AgentSettings(BaseModel):use_judge: bool = Trueground_truth: str | None = None # Ground truth answer or criteria for judge validationmax_history_items: int | None = None+ enable_planning: bool = True+ planning_replan_on_stall: int = 3 # consecutive failures before replan nudge; 0 = disabledpage_extraction_llm: BaseChatModel | None = Nonecalculate_cost: bool = False@@ -65,7 +67,9 @@ class AgentState(BaseModel):n_steps: int = 1consecutive_failures: int = 0last_result: list[ActionResult] | None = None- last_plan: str | None = None+ plan: list[PlanStep] | None = None+ current_plan_step_index: int = 0+ plan_generation_step: int | None = Nonelast_model_output: AgentOutput | None = None# Pause/resume state (kept serialisable for checkpointing)@@ -176,6 +180,11 @@ class StepMetadata(BaseModel):return self.step_end_time - self.step_start_time+class PlanStep(BaseModel):+ text: str+ status: Literal['pending', 'current', 'done', 'skipped'] = 'pending'++class AgentBrain(BaseModel):thinking: str | None = Noneevaluation_previous_goal: str@@ -190,6 +199,8 @@ class AgentOutput(BaseModel):evaluation_previous_goal: str | None = Nonememory: str | None = Nonenext_goal: str | None = None+ current_plan_step: int | None = None+ plan_update: list[str] | None = Noneaction: list[ActionModel] = Field(...,json_schema_extra={'min_items': 1}, # Ensure at least one action is provided@@ -258,10 +269,12 @@ class AgentOutput(BaseModel):@classmethoddef model_json_schema(cls, **kwargs):schema = super().model_json_schema(**kwargs)- # Remove thinking, evaluation_previous_goal, and next_goal fields+ # Remove thinking, evaluation_previous_goal, next_goal, and plan fieldsdel schema['properties']['thinking']del schema['properties']['evaluation_previous_goal']del schema['properties']['next_goal']+ schema['properties'].pop('current_plan_step', None)+ schema['properties'].pop('plan_update', None)# Update required fields to only include remaining propertiesschema['required'] = ['memory', 'action']return schema@@ -381,6 +394,10 @@ class AgentHistory(BaseModel):# Only include thinking if it's presentif self.model_output.thinking is not None:model_output_dump['thinking'] = self.model_output.thinking+ if self.model_output.current_plan_step is not None:+ model_output_dump['current_plan_step'] = self.model_output.current_plan_step+ if self.model_output.plan_update is not None:+ model_output_dump['plan_update'] = self.model_output.plan_update# Handle result serialization - don't filter ActionResult data# as it should contain meaningful information for the agentdiff --git a/tests/ci/test_agent_planning.py b/tests/ci/test_agent_planning.pynew file mode 100644index 000000000..c4db3d632--- /dev/null+++ b/tests/ci/test_agent_planning.py@@ -0,0 +1,294 @@+"""Tests for inline task planning feature.++Covers: plan generation, step advancement, replanning, rendering,+disabled planning, replan nudge, flash mode schema, and edge cases.+"""++import json++from browser_use.agent.views import (+ AgentOutput,+ PlanStep,+)+from browser_use.tools.service import Tools++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++def _make_agent_output(**overrides) -> AgentOutput:+ """Build a minimal AgentOutput with plan fields."""+ tools = Tools()+ ActionModel = tools.registry.create_action_model()+ OutputType = AgentOutput.type_with_custom_actions(ActionModel)+ action_json = json.dumps(+ {+ 'evaluation_previous_goal': 'Success',+ 'memory': 'mem',+ 'next_goal': 'goal',+ **{k: v for k, v in overrides.items() if k in ('current_plan_step', 'plan_update')},+ 'action': [{'done': {'text': 'ok', 'success': True}}],+ }+ )+ return OutputType.model_validate_json(action_json)+++def _make_agent(browser_session, mock_llm, **kwargs):+ """Create an Agent with defaults suitable for unit tests."""+ from browser_use import Agent++ return Agent(task='Test task', llm=mock_llm, browser_session=browser_session, **kwargs)+++# ---------------------------------------------------------------------------+# 1. Plan generation from plan_update on step 1+# ---------------------------------------------------------------------------+++async def test_plan_generation_from_plan_update(browser_session, mock_llm):+ agent = _make_agent(browser_session, mock_llm)+ output = _make_agent_output(plan_update=['Navigate to page', 'Search for item', 'Extract price'])++ agent._update_plan_from_model_output(output)++ assert agent.state.plan is not None+ assert len(agent.state.plan) == 3+ assert agent.state.plan[0].status == 'current'+ assert agent.state.plan[1].status == 'pending'+ assert agent.state.plan[2].status == 'pending'+ assert agent.state.current_plan_step_index == 0+ assert agent.state.plan_generation_step == agent.state.n_steps+++# ---------------------------------------------------------------------------+# 2. Plan step advancement via current_plan_step+# ---------------------------------------------------------------------------+++async def test_plan_step_advancement(browser_session, mock_llm):+ agent = _make_agent(browser_session, mock_llm)+ # Seed a plan+ agent.state.plan = [+ PlanStep(text='Step A', status='current'),+ PlanStep(text='Step B'),+ PlanStep(text='Step C'),+ ]+ agent.state.current_plan_step_index = 0++ output = _make_agent_output(current_plan_step=2)+ agent._update_plan_from_model_output(output)++ assert agent.state.plan[0].status == 'done'+ assert agent.state.plan[1].status == 'done'+ assert agent.state.plan[2].status == 'current'+ assert agent.state.current_plan_step_index == 2+++# ---------------------------------------------------------------------------+# 3. Replanning replaces old plan+# ---------------------------------------------------------------------------+++async def test_replanning_replaces_old_plan(browser_session, mock_llm):+ agent = _make_agent(browser_session, mock_llm)+ agent.state.plan = [+ PlanStep(text='Old step 1', status='done'),+ PlanStep(text='Old step 2', status='current'),+ ]+ agent.state.current_plan_step_index = 1+ agent.state.plan_generation_step = 1++ output = _make_agent_output(plan_update=['New step A', 'New step B', 'New step C'])+ agent._update_plan_from_model_output(output)++ assert len(agent.state.plan) == 3+ assert agent.state.plan[0].text == 'New step A'+ assert agent.state.plan[0].status == 'current'+ assert agent.state.current_plan_step_index == 0+++# ---------------------------------------------------------------------------+# 4. _render_plan_description output format+# ---------------------------------------------------------------------------+++async def test_render_plan_description(browser_session, mock_llm):+ agent = _make_agent(browser_session, mock_llm)+ agent.state.plan = [+ PlanStep(text='Navigate to search page', status='done'),+ PlanStep(text='Search for "laptop"', status='current'),+ PlanStep(text='Extract price from results', status='pending'),+ PlanStep(text='Skipped step', status='skipped'),+ ]++ result = agent._render_plan_description()+ assert result is not None+ lines = result.split('\n')+ assert lines[0] == '[x] 0: Navigate to search page'+ assert lines[1] == '[>] 1: Search for "laptop"'+ assert lines[2] == '[ ] 2: Extract price from results'+ assert lines[3] == '[-] 3: Skipped step'+++# ---------------------------------------------------------------------------+# 5. Planning disabled returns None+# ---------------------------------------------------------------------------+++async def test_planning_disabled_returns_none(browser_session, mock_llm):+ agent = _make_agent(browser_session, mock_llm, enable_planning=False)+ agent.state.plan = [PlanStep(text='Should not render')]++ assert agent._render_plan_description() is None++ # Also verify update is a no-op+ output = _make_agent_output(plan_update=['New plan'])+ agent._update_plan_from_model_output(output)+ # Plan should remain unchanged (the method returns early)+ assert agent.state.plan[0].text == 'Should not render'+++# ---------------------------------------------------------------------------+# 6. Replan nudge injection at threshold+# ---------------------------------------------------------------------------+++async def test_replan_nudge_injected_at_threshold(browser_session, mock_llm):+ agent = _make_agent(browser_session, mock_llm, planning_replan_on_stall=3)+ agent.state.plan = [PlanStep(text='Step 1', status='current')]+ agent.state.consecutive_failures = 3++ # Track context messages+ initial_count = len(agent._message_manager.state.history.context_messages)+ agent._inject_replan_nudge()+ after_count = len(agent._message_manager.state.history.context_messages)++ assert after_count == initial_count + 1+ msg = agent._message_manager.state.history.context_messages[-1]+ assert isinstance(msg.content, str) and 'REPLAN SUGGESTED' in msg.content+++# ---------------------------------------------------------------------------+# 7. No nudge below threshold+# ---------------------------------------------------------------------------+++async def test_no_replan_nudge_below_threshold(browser_session, mock_llm):+ agent = _make_agent(browser_session, mock_llm, planning_replan_on_stall=3)+ agent.state.plan = [PlanStep(text='Step 1', status='current')]+ agent.state.consecutive_failures = 2++ initial_count = len(agent._message_manager.state.history.context_messages)+ agent._inject_replan_nudge()+ after_count = len(agent._message_manager.state.history.context_messages)++ assert after_count == initial_count+++# ---------------------------------------------------------------------------+# 8. Flash mode schema excludes plan fields+# ---------------------------------------------------------------------------+++async def test_flash_mode_schema_excludes_plan_fields():+ tools = Tools()+ ActionModel = tools.registry.create_action_model()+ FlashOutput = AgentOutput.type_with_custom_actions_flash_mode(ActionModel)++ schema = FlashOutput.model_json_schema()+ assert 'current_plan_step' not in schema['properties']+ assert 'plan_update' not in schema['properties']+ assert 'thinking' not in schema['properties']+++# ---------------------------------------------------------------------------+# 9. Full mode schema includes plan fields as optional+# ---------------------------------------------------------------------------+++async def test_full_mode_schema_includes_plan_fields_optional():+ tools = Tools()+ ActionModel = tools.registry.create_action_model()+ FullOutput = AgentOutput.type_with_custom_actions(ActionModel)++ schema = FullOutput.model_json_schema()+ assert 'current_plan_step' in schema['properties']+ assert 'plan_update' in schema['properties']+ # They should NOT be in required+ assert 'current_plan_step' not in schema.get('required', [])+ assert 'plan_update' not in schema.get('required', [])+++# ---------------------------------------------------------------------------+# 10. Out-of-bounds current_plan_step handled gracefully+# ---------------------------------------------------------------------------+++async def test_out_of_bounds_plan_step_clamped(browser_session, mock_llm):+ agent = _make_agent(browser_session, mock_llm)+ agent.state.plan = [+ PlanStep(text='Step A', status='current'),+ PlanStep(text='Step B'),+ ]+ agent.state.current_plan_step_index = 0++ # Way out of bounds high+ output = _make_agent_output(current_plan_step=999)+ agent._update_plan_from_model_output(output)+ assert agent.state.current_plan_step_index == 1 # clamped to last valid index+ assert agent.state.plan[0].status == 'done'+ assert agent.state.plan[1].status == 'current'++ # Negative index+ agent.state.plan = [+ PlanStep(text='Step X', status='current'),+ PlanStep(text='Step Y'),+ ]+ agent.state.current_plan_step_index = 1+ output2 = _make_agent_output(current_plan_step=-5)+ agent._update_plan_from_model_output(output2)+ assert agent.state.current_plan_step_index == 0 # clamped to 0+ assert agent.state.plan[0].status == 'current'+++# ---------------------------------------------------------------------------+# 11. No plan means render returns None+# ---------------------------------------------------------------------------+++async def test_no_plan_render_returns_none(browser_session, mock_llm):+ agent = _make_agent(browser_session, mock_llm)+ assert agent.state.plan is None+ assert agent._render_plan_description() is None+++# ---------------------------------------------------------------------------+# 12. Replan nudge disabled when planning_replan_on_stall=0+# ---------------------------------------------------------------------------+++async def test_replan_nudge_disabled_when_zero(browser_session, mock_llm):+ agent = _make_agent(browser_session, mock_llm, planning_replan_on_stall=0)+ agent.state.plan = [PlanStep(text='Step 1', status='current')]+ agent.state.consecutive_failures = 100 # high but doesn't matter++ initial_count = len(agent._message_manager.state.history.context_messages)+ agent._inject_replan_nudge()+ after_count = len(agent._message_manager.state.history.context_messages)+ assert after_count == initial_count+++# ---------------------------------------------------------------------------+# 13. No nudge when no plan exists+# ---------------------------------------------------------------------------+++async def test_no_replan_nudge_without_plan(browser_session, mock_llm):+ agent = _make_agent(browser_session, mock_llm, planning_replan_on_stall=1)+ agent.state.consecutive_failures = 5 # above threshold++ initial_count = len(agent._message_manager.state.history.context_messages)+ agent._inject_replan_nudge()+ after_count = len(agent._message_manager.state.history.context_messages)+ assert after_count == initial_count