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
Remove page from docs
Magnus Müllerc6210dff6541
diff --git a/docs/customize/agent-settings.mdx b/docs/customize/agent-settings.mdxindex 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# orchannel=... # 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.mdxindex 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 agentsawait 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_eventasync def run_search():agent = Agent(task='Your task',llm=llm,- page=page, # optional: pass a specific playwright page to start onbrowser_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.mdxindex 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 areThese 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, ActionResultcontroller = 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```pythonfrom browser_use import BrowserSession, Controller, ActionResult+from browser_use.browser.events import NavigateToUrlEvent, SwitchTabEventcontroller = 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_eventreturn 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 Rules1. **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 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, 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.mdxindex 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.urlvisit_log = agent.history.urls()previous_url = visit_log[-2] if len(visit_log) >= 2 else Noneprint(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 pagediff --git a/docs/customize/real-browser.mdx b/docs/customize/real-browser.mdxindex 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`:```pythonfrom browser_use import Agent, BrowserSession@@ -63,41 +62,42 @@ We support most `chromium`-based browsers in `executable_path`, including [Bravepersist 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:```pythonfrom 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 asynciofrom browser_use import Agent, BrowserSessionfrom 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 asynciofrom browser_use import Agent, BrowserSessionfrom 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