Skip to content

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

Remove page from docs

Magnus Müllerc6210dff6541
diff --git a/docs/customize/agent-settings.mdx b/docs/customize/agent-settings.mdx
index 6baa6b8d4..c3dc05cd6 100644
--- a/docs/customize/agent-settings.mdx
+++ b/docs/customize/agent-settings.mdx
@@ -58,9 +58,9 @@ agent = Agent(
### Reuse Existing Browser Context
-By default browser-use launches its own builtin browser using playwright chromium.
-You can also connect to a remote browser or pass any of the following
-existing playwright objects to the Agent: `page`, `browser_context`, `browser`, `browser_session`, or `browser_profile`.
+By default browser-use launches its own builtin browser using Playwright-installed chromium.
+You can also connect to a remote browser or pass `browser_session` or `browser_profile` objects to the Agent.
+
These all get passed down to create a `BrowserSession` for the `Agent`:
@@ -79,12 +79,7 @@ agent = Agent(
executable_path=... # provide a custom chrome binary path
# or
channel=... # specify chrome, chromium, ms-edge, etc.
- # or
- page=page, # use an existing playwright Page object
- # or
- browser_context=browser_context, # use an existing playwright BrowserContext object
- # or
- browser=browser, # use an existing playwright Browser object
+
),
)
```
diff --git a/docs/customize/browser-settings.mdx b/docs/customize/browser-settings.mdx
index dbec43905..a3c9d2e11 100644
--- a/docs/customize/browser-settings.mdx
+++ b/docs/customize/browser-settings.mdx
@@ -34,7 +34,7 @@ agent = Agent('fill out the form on this page', browser_session=browser_session)
## `BrowserSession`
- `BrowserSession(**params)` is Browser Use's object that tracks a connection to a running browser. It sets up:
- - the `playwright`, `browser`, `browser_context`, and `page` objects and tracks which tabs the agent/human are focused on
+ - the CDP client connection and tracks which tabs the agent is focused on
- methods to interact with the browser window, apply config needed by the Agent, and run the `DOMService` for element detection
- it can take a `browser_profile=BrowserProfile(...)` template containing some config defaults, and `**kwargs` session-specific config overrides
@@ -159,8 +159,12 @@ This is useful because a user may only have 2 or 3 profiles, but they could have
- [Playwright parameters](#playwright)
- [Browser-Use parameters](#browser-use-parameters) (extra options we provide on top of `playwright`)
-The only parameters `BrowserProfile` can NOT take are the session-specific connection parameters and live playwright objects:
-`cdp_url`, `wss_url`, `browser_pid`, `page`, `browser`, `browser_context`, `playwright`, etc.
+The only parameters `BrowserProfile` can NOT take are the session-specific connection parameters:
+`cdp_url`, `wss_url`, `browser_pid`, etc.
+
+<Note>
+Playwright Page/Browser/Context objects are no longer supported as parameters.
+</Note>
### Basic Example
@@ -932,14 +936,16 @@ browser_session = BrowserSession(
# you can drive a session without the agent / reuse it between agents
await browser_session.start()
-page = await browser_session.get_current_page()
-await page.goto('https://example.com/first/page')
+
+# Navigate using events
+from browser_use.browser.events import NavigateToUrlEvent
+navigate_event = browser_session.event_bus.dispatch(NavigateToUrlEvent(url='https://example.com/first/page'))
+await navigate_event
async def run_search():
agent = Agent(
task='Your task',
llm=llm,
- page=page, # optional: pass a specific playwright page to start on
browser_session=browser_session, # optional: pass an existing browser session to an agent
)
```
diff --git a/docs/customize/custom-functions.mdx b/docs/customize/custom-functions.mdx
index 33abbb483..fa030a6fe 100644
--- a/docs/customize/custom-functions.mdx
+++ b/docs/customize/custom-functions.mdx
@@ -59,10 +59,18 @@ When the LLM calls an action, it sees its argument names & types, and will provi
```python
@controller.action('Click element')
-def click_element(css_selector: str, page: Page) -> ActionResult:
+async def click_element(css_selector: str, browser_session: BrowserSession) -> ActionResult:
# css_selector is an action param the LLM must provide when calling
- # page is a special framework-provided param to access the browser APIs (see below)
- await page.locator(css_selector).click()
+ # browser_session is a special framework-provided param to access the browser APIs (see below)
+
+ # Get the current CDP session to interact with the browser
+ cdp_session = await browser_session.get_or_create_cdp_session()
+
+ # Use CDP to evaluate JavaScript and click the element
+ await cdp_session.cdp_client.send.Runtime.evaluate(
+ params={'expression': f'document.querySelector("{css_selector}").click()'},
+ session_id=cdp_session.session_id,
+ )
return ActionResult(extracted_content=f"Clicked element {css_selector}")
```
@@ -89,12 +97,27 @@ class MyParams(BaseModel):
field4: str = Field(default='abc', description='Detailed description for the LLM')
@controller.action('My action', param_model=MyParams)
-def my_action(params: MyParams, page: Page) -> ActionResult:
- await page.keyboard.type(params.field2)
- return ActionResult(extracted_content=f"Inputted {params} on {page.url}")
+async def my_action(params: MyParams, browser_session: BrowserSession) -> ActionResult:
+ # Get the current CDP session to interact with the browser
+ cdp_session = await browser_session.get_or_create_cdp_session()
+
+ # Use CDP to type text
+ await cdp_session.cdp_client.send.Input.insertText(
+ params={'text': params.field2},
+ session_id=cdp_session.session_id,
+ )
+
+ # Get current URL using CDP
+ result = await cdp_session.cdp_client.send.Runtime.evaluate(
+ params={'expression': 'window.location.href', 'returnByValue': True},
+ session_id=cdp_session.session_id,
+ )
+ current_url = result.get('result', {}).get('value', 'unknown')
+
+ return ActionResult(extracted_content=f"Inputted {params} on {current_url}")
```
-Any special framework-provided arguments (e.g. `page`) will be passed as separate positional arguments after `params`.
+Any special framework-provided arguments (e.g. `browser_session`) will be passed as separate positional arguments after `params`.
<Important>
To use a `BaseModel` the arg *must* be called `params`. Action function args are matched and filled like named arguments; arg order doesn't matter but names and types do.
@@ -104,47 +127,134 @@ To use a `BaseModel` the arg *must* be called `params`. Action function args are
These special action parameters are injected by the `Controller` and are passed as extra args to any actions that expect them.
-For example, actions that need to run playwright code to interact with the browser should take the argument `page` or `browser_session`.
+For example, actions that need to interact with the browser should take the `browser_session` argument.
-- `page: Page` - The current Playwright page (shortcut for `browser_session.get_current_page()`)
-- `browser_session: BrowserSession` - The current browser session (and playwright context via `browser_session.browser_context`)
+- `browser_session: BrowserSession` - 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
- `has_sensitive_data: bool` - Whether the action content contains sensitive data markers (check this to avoid logging sensitive data to terminal by accident)
-#### Example: Action uses the current `page`
+<Note>
+Browser Use has moved from Playwright to Chrome DevTools Protocol (CDP) for browser interaction. The `browser_session` provides access to CDP through `browser_session.agent_focus.cdp_client` or `await browser_session.get_or_create_cdp_session()`. Playwright is only used internally to install the browser binary, but all browser interaction is done via CDP.
+</Note>
+
+### Understanding the Browser Session Context
+The `BrowserSession` object provides multiple ways to interact with the browser:
+
+#### 1. Direct CDP Access
```python
-from browser_use.browser.types import Page
-from browser_use import Controller, ActionResult
+# Get the current CDP session
+cdp_session = await browser_session.get_or_create_cdp_session()
+
+# Execute JavaScript
+result = await cdp_session.cdp_client.send.Runtime.evaluate(
+ params={'expression': 'document.title', 'returnByValue': True},
+ session_id=cdp_session.session_id,
+)
+
+# Click at coordinates
+await cdp_session.cdp_client.send.Input.dispatchMouseEvent(
+ params={
+ 'type': 'mousePressed',
+ 'x': 100,
+ 'y': 200,
+ 'button': 'left',
+ 'clickCount': 1,
+ },
+ session_id=cdp_session.session_id,
+)
+await cdp_session.cdp_client.send.Input.dispatchMouseEvent(
+ params={
+ 'type': 'mouseReleased',
+ 'x': 100,
+ 'y': 200,
+ 'button': 'left',
+ },
+ session_id=cdp_session.session_id,
+)
+```
+
+#### 2. Event-Based Actions
+```python
+from browser_use.browser.events import ClickElementEvent, TypeTextEvent, NavigateToUrlEvent
+
+# Get a DOM element first
+element = await browser_session.get_dom_element_by_index(5)
+
+# Dispatch events through the event bus
+click_event = browser_session.event_bus.dispatch(ClickElementEvent(node=element))
+await click_event
+
+type_event = browser_session.event_bus.dispatch(TypeTextEvent(node=element, text="Hello"))
+await type_event
+
+navigate_event = browser_session.event_bus.dispatch(NavigateToUrlEvent(url="https://example.com"))
+await navigate_event
+```
+
+#### 3. High-Level Browser Session Methods
+```python
+# Get current page information
+state = await browser_session.get_browser_state_summary()
+print(f"Current URL: {state.url}")
+print(f"Page title: {state.title}")
+
+# Take a screenshot
+screenshot_path = await browser_session.take_screenshot()
+
+# Get page HTML
+html = await browser_session.get_page_html()
+
+# Get all open tabs
+tabs = await browser_session.get_tabs()
+```
+
+#### Example: Action uses the current browser session
+
+```python
+from browser_use import BrowserSession, Controller, ActionResult
controller = Controller()
@controller.action('Type keyboard input into a page')
-async def input_text_into_page(text: str, page: Page) -> ActionResult:
- await page.keyboard.type(text)
- return ActionResult(extracted_content='Website opened')
+async def input_text_into_page(text: str, browser_session: BrowserSession) -> ActionResult:
+ # Get the current CDP session to interact with the browser
+ cdp_session = await browser_session.get_or_create_cdp_session()
+
+ # Use CDP to type text
+ await cdp_session.cdp_client.send.Input.insertText(
+ params={'text': text},
+ session_id=cdp_session.session_id,
+ )
+ return ActionResult(extracted_content='Text input completed')
```
-#### Example: Action uses the `browser_context`
+#### Example: Action uses browser session for tab management
```python
from browser_use import BrowserSession, 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:
- # find matching existing tab by looking through all pages in playwright browser_context
- all_tabs = await browser_session.browser_context.pages
- for tab in all_tabs:
+ # Get all open tabs
+ tabs = await browser_session.get_tabs()
+
+ # Check if URL is already open in any tab
+ for tab in tabs:
if tab.url == url:
- await tab.bring_to_foreground()
- return ActionResult(extracted_content=f'Switched to tab with url {url}')
- # otherwise, create a new tab
- new_tab = await browser_session.browser_context.new_page()
- await new_tab.goto(url)
+ # Switch to existing tab using events
+ switch_event = browser_session.event_bus.dispatch(SwitchTabEvent(target_id=tab.target_id))
+ await switch_event
+ return ActionResult(extracted_content=f'Switched to existing tab with url {url}')
+
+ # Otherwise, open URL in a new tab using events
+ navigate_event = browser_session.event_bus.dispatch(NavigateToUrlEvent(url=url, new_tab=True))
+ await navigate_event
return ActionResult(extracted_content=f'Opened new tab with url {url}')
```
@@ -155,15 +265,15 @@ async def open_website(url: str, browser_session: BrowserSession) -> ActionResul
## Important Rules
1. **Return an [`ActionResult`](https://github.com/search?q=repo%3Abrowser-use%2Fbrowser-use+%22class+ActionResult%28BaseModel%29%22&type=code)**: All actions should return an `ActionResult | str | None`. The stringified version of the result is passed back to the LLM, and optionally persisted in the long-term memory when `ActionResult(..., include_in_memory=True)`.
-2. **Type hints on arguments are required**: They are used to verify that action params don't conflict with special arguments injected by the controller (e.g. `page`)
+2. **Type hints on arguments are required**: They are used to verify that action params don't conflict with special arguments injected by the controller (e.g. `browser_session`)
3. **Actions functions called directly must be passed kwargs**: When calling actions from other actions or python code, you must **pass all parameters as kwargs only**, even though the actions are usually defined using positional args (for the same reasons as [pluggy](https://pluggy.readthedocs.io/en/stable/index.html#calling-hooks)).
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')
- def input_country_field(country: str, page: Page) -> ActionResult:
- await some_action(123, page=page) # ❌ not allowed: positional args, use kwarg syntax when calling
- await some_action(abc=123, page=page) # ✅ allowed: action params & special kwargs
- await some_other_action(params=OtherAction(abc=123), page=page) # ✅ allowed: params=model & special kwargs
+ async def input_country_field(country: str, browser_session: BrowserSession) -> 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
```
```python
@@ -173,12 +283,12 @@ class PinCodeParams(BaseModel):
retries: int = 3 # ✅ supports optional/defaults
@controller.action('...', param_model=PinCodeParams)
-async def input_pin_code(params: PinCodeParams, page: Page): ... # ✅ special params at the end
+async def input_pin_code(params: PinCodeParams, browser_session: BrowserSession): ... # ✅ special params at the end
# Using function arguments to define action params
-async def input_pin_code(code: int, retries: int, page: Page): ... # ✅ params first, special params second, no defaults
+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=3): ... # ✅ defaults ok only if no special params needed
-async def input_pin_code(code: int, retries: int=3, page: Page): ... # ❌ Python SyntaxError! not allowed
+async def input_pin_code(code: int, retries: int=3, browser_session: BrowserSession): ... # ❌ Python SyntaxError! not allowed
```
@@ -228,23 +338,8 @@ agent = Agent(controller=controller, ...)
```
-If you want actions to only be available on certain pages, and to not tell the LLM about them on other pages,
- you can use the `allowed_domains` and `page_filter`:
-
-```python
-from pydantic import BaseModel
-from browser_use import Controller, ActionResult
-
-controller = Controller()
-
-async def is_ai_allowed(page: Page):
- if api.some_service.check_url(page.url):
- logger.warning('Allowing AI agent to visit url:', page.url)
- return True
- return False
[email protected]('Fill out secret_form', allowed_domains=['https://*.example.com'], page_filter=is_ai_allowed)
[email protected]('Fill out secret_form', allowed_domains=['https://*.example.com'])
def fill_out_form(...) -> ActionResult:
- ... will only be runnable by LLM on pages that match https://*.example.com *AND* where is_ai_allowed(page) returns True
-
+ ... will only be runnable by LLM on pages that match https://*.example.com
```
diff --git a/docs/customize/hooks.mdx b/docs/customize/hooks.mdx
index b3091a050..53f839141 100644
--- a/docs/customize/hooks.mdx
+++ b/docs/customize/hooks.mdx
@@ -35,11 +35,10 @@ async def my_step_hook(agent: Agent):
# agent.controller, agent.llm, agent.browser_session
# agent.pause(), agent.resume(), agent.add_new_task(...), etc.
- # You also have direct access to the playwright Page and Browser Context
- page = await agent.browser_session.get_current_page()
- # https://playwright.dev/python/docs/api/class-page
-
- current_url = page.url
+ # You also have direct access to the browser state
+ state = await agent.browser_session.get_browser_state_summary()
+
+ current_url = state.url
visit_log = agent.history.urls()
previous_url = visit_log[-2] if len(visit_log) >= 2 else None
print(f"Agent was last on URL: {previous_url} and is now on {current_url}")
@@ -96,10 +95,10 @@ 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 playwright objects
- - `agent.browser_session.get_current_page()`: Get the current playwright `Page` object the agent is focused on
- - `agent.browser_session.browser_context`: Get the current playwright `BrowserContext` object
- - `agent.browser_session.browser_context.pages`: Get all the tabs currently open in the context
+- `agent.browser_session` gives direct access to the `BrowserSession()` 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
- `agent.browser_session.get_page_html()`: Current page HTML
- `agent.browser_session.take_screenshot()`: Screenshot of the current page
diff --git a/docs/customize/real-browser.mdx b/docs/customize/real-browser.mdx
index 2f6c38455..6440da912 100644
--- a/docs/customize/real-browser.mdx
+++ b/docs/customize/real-browser.mdx
@@ -10,7 +10,6 @@ Browser Use supports a wide variety of ways to launch or connect to a browser:
- Launch a new local browser using playwright/patchright chromium (the default)
- Connect to a remote browser using CDP or WSS
-- Use an existing playwright `Page`, `Browser`, or `BrowserContext` object
- Connect to a local browser already running using `browser_pid`
<Tip>
@@ -24,7 +23,7 @@ We provide automatic CAPTCHA solving, proxies, human-in-the-loop automation, and
### Method A: Launch a New Local Browser (Default)
-Launch a local browser using built-in default (playwright `chromium`) or a provided `executable_path`:
+Launch a local browser using built-in default (Playwright-installed `chromium`) or a provided `executable_path`:
```python
from browser_use import Agent, BrowserSession
@@ -63,41 +62,42 @@ We support most `chromium`-based browsers in `executable_path`, including [Brave
persist over time.
</Warning>
-### Method B: Connect Using Existing Playwright Objects
+### Method B: Connect to Remote Browser via CDP
-Pass existing Playwright `Page`, `BrowserContext`, `Browser`, and/or `playwright` API object to `BrowserSession(...)`:
+Connect to a remote browser instance using Chrome DevTools Protocol:
```python
from browser_use import Agent, BrowserSession
-from playwright.async_api import async_playwright
-# from patchright.async_api import async_playwright # stealth alternative
-
-async with async_playwright() as playwright:
- browser = await playwright.chromium.launch()
- context = await browser.new_context()
- page = await context.new_page()
-
- browser_session = BrowserSession(
- page=page,
- # browser_context=context, # all these are supported
- # browser=browser,
- # playwright=playwright,
- )
-
- agent = Agent(
- task="Your task here",
- llm=llm,
- browser_session=browser_session,
- )
+
+# Connect to a remote browser (e.g., running in Docker, cloud, or another machine)
+browser_session = BrowserSession(
+ cdp_url="ws://remote-browser:9222/devtools/browser", # Remote CDP WebSocket URL
+ is_local=False, # Important: set to False for remote connections
+)
+
+agent = Agent(
+ task="Your task here",
+ llm=llm,
+ browser_session=browser_session,
+)
```
-You can also pass `page` directly to `Agent(...)` as a shortcut.
+<Note>
+Playwright Page/Browser/Context objects are no longer supported. Browser Use now uses CDP exclusively for all browser interactions.
+</Note>
+
+You can also use HTTP-based CDP connections:
```python
+browser_session = BrowserSession(
+ cdp_url="http://remote-browser:9222", # Remote CDP HTTP URL
+ is_local=False,
+)
+
agent = Agent(
task="Your task here",
llm=llm,
- page=page,
+ browser_session=browser_session,
)
```
@@ -282,26 +282,40 @@ await reused_session.close()
### Parallel Agents, Same Browser, Multiple Tabs
```python
+import asyncio
from browser_use import Agent, BrowserSession
from browser_use.llm import ChatOpenAI
-from playwright.async_api import async_playwright
-
-async with async_playwright() as playwright:
- browser_context = await playwright.chromium.launch_persistent_context()
- page1 = await browser_context.new_page()
- page2 = await browser_context.new_page()
-
- agent1 = Agent(
- task="The first task...",
- llm=ChatOpenAI(model="gpt-4o-mini"),
- page=page1,
- )
- agent2 = Agent(
- task="The second task...",
- llm=ChatOpenAI(model="gpt-4o-mini"),
- page=page2,
- )
- await asyncio.gather(agent1.run(), agent2.run()) # run in parallel
+from browser_use.browser.events import NavigateToUrlEvent
+
+# Create a shared browser session
+browser_session = BrowserSession()
+await browser_session.start()
+
+# Create tabs for each agent using events
+tab1_event = browser_session.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))
+await tab2_event
+
+# Get tab information
+tabs = await browser_session.get_tabs()
+
+# Create agents that will work with different tabs
+agent1 = Agent(
+ task="The first task...",
+ llm=ChatOpenAI(model="gpt-4o-mini"),
+ browser_session=browser_session,
+)
+
+agent2 = Agent(
+ task="The second task...",
+ llm=ChatOpenAI(model="gpt-4o-mini"),
+ browser_session=browser_session,
+)
+
+# Run agents in parallel (they will automatically coordinate tab switching)
+await asyncio.gather(agent1.run(), agent2.run())
```
### Parallel Agents, Same Browser, Same Tab
@@ -313,19 +327,19 @@ async with async_playwright() as playwright:
</Warning>
```python
+import asyncio
from browser_use import Agent, BrowserSession
from browser_use.llm import ChatOpenAI
-from playwright.async_api import async_playwright
-
-playwright = await async_playwright().start()
-browser = await playwright.chromium.launch(headless=True)
-context = await browser.new_context()
-shared_page = await context.new_page()
-await shared_page.goto('https://example.com', wait_until='load')
+from browser_use.browser.events import NavigateToUrlEvent
-shared_session = BrowserSession(page=shared_page, keep_alive=True)
+# Create a shared browser session
+shared_session = BrowserSession()
await shared_session.start()
+# Navigate to the target page
+navigate_event = shared_session.event_bus.dispatch(NavigateToUrlEvent(url='https://example.com'))
+await navigate_event
+
agent1 = Agent(
task="Fill out the form in section A...",
llm=ChatOpenAI(model="gpt-4o-mini"),
@@ -336,9 +350,11 @@ agent2 = Agent(
llm=ChatOpenAI(model="gpt-4o-mini"),
browser_session=shared_session,
)
-await asyncio.gather(agent1.run(), agent2.run()) # run in parallel
-await shared_session.kill()
+# Run agents in parallel on the same tab (not recommended)
+await asyncio.gather(agent1.run(), agent2.run())
+
+await shared_session.stop()
```
### Parallel Agents, Same Profile, Different Browsers