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
reorder docs files
Magnus Müller2a27d8c1bfc7
diff --git a/docs/customize/agent-parameters.mdx b/docs/customize/agent/all-parameters.mdxsimilarity index 100%rename from docs/customize/agent-parameters.mdxrename to docs/customize/agent/all-parameters.mdxdiff --git a/docs/customize/agent-basic.mdx b/docs/customize/agent/basics.mdxsimilarity index 100%rename from docs/customize/agent-basic.mdxrename to docs/customize/agent/basics.mdxdiff --git a/docs/customize/agent-output-format.mdx b/docs/customize/agent/output-format.mdxsimilarity index 100%rename from docs/customize/agent-output-format.mdxrename to docs/customize/agent/output-format.mdxdiff --git a/docs/customize/supported-models.mdx b/docs/customize/agent/supported-models.mdxsimilarity index 100%rename from docs/customize/supported-models.mdxrename to docs/customize/agent/supported-models.mdxdiff --git a/docs/customize/browser-parameters.mdx b/docs/customize/browser/all-parameters.mdxsimilarity index 100%rename from docs/customize/browser-parameters.mdxrename to docs/customize/browser/all-parameters.mdxdiff --git a/docs/customize/browser-basic.mdx b/docs/customize/browser/basics.mdxsimilarity index 100%rename from docs/customize/browser-basic.mdxrename to docs/customize/browser/basics.mdxdiff --git a/docs/customize/browser-real-browser.mdx b/docs/customize/browser/real-browser.mdxsimilarity index 100%rename from docs/customize/browser-real-browser.mdxrename to docs/customize/browser/real-browser.mdxdiff --git a/docs/customize/browser-remote.mdx b/docs/customize/browser/remote.mdxsimilarity index 100%rename from docs/customize/browser-remote.mdxrename to docs/customize/browser/remote.mdxdiff --git a/docs/customize/custom-functions.mdx b/docs/customize/custom-functions.mdxdeleted file mode 100644index 850da3bfa..000000000--- a/docs/customize/custom-functions.mdx+++ /dev/null@@ -1,346 +0,0 @@-----title: "Tools"-description: "Extend default agent and write custom action functions to do certain tasks"-icon: "wrench"-mode: "wide"------Custom actions are functions *you* provide, that are added to our [default actions](https://github.com/browser-use/browser-use/blob/main/browser_use/controller/service.py) the agent can use to accomplish tasks.-Action functions can request [arbitrary parameters](#action-parameters-via-pydantic-model) that the LLM has to come up with + a fixed set of [framework-provided arguments](#framework-provided-parameters) for browser APIs / `Agent(context=...)` / etc.--<Note>- Our default set of actions is already quite powerful, the built-in `Controller` provides basics like `go_to_url`, `scroll_down`, `extract_content`, [and more](https://github.com/browser-use/browser-use/blob/main/browser_use/controller/service.py).-</Note>--It's easy to add your own actions to implement additional custom behaviors, integrations with other apps, or performance optimizations.--For examples of custom actions (e.g. uploading files, asking a human-in-the-loop for help, drawing a polygon with the mouse, and more), see [examples/custom-functions](https://github.com/browser-use/browser-use/tree/main/examples/custom-functions).---## Action Function Registration--To register your own custom functions (which can be `sync` or `async`), decorate them with the `@controller.action(...)` decorator. This saves them into the `controller.registry`.--```python-from browser_use import Controller, ActionResult--controller = Controller()-[email protected]('Ask human for help with a question', domains=['example.com']) # pass allowed_domains= or page_filter= to limit actions to certain pages-def ask_human(question: str) -> ActionResult:- answer = input(f'{question} > ')- return ActionResult(extracted_content=f'The human responded with: {answer}', include_in_memory=True)-```--```python-# Then pass your controller to the agent to use it-agent = Agent(- task='...',- llm=llm,- controller=controller,-)-```--<Note>- Keep your action function names and descriptions short and concise:- - The LLM chooses between actions to run solely based on the function name and description- - The LLM decides how to fill action params based on their names, type hints, & defaults-</Note>-------## Action Parameters--Browser Use supports two patterns for defining action parameters: normal function arguments, or a Pydantic model.--### Function Arguments--For simple actions that don't need default values, you can define the action parameters directly as arguments to the function. This one takes a single string argument, `css_selector`.-When the LLM calls an action, it sees its argument names & types, and will provide values that fit.--```python[email protected]('Click element')-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)-- # 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}")-```--### Pydantic Model--You can define a pydantic model for the parameters your action expects by setting a `@controller.action(..., param_model=MyParams)`.-This allows you to use optional parameters, default values, `Annotated[...]` types with custom validation, field descriptions, and other features offered by pydantic.--When the agent calls calls your agent function, an instance of your model with the values filled by the LLM will be passed as the argument named `params` to your action function.--Using a pydantic model is helpful because it allows more flexibility and power to enforce the schema of the values the LLM should provide.-The LLM gets the entire pydantic JSON schema for your `param_model`, it will see the function name & description + individual field names, types, descriptions, and default values.---```python-from typing import Annotated-from pydantic import BaseModel, AfterValidator-from browser_use import ActionResult--class MyParams(BaseModel):- field1: int- field2: str = 'default value'- field3: Annotated[str, AfterValidator(lambda s: s.lower())] # example: enforce always lowercase- field4: str = Field(default='abc', description='Detailed description for the LLM')-[email protected]('My action', param_model=MyParams)-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()-- # 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. `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.-</Important>--### Framework-Provided Parameters--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 interact with the browser should take the `browser_session` argument.--- `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-- `has_sensitive_data: bool` - Whether the action content contains sensitive data markers (check this to avoid logging sensitive data to terminal by accident)--<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 `Browser` object provides multiple ways to interact with the browser:--#### 1. Direct CDP Access-```python-# 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 Browser, Controller, ActionResult--controller = Controller()-[email protected]('Type keyboard input into a page')-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()-- # 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 browser session for tab management--```python-from browser_use import Browser, Controller, ActionResult-from browser_use.browser.events import NavigateToUrlEvent, SwitchTabEvent--controller = Controller()-[email protected]('Open website')-async def open_website(url: str, browser_session: Browser) -> ActionResult:- # 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:- # 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}')-```---------## 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. `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')- 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- ```--```python-# Using Pydantic Model to define action params (recommended)-class PinCodeParams(BaseModel):- code: int- retries: int = 3 # ✅ supports optional/defaults-[email protected]('...', param_model=PinCodeParams)-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: 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: Browser): ... # ❌ Python SyntaxError! not allowed-```---------## Reusing Custom Actions Across Agents--You can use the same controller for multiple agents.--```python-controller = Controller()--# ... register actions to the controller--agent = Agent(- task="Go to website X and find the latest news",- llm=llm,- controller=controller-)--# Run the agent-await agent.run()--agent2 = Agent(- task="Go to website Y and find the latest news",- llm=llm,- controller=controller-)--await agent2.run()-```--<Note>- The controller is stateless and can be used to register multiple actions and- multiple agents.-</Note>----## Exclude functions--If you want to exclude some registered actions and make them unavailable to the agent, you can do:-```python-controller = Controller(exclude_actions=['search_google'])-agent = Agent(controller=controller, ...)-```---[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-```diff --git a/docs/customize/chain-agents.mdx b/docs/customize/examples/chain-agents.mdxsimilarity index 100%rename from docs/customize/chain-agents.mdxrename to docs/customize/examples/chain-agents.mdxdiff --git a/docs/customize/fast-agent.mdx b/docs/customize/examples/fast-agent.mdxsimilarity index 100%rename from docs/customize/fast-agent.mdxrename to docs/customize/examples/fast-agent.mdxdiff --git a/docs/customize/more-examples.mdx b/docs/customize/examples/more-examples.mdxsimilarity index 100%rename from docs/customize/more-examples.mdxrename to docs/customize/examples/more-examples.mdxdiff --git a/docs/customize/parallel-browser.mdx b/docs/customize/examples/parallel-browser.mdxsimilarity index 100%rename from docs/customize/parallel-browser.mdxrename to docs/customize/examples/parallel-browser.mdxdiff --git a/docs/customize/secure.mdx b/docs/customize/examples/secure.mdxsimilarity index 100%rename from docs/customize/secure.mdxrename to docs/customize/examples/secure.mdxdiff --git a/docs/customize/sensitive-data.mdx b/docs/customize/examples/sensitive-data.mdxsimilarity index 100%rename from docs/customize/sensitive-data.mdxrename to docs/customize/examples/sensitive-data.mdxdiff --git a/docs/customize/real-browser.mdx b/docs/customize/real-browser.mdxdeleted file mode 100644index 7573eb186..000000000--- a/docs/customize/real-browser.mdx+++ /dev/null@@ -1,439 +0,0 @@-----title: "Connect to your Browser"-description: "Connect to a remote browser or launch a new local browser."-icon: "computer"-mode: "wide"------## Overview--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-- Connect to a local browser already running using `browser_pid`--<Tip>-Don't want to manage your own browser infrastructure? Try [☁️ Browser Use Cloud](https://browser-use.com) ➡️--We provide automatic CAPTCHA solving, proxies, human-in-the-loop automation, and more!--</Tip>--## Connection Methods--### Method A: Launch a New Local Browser (Default)--Launch a local browser using built-in default (Playwright-installed `chromium`) or a provided `executable_path`:--```python-from browser_use import Agent, Browser--# If no executable_path provided, uses Playwright/Patchright's built-in Chromium-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'- # For Linux: '/usr/bin/google-chrome'-- # Use a specific data directory on disk (optional, set to None for incognito)- user_data_dir='~/.config/browseruse/profiles/default', # this is the default- # ... any other BrowserProfile or playwright launch_persistnet_context config...- # headless=False,-)--agent = Agent(- task="Your task here",- llm=llm,- browser=browser,-)-```--We support most `chromium`-based browsers in `executable_path`, including [Brave](https://github.com/browser-use/browser-use/tree/main/examples/browser/stealth.py), [patchright chromium](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright), [rebrowser](https://rebrowser.net/), Edge, and more. See [`examples/browser/stealth.py`](https://github.com/browser-use/browser-use/tree/main/examples/browser) for more. We do not support Firefox or Safari at the moment.--<Warning>- [As of Chrome v136](https://github.com/browser-use/browser-use/issues/1520),- driving browsers with the default profile is [no longer- supported](https://developer.chrome.com/blog/remote-debugging-port) for- security reasons. Browser-Use has transitioned to creating a new dedicated- profile for agents in: `~/.config/browseruse/profiles/default`. You can [open- this- profile](https://superuser.com/questions/377186/how-do-i-start-chrome-using-a-specified-user-profile)- and log into everything you need your agent to have access to, and it will- persist over time.-</Warning>--### Method B: Connect to Remote Browser via CDP--Connect to a remote browser instance using Chrome DevTools Protocol:--```python-from browser_use import Agent, Browser--# Connect to a remote browser (e.g., running in Docker, cloud, or another machine)-browser = Browser(- 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=browser,-)-```--<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 = Browser(- cdp_url="http://remote-browser:9222", # Remote CDP HTTP URL- is_local=False,-)--agent = Agent(- task="Your task here",- llm=llm,- browser=browser,-)-```--### Method C: Connect to Local Browser Using Browser PID--Connect to a browser with open `--remote-debugging-port`:--```python-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 = Browser(browser_pid=12345) # Replace with actual Chrome PID--agent = Agent(- task="Your task here",- llm=llm,- browser=browser,-)-```--### Method D: Connect to remote Playwright Node.js Browser Server via WSS URL--Connect to Playwright Node.js server providers:--```python-from browser_use import Agent, Browser--# Connect to a playwright server-browser = Browser(wss_url="wss://your-playwright-server.com/ws")--agent = Agent(- task="Your task here",- llm=llm,- browser=browser,-)-```--### Method E: Connect to Remote Browser via CDP URL--Connect to any remote Chromium-based browser:--```python-from browser_use import Agent, Browser--# Connect to Chrome via CDP-browser = Browser(cdp_url="http://localhost:9222")--agent = Agent(- task="Your task here",- llm=llm,- browser=browser,-)-```--## Security Considerations--<Warning>- When using any browser profile, the agent will have access to:- - All its logged-in sessions and cookies- - Saved passwords (if autofill is enabled)- - Browser history and bookmarks- - 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 `Browser(allowed_domains=['https://*.example.com'])`.-</Warning>--## Best Practices--1. **Use isolated profiles**: Create separate Chrome profiles for different agents to limit scope of risk:-- ```python- browser = Browser(- user_data_dir='~/.config/browseruse/profiles/banking',- # profile_directory='Default'- )- ```--2. **Limit domain access**: Restrict which sites the agent can visit:-- ```python- browser = Browser(- allowed_domains=['example.com', 'http*://*.github.com'],- )- ```--3. **Enable `keep_alive=True`** If you want to use a single `Browser` with more than one agent:- ```python- browser = Browser(- keep_alive=True,- ...- )- await browser.start() # start the session yourself before passing to Agent- ...- agent = Agent(..., browser=browser)- await agent.run()- ...- await browser.kill() # end the session yourself, shortcut for keep_alive=False + .stop()- ```--## Re-Using a Browser--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 `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 `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>--### Sequential Agents, Same Profile, Different Browser--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, Browser-from browser_use.llm import ChatOpenAI--reused_profile = BrowserProfile(user_data_dir='~/.config/browseruse/profiles/default')--agent1 = Agent(- task="The first task...",- llm=ChatOpenAI(model="gpt-4.1-mini"),- browser_profile=reused_profile, # pass the profile in, it will auto-create a session-)-await agent1.run()--agent2 = Agent(- task="The second task...",- llm=ChatOpenAI(model="gpt-4.1-mini"),- browser_profile=reused_profile, # agent will auto-create its own new session-)-await agent2.run()-```--> Make sure to never mix different browser versions or `executable_path`s with the same `user_data_dir`. Once run with a newer browser version, some migrations are applied to the dir and older browsers wont be able to read it.--### Sequential Agents, Same Profile, Same Browser--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, Browser-from browser_use.llm import ChatOpenAI--reused_session = Browser(- user_data_dir='~/.config/browseruse/profiles/default',- keep_alive=True, # dont close browser after 1st agent.run() ends-)-await reused_session.start() # when keep_alive=True, session must be started manually--agent1 = Agent(- task="The first task...",- llm=ChatOpenAI(model="gpt-4.1-mini"),- browser=reused_session,-)-await agent1.run()--agent2 = Agent(- task="The second task...",- llm=ChatOpenAI(model="gpt-4.1-mini"),- browser=reused_session, # re-use the same session-)-await agent2.run()--await reused_session.close()-```--### Parallel Agents, Same Browser, Multiple Tabs--```python-import asyncio-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 = Browser()-await browser.start()--# Create tabs for each agent using events-tab1_event = browser.event_bus.dispatch(NavigateToUrlEvent(url="about:blank", new_tab=True))-await tab1_event--tab2_event = browser.event_bus.dispatch(NavigateToUrlEvent(url="about:blank", new_tab=True))-await tab2_event--# Get tab information-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"),- browser=browser,-)--agent2 = Agent(- task="The second task...",- llm=ChatOpenAI(model="gpt-4.1-mini"),- browser=browser,-)--# Run agents in parallel (they will automatically coordinate tab switching)-await asyncio.gather(agent1.run(), agent2.run())-```--### Parallel Agents, Same Browser, Same Tab--<Warning>- ⚠️ This mode is not recommended. Agents are not yet optimized to share the- same tab in the same browser, they may interfere with each other or cause- errors.-</Warning>--```python-import asyncio-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 = Browser()-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-4.1-mini"),- browser=shared_session-)-agent2 = Agent(- task="Fill out the form in section B...",- llm=ChatOpenAI(model="gpt-4.1-mini"),- browser=shared_session,-)--# 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--<Tip>This mode is the recommended default.</Tip>--To share a single set of configuration or cookies, but still have agents working in their own browser sessions (potentially in parallel), use our provided `BrowserProfile` object.--The recommended way to re-use cookies and localStorage state between separate parallel sessions is to use the [`storage_state`](https://docs.browser-use.com/customize/browser-settings#storage-state) option.--```bash-# open a browser to log into sites you want the Agent to have access to-playwright open https://example.com/ --save-storage=/tmp/auth.json-playwright open https://example.com/ --load-storage=/tmp/auth.json-```--```python-from browser_use.browser import BrowserProfile, Browser--shared_profile = BrowserProfile(- headless=True,- user_data_dir=None, # use dedicated tmp user_data_dir per session- storage_state='/tmp/auth.json', # load/save cookies to/from json file- keep_alive=True, # don't close the browser after the agent finishes-)--window1 = Browser(browser_profile=shared_profile)-await window1.start()-agent1 = Agent(browser=window1)--window2 = Browser(browser_profile=shared_profile)-await window2.start()-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-await window2.save_storage_state() # you must decide when to save manually--# can also reload the cookies from the file into the active session if they change-await window1.load_storage_state()-await window1.close()-await window2.close()-```-------## Troubleshooting--### Chrome Won't Connect--If you're having trouble connecting:--1. **Close all Chrome instances** before trying to launch with a custom profile-2. **Check if Chrome is running with debugging port**:- ```bash- ps aux | grep chrome | grep remote-debugging-port- ```-3. **Verify the executable path** is correct for your system-4. **Check profile permissions** - ensure your user has read/write access--### Profile Lock Issues--If you get a "profile is already in use" error:--1. Close all Chrome instances-2. The profile will automatically be unlocked when Browser starts-3. Alternatively, manually delete the `SingletonLock` file in the profile directory--<Note>- For more configuration options, see the [Browser- Settings](/customize/browser-settings) documentation.-</Note>--### Profile Version Issues--The browser version you run must always be equal to or greater than the version used to create the `user_data_dir`.-If you see errors like `Failed to parse Extensions` when launching, you're likely attempting to run an older browser with an incompatible `user_data_dir` that's already been migrated to a newer Chrome version.--Playwright ships a version of chromium that's newer than the default stable Google Chrome release channel, so this can happen if you try to use-a profile created by the default playwright chromium (e.g. `user_data_dir='~/.config/browseruse/profiles/default'`) with an older-local browser like `executable_path='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'`.diff --git a/docs/customize/system-prompt.mdx b/docs/customize/system-prompt.mdxdeleted file mode 100644index 4d6329db8..000000000--- a/docs/customize/system-prompt.mdx+++ /dev/null@@ -1,78 +0,0 @@-----title: "System Prompt"-description: "Customize the system prompt to control agent behavior and capabilities"-icon: "message"-mode: "wide"------## Overview--You can customize the system prompt in two ways:--1. Extend the default system prompt with additional instructions-2. Override the default system prompt entirely--<Note>- Custom system prompts allow you to modify the agent's behavior at a- fundamental level. Use this feature carefully as it can significantly impact- the agent's performance and reliability.-</Note>--### Extend System Prompt (recommended)--To add additional instructions to the default system prompt:--```python-extend_system_message = """-REMEMBER the most important RULE:-ALWAYS open first a new tab and go first to url wikipedia.com no matter the task!!!-"""-```--### Override System Prompt--<Warning>- Not recommended! If you must override the [default system- prompt](https://github.com/browser-use/browser-use/blob/main/browser_use/agent/system_prompt.md),- make sure to test the agent yourself.-</Warning>--Anyway, to override the default system prompt:--```python-# Define your complete custom prompt-override_system_message = """-You are an AI agent that helps users with web browsing tasks.--[Your complete custom instructions here...]-"""--# Create agent with custom system prompt-agent = Agent(- task="Your task here",- llm=ChatOpenAI(model='gpt-4'),- override_system_message=override_system_message-)-```--### Extend Planner System Prompt--You can customize the behavior of the planning agent by extending its system prompt:--```python-extend_planner_system_message = """-PRIORITIZE gathering information before taking any action.-Always suggest exploring multiple options before making a decision.-"""--# Create agent with extended planner system prompt-llm = ChatOpenAI(model='gpt-4.1-mini')-planner_llm = ChatOpenAI(model='gpt-4.1-mini')--agent = Agent(- task="Your task here",- llm=llm,- planner_llm=planner_llm,- extend_planner_system_message=extend_planner_system_message-)-```diff --git a/docs/customize/tools-register.mdx b/docs/customize/tools/add.mdxsimilarity index 100%rename from docs/customize/tools-register.mdxrename to docs/customize/tools/add.mdxdiff --git a/docs/customize/tools-available.mdx b/docs/customize/tools/available.mdxsimilarity index 100%rename from docs/customize/tools-available.mdxrename to docs/customize/tools/available.mdxdiff --git a/docs/customize/tools-basic.mdx b/docs/customize/tools/basics.mdxsimilarity index 100%rename from docs/customize/tools-basic.mdxrename to docs/customize/tools/basics.mdxdiff --git a/docs/customize/tools-remove.mdx b/docs/customize/tools/remove.mdxsimilarity index 100%rename from docs/customize/tools-remove.mdxrename to docs/customize/tools/remove.mdxdiff --git a/docs/customize/tools-response.mdx b/docs/customize/tools/response.mdxsimilarity index 100%rename from docs/customize/tools-response.mdxrename to docs/customize/tools/response.mdxdiff --git a/docs/docs.json b/docs/docs.jsonindex b05cbc53f..4dab4db6a 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -43,10 +43,10 @@"icon": "robot","isDefaultOpen": true,"pages": [- "customize/agent-basic",- "customize/supported-models",- "customize/agent-output-format",- "customize/agent-parameters"+ "customize/agent/basics",+ "customize/agent/supported-models",+ "customize/agent/output-format",+ "customize/agent/all-parameters"]},{@@ -54,10 +54,10 @@"icon": "window","isDefaultOpen": false,"pages": [- "customize/browser-basic",- "customize/browser-real-browser",- "customize/browser-remote",- "customize/browser-parameters"+ "customize/browser/basics",+ "customize/browser/real-browser",+ "customize/browser/remote",+ "customize/browser/all-parameters"]},{@@ -65,23 +65,23 @@"icon": "wrench","isDefaultOpen": false,"pages": [- "customize/tools-basic",- "customize/tools-available",- "customize/tools-register",- "customize/tools-remove",- "customize/tools-response"+ "customize/tools/basics",+ "customize/tools/available",+ "customize/tools/add",+ "customize/tools/remove",+ "customize/tools/response"]},{"group": "Examples","icon": "folder-open","pages": [- "customize/fast-agent",- "customize/chain-agents",- "customize/parallel-browser",- "customize/sensitive-data",- "customize/secure",- "customize/more-examples"+ "customize/examples/fast-agent",+ "customize/examples/chain-agents",+ "customize/examples/parallel-browser",+ "customize/examples/sensitive-data",+ "customize/examples/secure",+ "customize/examples/more-examples"]}]