Skip to content

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

Docs with simplified browser

Magnus Müller10738347ac53
diff --git a/docs/customize/agent-basic.mdx b/docs/customize/agent-basic.mdx
index 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.mdx
index 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 & Processing
diff --git a/docs/customize/browser-basic.mdx b/docs/customize/browser-basic.mdx
index 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"
```python
from browser_use import Agent, Browser, ChatOpenAI
-# Browser is an alias for BrowserSession - use whichever you prefer
-session = Browser(
+browser = Browser(
headless=False, # Show browser window
window_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.mdx
index 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 done
diff --git a/docs/customize/browser-real-browser.mdx b/docs/customize/browser-real-browser.mdx
index 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 directly
google-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 finishes
user_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 handlers
user_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 simultaneously
sessions = []
for i in range(3):
- session = BrowserSession(
+ session = Browser(
user_data_dir=f"./profile-{i}",
cdp_url=f"http://localhost:{9222 + i}", # Different ports
is_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.mdx
index 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 cloud
Connect 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 = [
```python
from 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 task
session = 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 domains
disable_security=False, # Keep security features enabled
@@ -254,11 +254,11 @@ session = BrowserSession(
```python
# Process multiple tasks on same remote browser
async 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 memory
headless=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 timeout
slow_mo=100, # Slow down actions for stability
@@ -300,7 +300,7 @@ import asyncio
async 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 session
except Exception as e:
@@ -316,7 +316,7 @@ async def connect_with_retry(cdp_url, max_attempts=3):
import logging
logging.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.mdx
index 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 browser
cdp_session = await browser_session.get_or_create_cdp_session()
@@ -130,7 +130,7 @@ These special action parameters are injected by the `Controller` and are passed
For 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, ActionResult
controller = 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 browser
cdp_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, ActionResult
from browser_use.browser.events import NavigateToUrlEvent, SwitchTabEvent
controller = 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 tabs
tabs = await browser_session.get_tabs()
@@ -271,7 +271,7 @@ async def open_website(url: str, browser_session: BrowserSession) -> ActionResul
Action 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 calling
await some_action(abc=123, browser_session=browser_session) # ✅ allowed: action params & special kwargs
await 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 defaults
async 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.mdx
index 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 open
diff --git a/docs/customize/mcp-server.mdx b/docs/customize/mcp-server.mdx
index 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
```mermaid
graph LR
A[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]' --mcp
playwright 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 Errors
diff --git a/docs/customize/real-browser.mdx b/docs/customize/real-browser.mdx
index 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, and
Launch 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 [Brave
Connect 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 URL
is_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 now
You can also use HTTP-based CDP connections:
```python
-browser_session = BrowserSession(
+browser = Browser(
cdp_url="http://remote-browser:9222", # Remote CDP HTTP URL
is_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 PID
agent = 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 data
Always 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 co
If 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, Browser
from browser_use.llm import ChatOpenAI
reused_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, Browser
from 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 m
agent1 = 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()
```python
import asyncio
-from browser_use import Agent, BrowserSession
+from browser_use import Agent, Browser
from browser_use.llm import ChatOpenAI
from 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 tabs
agent1 = 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())
```python
import asyncio
-from browser_use import Agent, BrowserSession
+from browser_use import Agent, Browser
from browser_use.llm import ChatOpenAI
from 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_event
agent1 = 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, Browser
shared_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 parallel
await 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 starts
3. Alternatively, manually delete the `SingletonLock` file in the profile directory
<Note>
diff --git a/docs/customize/sensitive-data.mdx b/docs/customize/sensitive-data.mdx
index 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_dotenv
load_dotenv()
from browser_use.llm import ChatOpenAI
-from browser_use import Agent, BrowserSession
+from browser_use import Agent, Browser
llm = 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 visit
use_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.json
Then 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_dotenv
load_dotenv()
from browser_use.llm import ChatOpenAI
-from browser_use import Agent, BrowserSession
+from browser_use import Agent, Browser
llm = 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,
)