Planning & Follow-up Tasks
Relevant source files
The following files were used as context for generating this wiki page:
The Planning & Follow-up Tasks system in browser-use is a multi-layered mechanism designed to orchestrate complex browser automations. It involves a dedicated planning agent that breaks down high-level objectives into actionable steps, assesses progress, and identifies potential roadblocks. This system ensures that the primary agent remains focused on immediate interactions while maintaining a long-term strategy for task completion.
The architecture separates reasoning about "what to do next" (Planning) from "how to interact with the current page" (Execution). By utilizing distinct LLM prompts and intervals, the system can handle multi-step workflows like job applications, shopping, or research, where initial actions may lead to follow-up tasks based on discovered information.
Planning Architecture
The planning system is centered around the PlannerPrompt and a separate planner_llm configuration within the Agent class. It allows the agent to pause at specific intervals to re-evaluate the global state of the task.
The Planning Agent
The Agent class can be initialized with a planner_llm and a planner_interval. If configured, the agent executes the _run_planner method, which invokes a specialized system prompt to generate a JSON-structured plan.
The diagram shows how the planning cycle is interleaved with the standard agent execution loop.
Sources: browser_use/agent/service.py:126-130, browser_use/agent/service.py:1005-1045
Planner Output Structure
The planner is strictly required to output a JSON object to maintain structured reasoning. This output is then injected into the MessageManager to guide the execution agent.
| Field | Description |
|---|---|
state_analysis | Brief analysis of the current state and history. |
progress_evaluation | Evaluation of progress towards the goal (percentage/description). |
challenges | List of potential challenges or roadblocks identified. |
next_steps | 2-3 concrete next steps to take. |
reasoning | Explanation for the suggested next steps. |
Sources: browser_use/agent/prompts.py:207-213
Follow-up & Task Chaining
Follow-up tasks are managed through the interaction between the Agent's memory and the MessageManager. The system supports "Initial Actions" and "New Tasks" that can be added dynamically.
Initial Actions
When an agent starts, it can be provided with a sequence of initial_actions. These are executed before the main loop begins, allowing the developer to set the browser's state (e.g., logging in or navigating to a specific starting point) without requiring LLM reasoning for the setup phase.
Sources: browser_use/agent/service.py:461-471
Dynamic Task Updates
The add_new_task method allows for the insertion of follow-up tasks into an existing agent session. This method updates the MessageManager with new instructions while preserving the previous context, enabling the agent to transition from one objective (e.g., "Find jobs") to a follow-up (e.g., "Apply to the first link found").
This sequence illustrates how follow-up tasks are integrated into the existing message history.
Sources: browser_use/agent/service.py:214-215, browser_use/agent/message_manager/service.py:113-116
Execution Logic & Action Sequencing
The Controller and Agent manage how plans are translated into specific browser interactions.
Multi-Action Execution
The agent does not just execute one action at a time. It can return a sequence of actions (up to max_actions_per_step). The controller.multi_act method iterates through these, but includes a critical "break" check: if a new element appears on the page or the page changes after an action, the sequence is interrupted to allow the agent to re-assess the state.
Sources: browser_use/controller/service.py:349-370, browser_use/agent/prompts.py:68-80
Action Results and Memory
Every action result includes a boolean include_in_memory. If an action identifies information required for a follow-up task (like an email address or a job ID), it is explicitly stored in the task history memory.
| Component | Role in Planning |
|---|---|
ActionResult.extracted_content | Stores data found during execution for future steps. |
AgentBrain.memory | Tracks "count" of repeated tasks (e.g., "3 out of 10 applied"). |
AgentBrain.next_goal | The immediate next milestone derived from the plan. |
Sources: browser_use/agent/views.py:27-32, browser_use/agent/prompts.py:34-40
Implementation Example: Task Chaining
In complex use cases, developers use custom controller actions to bridge the gap between discovery and follow-up. For instance, a "Save jobs" action might write to a file, and a subsequent planning step would instruct the agent to "Read jobs from file" and begin a new sequence of applications.
Sources: examples/use-cases/find_and_apply_to_jobs.py:53-70
The Planning & Follow-up Tasks system provides the necessary infrastructure for browser-use to move beyond simple automation into complex, multi-stage agentic workflows. By separating strategic planning from tactical execution and allowing for dynamic task injection, the system can handle sophisticated web interactions that require persistent state and evolving objectives.