Skip to content

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

Add new tools documentation and enhance existing sections

Magnus Müllerb235e7bfe5ec
diff --git a/docs/customize/tools-available.mdx b/docs/customize/tools-available.mdx
new file mode 100644
index 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.mdx
index 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.mdx
index 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 Parameters
The `@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 Input
diff --git a/docs/customize/tools-remove.mdx b/docs/customize/tools-remove.mdx
new file mode 100644
index 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.mdx
index 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
```python
return 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
```python
return 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.json
index 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"
]
},