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
Add new tools documentation and enhance existing sections
Magnus Müllerb235e7bfe5ec
diff --git a/docs/customize/tools-available.mdx b/docs/customize/tools-available.mdxnew file mode 100644index 000000000..7c6a37150--- /dev/null+++ b/docs/customize/tools-available.mdx@@ -0,0 +1,43 @@+---+title: "Available Tools"+description: "Here is the [source code](https://github.com/browser-use/browser-use/blob/main/browser_use/controller/service.py) for the default tools:"+icon: "list"+mode: "wide"+---+++++### Navigation & Browser Control+- **`search_google`** - Search queries in Google+- **`go_to_url`** - Navigate to URLs+- **`go_back`** - Go back in browser history+- **`wait`** - Wait for specified seconds++### Page Interaction+- **`click_element_by_index`** - Click elements by their index+- **`input_text`** - Input text into form fields+- **`upload_file_to_element`** - Upload files to file inputs+- **`scroll`** - Scroll the page up/down+- **`scroll_to_text`** - Scroll to specific text on page+- **`send_keys`** - Send special keys (Enter, Escape, etc.)++### Tab Management+- **`switch_tab`** - Switch between browser tabs+- **`close_tab`** - Close browser tabs++### Content Extraction+- **`extract_structured_data`** - Extract data from webpages using LLM++### Form Controls+- **`get_dropdown_options`** - Get dropdown option values+- **`select_dropdown_option`** - Select dropdown options++### File Operations+- **`write_file`** - Write content to files+- **`read_file`** - Read file contents+- **`replace_file_str`** - Replace text in files++### Task Completion+- **`done`** - Complete the task (always available)+diff --git a/docs/customize/tools-basic.mdx b/docs/customize/tools-basic.mdxindex 33a4ecbf7..21c9d4bcf 100644--- a/docs/customize/tools-basic.mdx+++ b/docs/customize/tools-basic.mdx@@ -1,23 +1,10 @@---title: "Basics"-description: ""+description: "Tools are the functions that the agent has to interact with the world."icon: "play"mode: "wide"----You can add custom tools to our [default tools](https://github.com/browser-use/browser-use/blob/main/browser_use/controller/service.py).--Examples:-- deterministic clicks-- file handling-- calling APIs-- human-in-the-loop-- browser interactions-- calling other LLMs-- get 2fa code-- send emails-...-## Quick Example@@ -38,3 +25,4 @@ agent = Agent(controller=controller,)```+diff --git a/docs/customize/tools-register.mdx b/docs/customize/tools-register.mdxindex 8859a3776..1d82bb4c6 100644--- a/docs/customize/tools-register.mdx+++ b/docs/customize/tools-register.mdx@@ -1,11 +1,22 @@---title: "Add Tools"-description: ""+description: "You can add your own tools!"icon: "plus"mode: "wide"---+Examples:+- deterministic clicks+- file handling+- calling APIs+- human-in-the-loop+- browser interactions+- calling LLMs+- get 2fa codes+- send emails+...+To register your own custom functions (`sync` or `async`), add `@controller.action(...)`.```python@@ -24,21 +35,22 @@ agent = Agent(task='...', llm=llm, controller=controller)```-<Note>- - The Agent chooses between tools to run solely based on the function name and description- - The Agent decides how to fill tool params based on their names, type hints, & defaults-</Note>## Decorator ParametersThe `@controller.action()` decorator accepts these parameters:-- **`description`** *(required)* - What the tool does (LLM uses this to decide when to call it)+- **`description`** *(required)* - What the tool does, the LLM uses this to decide when to call it. Explain here the rules how to use the tool.- **`allowed_domains`** - List of domains where tool can run (e.g. `['*.example.com']`), defaults to all domains-## Special Function Parameters+<Note>+ - The Agent chooses between tools to run solely based on the function name and description+ - The Agent fills tool parameters based on their names, type hints, & defaults+</Note>++## Available Objects-Your tool functions can request these special parameters:+Your tools have access to these objects:- **`browser_session: BrowserSession`** - Current browser session for CDP access- **`cdp_client`** - Direct Chrome DevTools Protocol client@@ -46,14 +58,6 @@ Your tool functions can request these special parameters:- **`file_system: FileSystem`** - File system access- **`available_file_paths: list[str]`** - Available files for upload/processing- **`has_sensitive_data: bool`** - Whether action contains sensitive data-## Remove Tools--You can exclude default tools:--```python-controller = Controller(exclude_actions=['search_google'])-agent = Agent(controller=controller, ...)-```## Pydantic Inputdiff --git a/docs/customize/tools-remove.mdx b/docs/customize/tools-remove.mdxnew file mode 100644index 000000000..c285714bc--- /dev/null+++ b/docs/customize/tools-remove.mdx@@ -0,0 +1,16 @@+---+title: "Remove Tools"+description: "Exclude default tools from your controller"+icon: "minus"+mode: "wide"+---++You can exclude default tools when creating a controller:++```python+from browser_use import Controller++controller = Controller(exclude_actions=['search_google', 'wait'])+agent = Agent(task='...', llm=llm, controller=controller)+```+diff --git a/docs/customize/tools-response.mdx b/docs/customize/tools-response.mdxindex ad21891f3..4e2e46737 100644--- a/docs/customize/tools-response.mdx+++ b/docs/customize/tools-response.mdx@@ -28,35 +28,55 @@ def advanced_tool() -> ActionResult:## ActionResult Properties-- `extracted_content` - Main result passed to LLM-- `long_term_memory` - Stored across all future steps-- `error` - Error message (auto-included in memory)-- `is_done` - Tool completes entire task-- `success` - Task success (only with `is_done=True`)-- `attachments` - Files to show user-- `metadata` - Debug/observability data-- `include_extracted_content_only_once` - One-time content--## Examples--### Success+- `extracted_content` (default: `None`) - Main result passed to LLM, this is equivalent to returning a string.+- `include_extracted_content_only_once` (default: `False`) - Set to `True` for large content to include it only once in the LLM input.+- `long_term_memory` (default: `None`) - This is always included in the LLM input for all future steps.+- `error` (default: `None`) - Error message, we catch exceptions and set this automatically. This is always included in the LLM input.+- `is_done` (default: `False`) - Tool completes entire task+- `success` (default: `None`) - Task success (only valid with `is_done=True`)+- `attachments` (default: `None`) - Files to show user+- `metadata` (default: `None`) - Debug/observability data++## Why `extracted_content` and `long_term_memory`?+With this you control the context for the LLM.++### 1. Simple response```python-return ActionResult(extracted_content="Found 3 results")+def simple_tool() -> str:+ return "Hello, world!" # Keep in context for all future steps (recommended)```+This is equivalent to: `ActionResult(extracted_content="Hello, world!")` and `ActionResult(long_term_memory="Hello, world!")` without any other properties.-### Error+### 2. Long content - show once, remember subset```pythonreturn ActionResult(- extracted_content="Failed to connect",- error="Connection timeout"+ extracted_content="[500 lines of product data...]", # Shows to LLM once+ include_extracted_content_only_once=True, # Never show full output again+ long_term_memory="Found 50 products" # Only this in future steps)```+We save the full `extracted_content` to files which the LLM can read in future steps.-### Task Complete+### 3. Long content - show never, remember subset```pythonreturn ActionResult(- extracted_content="All done!",- is_done=True,- success=True+ extracted_content="[500 lines of product data...]", # The LLM never sees this because `long_term_memory` overrides it and `include_extracted_content_only_once` is not used+ long_term_memory="Saved user's favorite products", # This is shown to the LLM in future steps)```++## Terminating the Agent++Set `is_done=True` to stop the agent completely. Use when your tool finishes the entire task:++```python[email protected](description='Complete the task')+def finish_task() -> ActionResult:+ return ActionResult(+ extracted_content="Task completed!",+ is_done=True, # Stops the agent+ success=True # Task succeeded+ )+```++diff --git a/docs/docs.json b/docs/docs.jsonindex d8145f7d4..b05cbc53f 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -66,7 +66,9 @@"isDefaultOpen": false,"pages": ["customize/tools-basic",+ "customize/tools-available","customize/tools-register",+ "customize/tools-remove","customize/tools-response"]},