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
Docs with simplified browser
Magnus Müller10738347ac53
diff --git a/docs/customize/agent-basic.mdx b/docs/customize/agent-basic.mdxindex 7d897800a..1b7892cf1 100644--- a/docs/customize/agent-basic.mdx+++ b/docs/customize/agent-basic.mdx@@ -1,5 +1,5 @@----title: "Basic Setup"+title: "Basics"description: ""icon: "play"mode: "wide"diff --git a/docs/customize/agent-parameters.mdx b/docs/customize/agent-parameters.mdxindex ec8015023..58b794e0d 100644--- a/docs/customize/agent-parameters.mdx+++ b/docs/customize/agent-parameters.mdx@@ -10,7 +10,7 @@ mode: "wide"### Core Settings- `controller`: Registry of [our tools](https://github.com/browser-use/browser-use/blob/main/browser_use/controller/service.py) the agent can call. [Example for custom tools](https://github.com/browser-use/browser-use/tree/main/examples/custom-functions)-- `browser_session`: BrowserSession object where you can specify the browser settings.+- `browser`: Browser object where you can specify the browser settings.- `output_model_schema`: Pydantic model class for structured output validation. [Example](https://github.com/browser-use/browser-use/blob/main/examples/features/custom_output.py)### Vision & Processingdiff --git a/docs/customize/browser-basic.mdx b/docs/customize/browser-basic.mdxindex f279ca91f..6f7482f5a 100644--- a/docs/customize/browser-basic.mdx+++ b/docs/customize/browser-basic.mdx@@ -1,5 +1,5 @@----title: "Browser Quickstart"+title: "Basics"description: ""icon: "globe"---@@ -10,15 +10,14 @@ icon: "globe"```pythonfrom browser_use import Agent, Browser, ChatOpenAI-# Browser is an alias for BrowserSession - use whichever you prefer-session = Browser(+browser = Browser(headless=False, # Show browser windowwindow_size={'width': 1000, 'height': 700}, # Set window size)agent = Agent(task='Search for Browser Use',- browser_session=session,+ browser=browser,llm=ChatOpenAI(model='gpt-4.1-mini'),)diff --git a/docs/customize/browser-keep-open.mdx b/docs/customize/browser-keep-open.mdxindex 51e231611..9fe85479c 100644--- a/docs/customize/browser-keep-open.mdx+++ b/docs/customize/browser-keep-open.mdx@@ -1,5 +1,5 @@----title: "Chain Agents in one browser"+title: "Chain agents in one browser"description: ""icon: "window-restore"mode: "wide"@@ -17,13 +17,13 @@ browser = Browser(async def main():# Run multiple agents with the same browser- agent1 = Agent(task='Search for Browser Use', browser_session=browser)+ agent1 = Agent(task='Search for Browser Use', browser=browser)await agent1.run()- agent2 = Agent(task='Click on the first link', browser_session=browser)+ agent2 = Agent(task='Click on the first link', browser=browser)await agent2.run()- agent3 = Agent(task='Find the social media page', browser_session=browser)+ agent3 = Agent(task='Find the social media page', browser=browser)await agent3.run()# Close browser when completely donediff --git a/docs/customize/browser-real-browser.mdx b/docs/customize/browser-real-browser.mdxindex e35164ac8..ac7998d0d 100644--- a/docs/customize/browser-real-browser.mdx+++ b/docs/customize/browser-real-browser.mdx@@ -36,9 +36,9 @@ chrome.exe --remote-debugging-port=9222 --user-data-dir="./chrome-profile"Then connect Browser Use:```python-from browser_use import BrowserSession+from browser_use import Browser-session = BrowserSession(+session = Browser(cdp_url="http://localhost:9222",is_local=False # Don't launch new browser)@@ -49,7 +49,7 @@ session = BrowserSession(Connect to an existing Chrome profile:```python-session = BrowserSession(+session = Browser(user_data_dir="/path/to/existing/chrome/profile",executable_path="/path/to/chrome", # Optional: specify browser location)@@ -71,7 +71,7 @@ profile = BrowserProfile(storage_state="./auth.json", # Load authentication state)-session = BrowserSession(browser_profile=profile)+session = Browser(browser_profile=profile)```### Profile Organization@@ -97,7 +97,7 @@ profiles = {}# Use different profiles for different environments-test_session = BrowserSession(browser_profile=profiles["testing"])+test_session = Browser(browser_profile=profiles["testing"])```## Authentication & Cookies@@ -106,13 +106,13 @@ test_session = BrowserSession(browser_profile=profiles["testing"])```python# Method 1: Storage state (recommended)-session = BrowserSession(+session = Browser(storage_state="./saved-auth.json",user_data_dir=None # Use temporary profile with loaded auth)# Method 2: Existing profile with cookies-session = BrowserSession(+session = Browser(user_data_dir="./authenticated-profile")```@@ -127,23 +127,23 @@ npx playwright open --save-storage=./auth.json https://example.com# Or use Chrome directlygoogle-chrome --user-data-dir="./auth-profile" https://example.com-# Login manually, then use the profile path in BrowserSession+# Login manually, then use the profile path in Browser```### Saving Authentication for Reuse```python# Keep browser alive to maintain session-session = BrowserSession(+session = Browser(keep_alive=True, # Don't close browser after agent finishesuser_data_dir="./persistent-auth")# Run multiple agents with same authentication-agent1 = Agent(task="Check email", browser_session=session)+agent1 = Agent(task="Check email", browser=session)await agent1.run()-agent2 = Agent(task="Update profile", browser_session=session)+agent2 = Agent(task="Update profile", browser=session)await agent2.run()# Manually close when done@@ -156,7 +156,7 @@ await session.stop()```python# Connect to browser with your installed extensions-session = BrowserSession(+session = Browser(user_data_dir="/path/to/chrome/profile/with/extensions",# Extensions will be available automatically)@@ -167,7 +167,7 @@ session = BrowserSession(Browser Use includes automation-friendly extensions:```python-session = BrowserSession(+session = Browser(enable_default_extensions=True, # Includes uBlock Origin, cookie handlersuser_data_dir="./profile-with-extensions")@@ -179,7 +179,7 @@ session = BrowserSession(```python# Use specific browser installation-session = BrowserSession(+session = Browser(executable_path="/opt/google/chrome/chrome",channel="chrome", # or "chromium", "chrome-beta", etc.user_data_dir="./custom-profile"@@ -192,7 +192,7 @@ session = BrowserSession(# Run multiple browsers simultaneouslysessions = []for i in range(3):- session = BrowserSession(+ session = Browser(user_data_dir=f"./profile-{i}",cdp_url=f"http://localhost:{9222 + i}", # Different portsis_local=False@@ -224,7 +224,7 @@ for i in range(3):### Connection Issues```python# Check if CDP port is available-session = BrowserSession(+session = Browser(cdp_url="http://localhost:9222",timeout=5000 # Fail fast if can't connect)@@ -233,7 +233,7 @@ session = BrowserSession(### Profile Conflicts```python# Avoid conflicts with existing browser instances-session = BrowserSession(+session = Browser(user_data_dir="./unique-profile-name", # Use unique directory# Don't use default Chrome profile if Chrome is already running)@@ -242,7 +242,7 @@ session = BrowserSession(### Permission Issues```python# Grant required permissions-session = BrowserSession(+session = Browser(permissions=['clipboard-read', 'clipboard-write', 'notifications'],bypass_csp=True # If needed for specific sites)diff --git a/docs/customize/browser-remote.mdx b/docs/customize/browser-remote.mdxindex 4d7871806..d88180961 100644--- a/docs/customize/browser-remote.mdx+++ b/docs/customize/browser-remote.mdx@@ -26,10 +26,10 @@ Connect Browser Use to browsers running on remote servers, containers, or cloudConnect to a browser with Chrome DevTools Protocol:```python-from browser_use import BrowserSession+from browser_use import Browser# Connect to remote browser-session = BrowserSession(+session = Browser(cdp_url="http://remote-server:9222",is_local=False # Important: don't try to launch local browser)@@ -40,7 +40,7 @@ session = BrowserSession(For secured remote browsers:```python-session = BrowserSession(+session = Browser(cdp_url="http://username:password@remote-server:9222",headers={'Authorization': 'Bearer your-token'},is_local=False@@ -67,7 +67,7 @@ docker run -d \Connect from Browser Use:```python-session = BrowserSession(+session = Browser(cdp_url="http://localhost:9222",is_local=False)@@ -129,7 +129,7 @@ cloud_browsers = []sessions = [- BrowserSession(cdp_url=url, is_local=False)+ Browser(cdp_url=url, is_local=False)for url in cloud_browsers]```@@ -141,7 +141,7 @@ sessions = [```pythonfrom browser_use.browser.profile import ProxySettings-session = BrowserSession(+session = Browser(cdp_url="http://remote-server:9222",proxy=ProxySettings(server="http://proxy-server:8080",@@ -155,7 +155,7 @@ session = BrowserSession(### Remote with Specific Settings```python-session = BrowserSession(+session = Browser(cdp_url="http://remote-server:9222",viewport={'width': 1920, 'height': 1080},user_agent="Mozilla/5.0 Custom Agent",@@ -172,7 +172,7 @@ session = BrowserSession(class BrowserPool:def __init__(self, remote_urls):self.sessions = [- BrowserSession(cdp_url=url, is_local=False)+ Browser(cdp_url=url, is_local=False)for url in remote_urls]self.current = 0@@ -191,7 +191,7 @@ pool = BrowserPool([# Get available browser for each tasksession = pool.get_session()-agent = Agent(task="Process data", browser_session=session)+agent = Agent(task="Process data", browser=session)```### Health Checking@@ -217,7 +217,7 @@ healthy_urls = []sessions = [- BrowserSession(cdp_url=url, is_local=False)+ Browser(cdp_url=url, is_local=False)for url in healthy_urls]```@@ -228,7 +228,7 @@ sessions = [```python# Use HTTPS when possible-session = BrowserSession(+session = Browser(cdp_url="https://secure-browser.example.com:9222",headers={'X-API-Key': 'your-secure-key'},is_local=False@@ -239,7 +239,7 @@ session = BrowserSession(```python# Restrict browser network access-session = BrowserSession(+session = Browser(cdp_url="http://isolated-browser:9222",allowed_domains=['*.trusted-domain.com'], # Only allow specific domainsdisable_security=False, # Keep security features enabled@@ -254,11 +254,11 @@ session = BrowserSession(```python# Process multiple tasks on same remote browserasync def batch_process(tasks, cdp_url):- session = BrowserSession(cdp_url=cdp_url, is_local=False, keep_alive=True)+ session = Browser(cdp_url=cdp_url, is_local=False, keep_alive=True)results = []for task in tasks:- agent = Agent(task=task, browser_session=session)+ agent = Agent(task=task, browser=session)result = await agent.run()results.append(result)@@ -270,7 +270,7 @@ async def batch_process(tasks, cdp_url):```python# Monitor resource usage-session = BrowserSession(+session = Browser(cdp_url="http://remote-browser:9222",viewport={'width': 1280, 'height': 720}, # Smaller viewport for lower memoryheadless=True, # No display resources needed@@ -283,7 +283,7 @@ session = BrowserSession(### Connection Timeouts```python-session = BrowserSession(+session = Browser(cdp_url="http://slow-remote:9222",timeout=120000, # 2 minute timeoutslow_mo=100, # Slow down actions for stability@@ -300,7 +300,7 @@ import asyncioasync def connect_with_retry(cdp_url, max_attempts=3):for attempt in range(max_attempts):try:- session = BrowserSession(cdp_url=cdp_url, is_local=False)+ session = Browser(cdp_url=cdp_url, is_local=False)await session.start()return sessionexcept Exception as e:@@ -316,7 +316,7 @@ async def connect_with_retry(cdp_url, max_attempts=3):import logginglogging.getLogger('browser_use').setLevel(logging.DEBUG)-session = BrowserSession(+session = Browser(cdp_url="http://remote:9222",is_local=False)diff --git a/docs/customize/custom-functions.mdx b/docs/customize/custom-functions.mdxindex 87bad6a6a..986b075eb 100644--- a/docs/customize/custom-functions.mdx+++ b/docs/customize/custom-functions.mdx@@ -60,7 +60,7 @@ When the LLM calls an action, it sees its argument names & types, and will provi```python@controller.action('Click element')-async def click_element(css_selector: str, browser_session: BrowserSession) -> ActionResult:+async def click_element(css_selector: str, browser_session: Browser) -> ActionResult:# css_selector is an action param the LLM must provide when calling# browser_session is a special framework-provided param to access the browser APIs (see below)@@ -98,7 +98,7 @@ class MyParams(BaseModel):field4: str = Field(default='abc', description='Detailed description for the LLM')@controller.action('My action', param_model=MyParams)-async def my_action(params: MyParams, browser_session: BrowserSession) -> ActionResult:+async def my_action(params: MyParams, browser_session: Browser) -> ActionResult:# Get the current CDP session to interact with the browsercdp_session = await browser_session.get_or_create_cdp_session()@@ -130,7 +130,7 @@ These special action parameters are injected by the `Controller` and are passedFor example, actions that need to interact with the browser should take the `browser_session` argument.-- `browser_session: BrowserSession` - The current browser session with access to CDP for browser interaction+- `browser_session: Browser` - The current browser session with access to CDP for browser interaction- `context: AgentContext` - Any optional top-level context object passed to the Agent, e.g. `Agent(context=user_provided_obj)`- `page_extraction_llm: BaseChatModel` - LLM instance used for page content extraction- `available_file_paths: list[str]` - List of available file paths for upload / processing@@ -142,7 +142,7 @@ Browser Use has moved from Playwright to Chrome DevTools Protocol (CDP) for brow### Understanding the Browser Session Context-The `BrowserSession` object provides multiple ways to interact with the browser:+The `Browser` object provides multiple ways to interact with the browser:#### 1. Direct CDP Access```python@@ -215,12 +215,12 @@ tabs = await browser_session.get_tabs()#### Example: Action uses the current browser session```python-from browser_use import BrowserSession, Controller, ActionResult+from browser_use import Browser, Controller, ActionResultcontroller = Controller()@controller.action('Type keyboard input into a page')-async def input_text_into_page(text: str, browser_session: BrowserSession) -> ActionResult:+async def input_text_into_page(text: str, browser_session: Browser) -> ActionResult:# Get the current CDP session to interact with the browsercdp_session = await browser_session.get_or_create_cdp_session()@@ -235,13 +235,13 @@ async def input_text_into_page(text: str, browser_session: BrowserSession) -> Ac#### Example: Action uses browser session for tab management```python-from browser_use import BrowserSession, Controller, ActionResult+from browser_use import Browser, Controller, ActionResultfrom browser_use.browser.events import NavigateToUrlEvent, SwitchTabEventcontroller = Controller()@controller.action('Open website')-async def open_website(url: str, browser_session: BrowserSession) -> ActionResult:+async def open_website(url: str, browser_session: Browser) -> ActionResult:# Get all open tabstabs = await browser_session.get_tabs()@@ -271,7 +271,7 @@ async def open_website(url: str, browser_session: BrowserSession) -> ActionResulAction arguments are always matched by name and type, **not** positional order, so this helps prevent ambiguity / reordering issues while keeping action signatures short.```python@controller.action('Fill in the country form field')- async def input_country_field(country: str, browser_session: BrowserSession) -> ActionResult:+ async def input_country_field(country: str, browser_session: Browser) -> ActionResult:await some_action(123, browser_session=browser_session) # ❌ not allowed: positional args, use kwarg syntax when callingawait some_action(abc=123, browser_session=browser_session) # ✅ allowed: action params & special kwargsawait some_other_action(params=OtherAction(abc=123), browser_session=browser_session) # ✅ allowed: params=model & special kwargs@@ -284,12 +284,12 @@ class PinCodeParams(BaseModel):retries: int = 3 # ✅ supports optional/defaults@controller.action('...', param_model=PinCodeParams)-async def input_pin_code(params: PinCodeParams, browser_session: BrowserSession): ... # ✅ special params at the end+async def input_pin_code(params: PinCodeParams, browser_session: Browser): ... # ✅ special params at the end# Using function arguments to define action params-async def input_pin_code(code: int, retries: int, browser_session: BrowserSession): ... # ✅ params first, special params second, no defaults+async def input_pin_code(code: int, retries: int, browser_session: Browser): ... # ✅ params first, special params second, no defaultsasync def input_pin_code(code: int, retries: int=3): ... # ✅ defaults ok only if no special params needed-async def input_pin_code(code: int, retries: int=3, browser_session: BrowserSession): ... # ❌ Python SyntaxError! not allowed+async def input_pin_code(code: int, retries: int=3, browser_session: Browser): ... # ❌ Python SyntaxError! not allowed```diff --git a/docs/customize/hooks.mdx b/docs/customize/hooks.mdxindex d4f47d02b..ede04c056 100644--- a/docs/customize/hooks.mdx+++ b/docs/customize/hooks.mdx@@ -96,7 +96,7 @@ When working with agent hooks, you have access to the entire `Agent` instance. H- `agent.history.model_actions()`: Actions taken by the agent- `agent.history.extracted_content()`: Content extracted from web pages- `agent.history.urls()`: URLs visited by the agent-- `agent.browser_session` gives direct access to the `BrowserSession()` and CDP interface+- `agent.browser_session` gives direct access to the `Browser()` and CDP interface- `agent.browser_session.agent_focus`: Get the current CDP session the agent is focused on- `agent.browser_session.get_or_create_cdp_session()`: Get the current CDP session for browser interaction- `agent.browser_session.get_tabs()`: Get all tabs currently opendiff --git a/docs/customize/mcp-server.mdx b/docs/customize/mcp-server.mdxindex 06eb13385..5bcdbd5a0 100644--- a/docs/customize/mcp-server.mdx+++ b/docs/customize/mcp-server.mdx@@ -18,7 +18,7 @@ The MCP server acts as a bridge between MCP-compatible AI assistants and browser```mermaidgraph LRA[Claude Desktop] -->|MCP Protocol| B[Browser-use MCP Server]- B --> C[BrowserSession]+ B --> C[Browser]B --> D[Controller]B --> E[FileSystem]C --> F[Playwright Browser]@@ -380,7 +380,7 @@ uvx 'browser-use[cli]' --mcpplaywright install chromium# Test browser launch-python -c "from browser_use import BrowserSession; import asyncio; asyncio.run(BrowserSession().start())"+python -c "from browser_use import Browser; import asyncio; asyncio.run(Browser().start())"```### Connection Errorsdiff --git a/docs/customize/real-browser.mdx b/docs/customize/real-browser.mdxindex 1ae852882..08c7246da 100644--- a/docs/customize/real-browser.mdx+++ b/docs/customize/real-browser.mdx@@ -27,10 +27,10 @@ We provide automatic CAPTCHA solving, proxies, human-in-the-loop automation, andLaunch a local browser using built-in default (Playwright-installed `chromium`) or a provided `executable_path`:```python-from browser_use import Agent, BrowserSession+from browser_use import Agent, Browser# If no executable_path provided, uses Playwright/Patchright's built-in Chromium-browser_session = BrowserSession(+browser = Browser(# Path to a specific Chromium-based executable (optional)executable_path='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', # macOS# For Windows: 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'@@ -45,7 +45,7 @@ browser_session = BrowserSession(agent = Agent(task="Your task here",llm=llm,- browser_session=browser_session,+ browser=browser,)```@@ -68,10 +68,10 @@ We support most `chromium`-based browsers in `executable_path`, including [BraveConnect to a remote browser instance using Chrome DevTools Protocol:```python-from browser_use import Agent, BrowserSession+from browser_use import Agent, Browser# Connect to a remote browser (e.g., running in Docker, cloud, or another machine)-browser_session = BrowserSession(+browser = Browser(cdp_url="ws://remote-browser:9222/devtools/browser", # Remote CDP WebSocket URLis_local=False, # Important: set to False for remote connections)@@ -79,7 +79,7 @@ browser_session = BrowserSession(agent = Agent(task="Your task here",llm=llm,- browser_session=browser_session,+ browser=browser,)```@@ -90,7 +90,7 @@ Playwright Page/Browser/Context objects are no longer supported. Browser Use nowYou can also use HTTP-based CDP connections:```python-browser_session = BrowserSession(+browser = Browser(cdp_url="http://remote-browser:9222", # Remote CDP HTTP URLis_local=False,)@@ -98,7 +98,7 @@ browser_session = BrowserSession(agent = Agent(task="Your task here",llm=llm,- browser_session=browser_session,+ browser=browser,)```@@ -107,18 +107,18 @@ agent = Agent(Connect to a browser with open `--remote-debugging-port`:```python-from browser_use import Agent, BrowserSession+from browser_use import Agent, Browser# First, start Chrome with remote debugging:# /Applications/Google Chrome.app/Contents/MacOS/Google Chrome --remote-debugging-port=9242# Then connect using the process ID-browser_session = BrowserSession(browser_pid=12345) # Replace with actual Chrome PID+browser = Browser(browser_pid=12345) # Replace with actual Chrome PIDagent = Agent(task="Your task here",llm=llm,- browser_session=browser_session,+ browser=browser,)```@@ -127,15 +127,15 @@ agent = Agent(Connect to Playwright Node.js server providers:```python-from browser_use import Agent, BrowserSession+from browser_use import Agent, Browser# Connect to a playwright server-browser_session = BrowserSession(wss_url="wss://your-playwright-server.com/ws")+browser = Browser(wss_url="wss://your-playwright-server.com/ws")agent = Agent(task="Your task here",llm=llm,- browser_session=browser_session,+ browser=browser,)```@@ -144,15 +144,15 @@ agent = Agent(Connect to any remote Chromium-based browser:```python-from browser_use import Agent, BrowserSession+from browser_use import Agent, Browser# Connect to Chrome via CDP-browser_session = BrowserSession(cdp_url="http://localhost:9222")+browser = Browser(cdp_url="http://localhost:9222")agent = Agent(task="Your task here",llm=llm,- browser_session=browser_session,+ browser=browser,)```@@ -166,7 +166,7 @@ agent = Agent(- Extensions and their dataAlways review the task you're giving to the agent and ensure it aligns with your security requirements!- Use `Agent(sensitive_data={'https://auth.example.com': {x_key: value}})` for any secrets, and restrict the browser with `BrowserSession(allowed_domains=['https://*.example.com'])`.+ Use `Agent(sensitive_data={'https://auth.example.com': {x_key: value}})` for any secrets, and restrict the browser with `Browser(allowed_domains=['https://*.example.com'])`.</Warning>## Best Practices@@ -174,7 +174,7 @@ agent = Agent(1. **Use isolated profiles**: Create separate Chrome profiles for different agents to limit scope of risk:```python- browser_session = BrowserSession(+ browser = Browser(user_data_dir='~/.config/browseruse/profiles/banking',# profile_directory='Default')@@ -183,40 +183,40 @@ agent = Agent(2. **Limit domain access**: Restrict which sites the agent can visit:```python- browser_session = BrowserSession(+ browser = Browser(allowed_domains=['example.com', 'http*://*.github.com'],)```-3. **Enable `keep_alive=True`** If you want to use a single `BrowserSession` with more than one agent:+3. **Enable `keep_alive=True`** If you want to use a single `Browser` with more than one agent:```python- browser_session = BrowserSession(+ browser = Browser(keep_alive=True,...)- await browser_session.start() # start the session yourself before passing to Agent+ await browser.start() # start the session yourself before passing to Agent...- agent = Agent(..., browser_session=browser_session)+ agent = Agent(..., browser=browser)await agent.run()...- await browser_session.kill() # end the session yourself, shortcut for keep_alive=False + .stop()+ await browser.kill() # end the session yourself, shortcut for keep_alive=False + .stop()```## Re-Using a Browser-A `BrowserSession` starts when the browser is launched/connected, and ends when the browser process exits/disconnects. A session internally manages a single live playwright browser context, and is normally auto-closed by the agent when its task is complete (_if_ the agent started the session itself). If you pass an existing `BrowserSession` into an Agent, or if you set `BrowserSession(keep_alive=True)`, the session will not be closed and can be re-used between agents.+A `Browser` starts when the browser is launched/connected, and ends when the browser process exits/disconnects. A session internally manages a single live playwright browser context, and is normally auto-closed by the agent when its task is complete (_if_ the agent started the session itself). If you pass an existing `Browser` into an Agent, or if you set `Browser(keep_alive=True)`, the session will not be closed and can be re-used between agents.Browser Use provides a number of ways to re-use profiles, sessions, and other configuration across multiple agents.-- ✅ sequential agents can re-use a single `user_data_dir` in new `BrowserSession`s-- ✅ sequential agents can re-use a single `BrowserSession` without closing it-- ❌ parallel agents cannot run separate `BrowserSession`s using the same `user_data_dir`-- ✅ parallel agents can run separate `BrowserSession`s using the same `storage_state`-- ✅ parallel agents can share a single `BrowserSession`, working in different tabs-- ⚠️ parallel agents can share a single `BrowserSession`, working in the same tab+- ✅ sequential agents can re-use a single `user_data_dir` in new `Browser`s+- ✅ sequential agents can re-use a single `Browser` without closing it+- ❌ parallel agents cannot run separate `Browser`s using the same `user_data_dir`+- ✅ parallel agents can run separate `Browser`s using the same `storage_state`+- ✅ parallel agents can share a single `Browser`, working in different tabs+- ⚠️ parallel agents can share a single `Browser`, working in the same tab<Important>- Multiple `BrowserSession`s (aka chrome processes) cannot share the same+ Multiple `Browser`s (aka chrome processes) cannot share the same`user_data_dir` at the same time, but they can share a `storage_state` file or`BrowserProfile` config.</Important>@@ -226,7 +226,7 @@ Browser Use provides a number of ways to re-use profiles, sessions, and other coIf you are only running one agent & browser at a time, they can re-use the same `user_data_dir` sequentially.```python-from browser_use import Agent, BrowserSession+from browser_use import Agent, Browserfrom browser_use.llm import ChatOpenAIreused_profile = BrowserProfile(user_data_dir='~/.config/browseruse/profiles/default')@@ -250,14 +250,14 @@ await agent2.run()### Sequential Agents, Same Profile, Same Browser-If you are only running one agent at a time, they can re-use the same active `BrowserSession` and avoid having to relaunch chrome.+If you are only running one agent at a time, they can re-use the same active `Browser` and avoid having to relaunch chrome.Each agent will start off looking at the same tab the last agent ended off on.```python-from browser_use import Agent, BrowserSession+from browser_use import Agent, Browserfrom browser_use.llm import ChatOpenAI-reused_session = BrowserSession(+reused_session = Browser(user_data_dir='~/.config/browseruse/profiles/default',keep_alive=True, # dont close browser after 1st agent.run() ends)@@ -266,14 +266,14 @@ await reused_session.start() # when keep_alive=True, session must be started magent1 = Agent(task="The first task...",llm=ChatOpenAI(model="gpt-4.1-mini-mini"),- browser_session=reused_session,+ browser=reused_session,)await agent1.run()agent2 = Agent(task="The second task...",llm=ChatOpenAI(model="gpt-4.1-mini-mini"),- browser_session=reused_session, # re-use the same session+ browser=reused_session, # re-use the same session)await agent2.run()@@ -284,35 +284,35 @@ await reused_session.close()```pythonimport asyncio-from browser_use import Agent, BrowserSession+from browser_use import Agent, Browserfrom browser_use.llm import ChatOpenAIfrom browser_use.browser.events import NavigateToUrlEvent# Create a shared browser session-browser_session = BrowserSession()-await browser_session.start()+browser = Browser()+await browser.start()# Create tabs for each agent using events-tab1_event = browser_session.event_bus.dispatch(NavigateToUrlEvent(url="about:blank", new_tab=True))+tab1_event = browser.event_bus.dispatch(NavigateToUrlEvent(url="about:blank", new_tab=True))await tab1_event-tab2_event = browser_session.event_bus.dispatch(NavigateToUrlEvent(url="about:blank", new_tab=True))+tab2_event = browser.event_bus.dispatch(NavigateToUrlEvent(url="about:blank", new_tab=True))await tab2_event# Get tab information-tabs = await browser_session.get_tabs()+tabs = await browser.get_tabs()# Create agents that will work with different tabsagent1 = Agent(task="The first task...",llm=ChatOpenAI(model="gpt-4.1-mini-mini"),- browser_session=browser_session,+ browser=browser,)agent2 = Agent(task="The second task...",llm=ChatOpenAI(model="gpt-4.1-mini-mini"),- browser_session=browser_session,+ browser=browser,)# Run agents in parallel (they will automatically coordinate tab switching)@@ -329,12 +329,12 @@ await asyncio.gather(agent1.run(), agent2.run())```pythonimport asyncio-from browser_use import Agent, BrowserSession+from browser_use import Agent, Browserfrom browser_use.llm import ChatOpenAIfrom browser_use.browser.events import NavigateToUrlEvent# Create a shared browser session-shared_session = BrowserSession()+shared_session = Browser()await shared_session.start()# Navigate to the target page@@ -344,12 +344,12 @@ await navigate_eventagent1 = Agent(task="Fill out the form in section A...",llm=ChatOpenAI(model="gpt-4.1-mini-mini"),- browser_session=shared_session+ browser=shared_session)agent2 = Agent(task="Fill out the form in section B...",llm=ChatOpenAI(model="gpt-4.1-mini-mini"),- browser_session=shared_session,+ browser=shared_session,)# Run agents in parallel on the same tab (not recommended)@@ -373,7 +373,7 @@ playwright open https://example.com/ --load-storage=/tmp/auth.json``````python-from browser_use.browser import BrowserProfile, BrowserSession+from browser_use.browser import BrowserProfile, Browsershared_profile = BrowserProfile(headless=True,@@ -382,13 +382,13 @@ shared_profile = BrowserProfile(keep_alive=True, # don't close the browser after the agent finishes)-window1 = BrowserSession(browser_profile=shared_profile)+window1 = Browser(browser_profile=shared_profile)await window1.start()-agent1 = Agent(browser_session=window1)+agent1 = Agent(browser=window1)-window2 = BrowserSession(browser_profile=shared_profile)+window2 = Browser(browser_profile=shared_profile)await window2.start()-agent2 = Agent(browser_session=window2)+agent2 = Agent(browser=window2)await asyncio.gather(agent1.run(), agent2.run()) # run in parallelawait window1.save_storage_state() # write storage state (cookies, localStorage, etc.) to auth.json@@ -421,7 +421,7 @@ If you're having trouble connecting:If you get a "profile is already in use" error:1. Close all Chrome instances-2. The profile will automatically be unlocked when BrowserSession starts+2. The profile will automatically be unlocked when Browser starts3. Alternatively, manually delete the `SingletonLock` file in the profile directory<Note>diff --git a/docs/customize/sensitive-data.mdx b/docs/customize/sensitive-data.mdxindex 68a194c19..56d4e39e8 100644--- a/docs/customize/sensitive-data.mdx+++ b/docs/customize/sensitive-data.mdx@@ -23,7 +23,7 @@ agent = Agent(<Note>-You should also configure [`BrowserSession(allowed_domains=...)`](https://docs.browser-use.com/customize/browser-settings#allowed-domains) to prevent the Agent from visiting URLs not needed for the task.+You should also configure [`Browser(allowed_domains=...)`](https://docs.browser-use.com/customize/browser-settings#allowed-domains) to prevent the Agent from visiting URLs not needed for the task.</Note>@@ -36,7 +36,7 @@ from dotenv import load_dotenvload_dotenv()from browser_use.llm import ChatOpenAI-from browser_use import Agent, BrowserSession+from browser_use import Agent, Browserllm = ChatOpenAI(model='gpt-4.1')@@ -57,13 +57,13 @@ task = """"""# Recommended: Limit the domains available for the entire browser so the Agent can't be tricked into visiting untrusted URLs-browser_session = BrowserSession(allowed_domains=['https://*.example.com'])+browser = Browser(allowed_domains=['https://*.example.com'])agent = Agent(task=task,llm=llm,sensitive_data=sensitive_data, # Pass the sensitive data to the agent- browser_session=browser_session, # Pass the restricted browser_session to limit URLs Agent can visit+ browser=browser, # Pass the restricted browser to limit URLs Agent can visituse_vision=False, # Disable vision or else the LLM might see entered values in screenshots)@@ -88,7 +88,7 @@ This approach ensures that sensitive information remains secure while still allo### Best Practices- Always restrict your sensitive data to only the exact domains that need it, `https://travel.example.com` is better than `*.example.com`-- Always restrict [`BrowserSession(allowed_domains=[...])`](https://docs.browser-use.com/customize/browser-settings#allowed-domains) to only the domains the agent needs to visit to accomplish its task. This helps guard against prompt injection attacks, jailbreaks, and LLM mistakes.+- Always restrict [`Browser(allowed_domains=[...])`](https://docs.browser-use.com/customize/browser-settings#allowed-domains) to only the domains the agent needs to visit to accomplish its task. This helps guard against prompt injection attacks, jailbreaks, and LLM mistakes.- Only use `sensitive_data` for strings that can be inputted verbatim as text. The LLM never sees the actual values, so it can't "understand" them, adapt them, or split them up for multiple input fields. For example, you can't ask the Agent to click through a datepicker UI to input the sensitive value `1990-12-31`. For these situations you can implement a [custom function](/customize/custom-functions) the LLM can call that updates the DOM using Python / JS.- Don't use `sensitive_data` for login credentials, it's better to use [`storage_state`](docs.browser-use.com/customize/browser-settings#storage-state) or a [`user_data_dir`](/customize/browser-settings#user-data-dir) to log into the sites the agent needs in advance & reuse the cookies:@@ -100,7 +100,7 @@ $ playwright open https://accounts.google.com --save-storage auth.jsonThen use those cookies when the agent runs:```python-agent = Agent(..., browser_session=BrowserSession(storage_state='./auth.json'))+agent = Agent(..., browser=Browser(storage_state='./auth.json'))```<Warning>@@ -131,7 +131,7 @@ Domain patterns in `sensitive_data` follow the same format as [`allowed_domains`The default protocol when no scheme is specified is now `https://` for enhanced security.-For convenience the system will validate that all domain patterns used in `Agent(sensitive_data)` are also included in `BrowserSession(allowed_domains)`.+For convenience the system will validate that all domain patterns used in `Agent(sensitive_data)` are also included in `Browser(allowed_domains)`.### Missing or Empty Values@@ -152,7 +152,7 @@ from dotenv import load_dotenvload_dotenv()from browser_use.llm import ChatOpenAI-from browser_use import Agent, BrowserSession+from browser_use import Agent, Browserllm = ChatOpenAI(model='gpt-4.1')@@ -165,7 +165,7 @@ sensitive_data = {}# Set browser session with allowed domains that match all domain patterns in sensitive_data-browser_session = BrowserSession(+browser = Browser(allowed_domains=['https://*.google.com','chrome-extension://abcd',@@ -179,7 +179,7 @@ agent = Agent(task="Log into Google, then check my account information",llm=llm,sensitive_data=sensitive_data,- browser_session=browser_session,+ browser=browser,use_vision=False,)