Skip to content

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

reorder docs files

Magnus Müller2a27d8c1bfc7
diff --git a/docs/customize/agent-parameters.mdx b/docs/customize/agent/all-parameters.mdx
similarity index 100%
rename from docs/customize/agent-parameters.mdx
rename to docs/customize/agent/all-parameters.mdx
diff --git a/docs/customize/agent-basic.mdx b/docs/customize/agent/basics.mdx
similarity index 100%
rename from docs/customize/agent-basic.mdx
rename to docs/customize/agent/basics.mdx
diff --git a/docs/customize/agent-output-format.mdx b/docs/customize/agent/output-format.mdx
similarity index 100%
rename from docs/customize/agent-output-format.mdx
rename to docs/customize/agent/output-format.mdx
diff --git a/docs/customize/supported-models.mdx b/docs/customize/agent/supported-models.mdx
similarity index 100%
rename from docs/customize/supported-models.mdx
rename to docs/customize/agent/supported-models.mdx
diff --git a/docs/customize/browser-parameters.mdx b/docs/customize/browser/all-parameters.mdx
similarity index 100%
rename from docs/customize/browser-parameters.mdx
rename to docs/customize/browser/all-parameters.mdx
diff --git a/docs/customize/browser-basic.mdx b/docs/customize/browser/basics.mdx
similarity index 100%
rename from docs/customize/browser-basic.mdx
rename to docs/customize/browser/basics.mdx
diff --git a/docs/customize/browser-real-browser.mdx b/docs/customize/browser/real-browser.mdx
similarity index 100%
rename from docs/customize/browser-real-browser.mdx
rename to docs/customize/browser/real-browser.mdx
diff --git a/docs/customize/browser-remote.mdx b/docs/customize/browser/remote.mdx
similarity index 100%
rename from docs/customize/browser-remote.mdx
rename to docs/customize/browser/remote.mdx
diff --git a/docs/customize/custom-functions.mdx b/docs/customize/custom-functions.mdx
deleted file mode 100644
index 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.mdx
similarity index 100%
rename from docs/customize/chain-agents.mdx
rename to docs/customize/examples/chain-agents.mdx
diff --git a/docs/customize/fast-agent.mdx b/docs/customize/examples/fast-agent.mdx
similarity index 100%
rename from docs/customize/fast-agent.mdx
rename to docs/customize/examples/fast-agent.mdx
diff --git a/docs/customize/more-examples.mdx b/docs/customize/examples/more-examples.mdx
similarity index 100%
rename from docs/customize/more-examples.mdx
rename to docs/customize/examples/more-examples.mdx
diff --git a/docs/customize/parallel-browser.mdx b/docs/customize/examples/parallel-browser.mdx
similarity index 100%
rename from docs/customize/parallel-browser.mdx
rename to docs/customize/examples/parallel-browser.mdx
diff --git a/docs/customize/secure.mdx b/docs/customize/examples/secure.mdx
similarity index 100%
rename from docs/customize/secure.mdx
rename to docs/customize/examples/secure.mdx
diff --git a/docs/customize/sensitive-data.mdx b/docs/customize/examples/sensitive-data.mdx
similarity index 100%
rename from docs/customize/sensitive-data.mdx
rename to docs/customize/examples/sensitive-data.mdx
diff --git a/docs/customize/real-browser.mdx b/docs/customize/real-browser.mdx
deleted file mode 100644
index 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.mdx
deleted file mode 100644
index 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.mdx
similarity index 100%
rename from docs/customize/tools-register.mdx
rename to docs/customize/tools/add.mdx
diff --git a/docs/customize/tools-available.mdx b/docs/customize/tools/available.mdx
similarity index 100%
rename from docs/customize/tools-available.mdx
rename to docs/customize/tools/available.mdx
diff --git a/docs/customize/tools-basic.mdx b/docs/customize/tools/basics.mdx
similarity index 100%
rename from docs/customize/tools-basic.mdx
rename to docs/customize/tools/basics.mdx
diff --git a/docs/customize/tools-remove.mdx b/docs/customize/tools/remove.mdx
similarity index 100%
rename from docs/customize/tools-remove.mdx
rename to docs/customize/tools/remove.mdx
diff --git a/docs/customize/tools-response.mdx b/docs/customize/tools/response.mdx
similarity index 100%
rename from docs/customize/tools-response.mdx
rename to docs/customize/tools/response.mdx
diff --git a/docs/docs.json b/docs/docs.json
index 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"
]
}
]