Multi-Tab & Parallel Execution

Relevant source files

The following files were used as context for generating this wiki page:

• browser_use/browser/context.py
• browser_use/controller/service.py
• browser_use/agent/prompts.py
• examples/use-cases/find_and_apply_to_jobs.py
• browser_use/browser/views.py

The Browser-Use framework enables AI agents to interact with multiple web pages simultaneously and supports parallel execution of multiple agents within the same or different browser environments. This capability is facilitated by a robust session management system that abstracts Playwright's browser contexts and pages into manageable components for LLM-driven automation.

Multi-tab handling allows an agent to research information across different sites without losing current state, while parallel execution enables complex workflows—such as job searching across multiple companies—to be performed concurrently using asyncio.gather.

Sources: browser_use/browser/context.py, examples/use-cases/find_and_apply_to_jobs.py:157-164, browser_use/agent/prompts.py:53-57

Multi-Tab Management

Tab management is handled through the BrowserContext class, which manages a BrowserSession. Each session tracks the current_page and maintains a list of available tabs as TabInfo objects. Agents can navigate, switch between, and open new tabs through specific controller actions.

Tab Navigation Actions

The Controller defines several actions specifically for multi-tab workflows:

Action	Description	Parameter Model
switch_tab	Switches the active focus to a specific tab by ID.	SwitchTabAction
open_tab	Opens a new URL in a completely new browser tab.	OpenTabAction
close_current_tab	Closes the active tab and switches focus to the first available tab.	N/A

Sources: browser_use/controller/service.py:116-136, browser_use/browser/context.py:613-625

Tab State Representation

The state of all open tabs is included in the BrowserState provided to the LLM during every step. This ensures the agent is aware of its environment and can decide when to switch contexts.

The diagram shows how a single BrowserSession maintains references to multiple pages, with one designated as the current active page.
Sources: browser_use/browser/context.py:126-130, browser_use/browser/context.py:801-813

Parallel Agent Execution

Parallelism is achieved by initializing multiple Agent instances and executing their run() methods concurrently using Python's asyncio library. This is frequently used for high-throughput tasks where different sub-tasks are assigned to individual agents.

Implementation Logic

1. Shared Resources: Multiple agents can share a single Browser instance or a single Controller instance while maintaining independent execution loops.
2. Concurrency: Using asyncio.gather(*[agent.run() for agent in agents]) allows the system to process multiple tasks without blocking.

# Example of parallelizing agents across different tasks
agents = []
for task in tasks:
    agent = Agent(task=task, llm=model, controller=controller, browser=browser)
    agents.append(agent)

await asyncio.gather(*[agent.run() for agent in agents])

Sources: examples/use-cases/find_and_apply_to_jobs.py:157-164

Execution Flow

The following sequence diagram illustrates how multiple agents interact with a shared browser context in parallel.

The diagram represents concurrent requests from two agents to a single browser context to perform separate tasks.
Sources: examples/use-cases/find_and_apply_to_jobs.py:145-164, browser_use/browser/context.py:734-740

Tab Lifecycle and Constraints

Lifecycle Management

• Creation: New tabs are created using context.new_page() or through the open_tab action.
• Switching: Switching involves page.bring_to_front() and updating the session.current_page pointer.
• Closure: When a tab is closed via close_current_tab, the system automatically defaults focus to the first available tab to prevent the session from becoming orphaned.
• Persistence: Cookies can be saved and loaded across sessions via the cookies_file configuration in BrowserContextConfig.

Sources: browser_use/browser/context.py:209-215, browser_use/browser/context.py:613-630, browser_use/browser/context.py:781-795

Domain & Security Constraints

The BrowserContextConfig allows for restricting multi-tab navigation through the allowed_domains setting. If an agent attempts to open a tab or navigate to a URL outside this whitelist, a URLNotAllowedError is raised, and the system attempts to revert the navigation.

Configuration Field	Type	Description
allowed_domains	list[str] | None	List of domains the agent is permitted to access across all tabs.
disable_security	bool	Disables CSP and HTTPS errors, often necessary for multi-site research.

Sources: browser_use/browser/context.py:91-105, browser_use/browser/context.py:488-511

Conclusion

The multi-tab and parallel execution architecture provides a scalable way to handle complex browser automation. By decoupling the BrowserContext from individual agent logic, the framework supports both single-agent multi-tasking (via tabs) and multi-agent concurrency (via asyncio). This structure ensures that agents remain context-aware of all open resources while maintaining the ability to execute distinct goals in parallel.