Skip to content

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

Enhance tool documentation with new examples and clarify action registration process

Magnus Müller9f272fab9a72
diff --git a/docs/customize/tools-basic.mdx b/docs/customize/tools-basic.mdx
index 5ca688bb2..33a4ecbf7 100644
--- a/docs/customize/tools-basic.mdx
+++ b/docs/customize/tools-basic.mdx
@@ -14,6 +14,8 @@ Examples:
- human-in-the-loop
- browser interactions
- calling other LLMs
+- get 2fa code
+- send emails
...
@@ -25,7 +27,7 @@ from browser_use import Controller, ActionResult
controller = Controller()
[email protected](description='Ask human for help with a question')
[email protected]('Ask human for help with a question')
def ask_human(question: str) -> ActionResult:
answer = input(f'{question} > ')
return f'The human responded with: {answer}'
diff --git a/docs/customize/tools-register.mdx b/docs/customize/tools-register.mdx
index 6bd54ffab..8859a3776 100644
--- a/docs/customize/tools-register.mdx
+++ b/docs/customize/tools-register.mdx
@@ -1,69 +1,89 @@
---
-title: "Action Registration"
-description: "Register custom actions, manage controllers, and configure domain restrictions"
+title: "Add Tools"
+description: ""
icon: "plus"
mode: "wide"
---
-## 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`.
+To register your own custom functions (`sync` or `async`), add `@controller.action(...)`.
```python
-from browser_use import Controller, ActionResult
+from browser_use import Controller, Agent
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
[email protected](description='Ask human for help with a question')
def ask_human(question: str) -> ActionResult:
answer = input(f'{question} > ')
- return ActionResult(extracted_content=f'The human responded with: {answer}', include_in_memory=True)
+ return f'The human responded with: {answer}'
```
```python
-# Then pass your controller to the agent to use it
-agent = Agent(
- task='...',
- llm=llm,
- controller=controller,
-)
+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
+ - 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>
-### Excluding Actions
-If you want to exclude some registered actions and make them unavailable to the agent, you can do:
+## Decorator Parameters
+
+The `@controller.action()` decorator accepts these parameters:
+
+- **`description`** *(required)* - What the tool does (LLM uses this to decide when to call it)
+- **`allowed_domains`** - List of domains where tool can run (e.g. `['*.example.com']`), defaults to all domains
+
+## Special Function Parameters
+
+Your tool functions can request these special parameters:
+
+- **`browser_session: BrowserSession`** - Current browser session for CDP access
+- **`cdp_client`** - Direct Chrome DevTools Protocol client
+- **`page_extraction_llm: BaseChatModel`** - The LLM you pass into agent. This can be used to do a custom llm call here.
+- **`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, ...)
```
-<Note>
- The controller is stateless and can be used to register multiple actions and
- multiple agents.
-</Note>
+## Pydantic Input
-## Domain Restrictions
+You can use Pydantic for the tool parameters:
-You can restrict actions to only run on specific domains or pages using the `allowed_domains` or `page_filter` parameters:
+```python
+from pydantic import BaseModel
-### Domain-Based Restrictions
+class Cars(BaseModel):
+ name: str
+ price: int
-```python
[email protected]('Fill out secret_form', allowed_domains=['https://*.example.com'])
-def fill_out_form(...) -> ActionResult:
- # This action will only be runnable by LLM on pages that match https://*.example.com
- ...
-```
[email protected](description='Save cars to file')
+def save_cars(cars: list[Cars]) -> str:
+ with open('cars.json', 'w') as f:
+ json.dump(cars, f)
+ return f'Saved {len(cars)} cars to file'
-## Next Steps
+task = "find cars and save them to file"
+```
+## Domain Restrictions
-- Understand [tool responses and ActionResult](/customize/tools-response)
-- Explore [real examples](https://github.com/browser-use/browser-use/tree/main/examples/custom-functions)
-- Read the [tools overview](/customize/tools-basic)
+Limit tools to specific domains:
+```python
+ description='Fill out banking forms',
+ allowed_domains=['https://mybank.com']
+)
+def fill_bank_form(account_number: str) -> str:
+ # Only works on mybank.com
+ return f'Filled form for account {account_number}'
+```
diff --git a/docs/customize/tools-response.mdx b/docs/customize/tools-response.mdx
index 721b687b6..ad21891f3 100644
--- a/docs/customize/tools-response.mdx
+++ b/docs/customize/tools-response.mdx
@@ -1,211 +1,62 @@
---
title: "Tool Response"
-description: "Return structured responses from custom actions using ActionResult"
+description: ""
icon: "arrow-turn-down-left"
mode: "wide"
---
-All custom actions must return an `ActionResult` object to communicate results back to the agent. The `ActionResult` provides a structured way to return content, handle errors, manage memory, and control task completion.
+Tools return results using `ActionResult` or simple strings.
-## Basic ActionResult
+## Return Types
-The simplest way to return a result:
-
-```python
-from browser_use import ActionResult
-
[email protected]('Simple action')
-def my_action(param: str) -> ActionResult:
- result = f"Processed: {param}"
- return ActionResult(extracted_content=result)
-```
-
-## ActionResult Properties
-
-### Core Properties
-
-- **`extracted_content`** - The main result content that gets passed to the LLM
-- **`error`** - Error message if the action failed (automatically included in memory)
-- **`is_done`** - Set to `True` if this action completes the entire task
-- **`success`** - Whether the task completed successfully (only valid when `is_done=True`)
-
-### Memory Management
-
-- **`long_term_memory`** - Content to store in agent's long-term memory
-- **`include_extracted_content_only_once`** - Whether content should only be used for the next step
-- **`include_in_memory`** - *(Deprecated)* Whether to include extracted_content in memory
-
-### Additional Properties
-
-- **`attachments`** - List of file paths to display in the completion message
-- **`metadata`** - Dictionary for observability data (e.g., click coordinates)
-
-## Common Response Patterns
-
-### Success Response
```python
[email protected]('Process data')
-def process_data(data: str) -> ActionResult:
- # Process the data
- result = perform_processing(data)
-
- return ActionResult(
- extracted_content=f"Successfully processed {len(data)} characters",
- long_term_memory=f"Processed data: {data[:100]}..." if len(data) > 100 else f"Processed data: {data}"
- )
-```
+def my_tool() -> str:
+ return "Task completed successfully"
-### Error Response
-```python
[email protected]('Risky operation')
-def risky_operation(param: str) -> ActionResult:
- try:
- result = dangerous_operation(param)
- return ActionResult(extracted_content=f"Operation succeeded: {result}")
- except Exception as e:
- return ActionResult(
- extracted_content="Operation failed",
- error=str(e) # Error is automatically included in memory
- )
-```
-
-### Task Completion Response
-```python
[email protected]('Complete task')
-def complete_task(summary: str) -> ActionResult:
[email protected]('Advanced tool')
+def advanced_tool() -> ActionResult:
return ActionResult(
- extracted_content=summary,
+ extracted_content="Main result",
+ long_term_memory="Remember this info",
+ error="Something went wrong",
is_done=True,
- success=True, # Only valid when is_done=True
- long_term_memory=f"Task completed successfully: {summary}"
+ success=True,
+ attachments=["file.pdf"],
)
```
-### Response with File Attachments
-```python
[email protected]('Generate report')
-def generate_report(data: str) -> ActionResult:
- # Generate report file
- report_path = create_report(data)
-
- return ActionResult(
- extracted_content="Report generated successfully",
- attachments=[report_path], # Files to show user
- long_term_memory=f"Generated report with {len(data)} data points"
- )
-```
+## ActionResult Properties
-## Memory Behavior
+- `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
-### Long-term Memory
-Content in `long_term_memory` is always persisted and available to the agent across all future steps:
+## Examples
+### Success
```python
-return ActionResult(
- extracted_content="Found 5 products",
- long_term_memory="Product search completed: found iPhone 15, Samsung Galaxy S24, etc."
-)
+return ActionResult(extracted_content="Found 3 results")
```
-### One-time Content
-Use `include_extracted_content_only_once=True` for content that should only be available for the immediate next step:
-
+### Error
```python
return ActionResult(
- extracted_content="Temporary analysis results...",
- include_extracted_content_only_once=True
+ extracted_content="Failed to connect",
+ error="Connection timeout"
)
```
-## Validation Rules
-
-### Task Completion Rules
-- `success=True` can only be set when `is_done=True`
-- Use `success=False` for failed task completion
-- For regular successful actions, leave `success` as `None`
-
-```python
-# ✅ Valid - Task completed successfully
-ActionResult(is_done=True, success=True, extracted_content="All done!")
-
-# ✅ Valid - Task completed but failed
-ActionResult(is_done=True, success=False, extracted_content="Could not complete")
-
-# ✅ Valid - Regular action success
-ActionResult(extracted_content="Step completed")
-
-# ❌ Invalid - success=True without is_done=True
-ActionResult(success=True, extracted_content="Step completed") # Raises ValueError
-```
-
-## Return Type Options
-
-Actions can return multiple types:
-
-```python
-# ActionResult (recommended)
-def action1() -> ActionResult:
- return ActionResult(extracted_content="Result")
-
-# String (converted to ActionResult internally)
-def action2() -> str:
- return "Simple result"
-
-# None (no result)
-def action3() -> None:
- # Action with side effects only
- pass
-```
-
-## Advanced Examples
-
-### Conditional Memory Storage
+### Task Complete
```python
[email protected]('Smart search')
-def smart_search(query: str, save_results: bool = False) -> ActionResult:
- results = search_database(query)
-
- if save_results:
- return ActionResult(
- extracted_content=f"Found {len(results)} results",
- long_term_memory=f"Search '{query}' returned: {results}"
- )
- else:
- return ActionResult(
- extracted_content=f"Found {len(results)} results",
- include_extracted_content_only_once=True
- )
-```
-
-### Rich Metadata Response
-```python
[email protected]('Click with tracking')
-def tracked_click(selector: str, browser_session: Browser) -> ActionResult:
- # Perform click and get coordinates
- coordinates = perform_click(selector)
-
- return ActionResult(
- extracted_content=f"Clicked element {selector}",
- metadata={
- "action_type": "click",
- "selector": selector,
- "coordinates": coordinates,
- "timestamp": time.time()
- }
- )
+return ActionResult(
+ extracted_content="All done!",
+ is_done=True,
+ success=True
+)
```
-
-## Best Practices
-
-1. **Always provide extracted_content** for successful actions
-2. **Use long_term_memory** for important information the agent should remember
-3. **Include error details** in the `error` field for failed actions
-4. **Be descriptive** in your response messages to help the LLM understand results
-5. **Use attachments** to reference files the user should see
-6. **Add metadata** for debugging and observability
-
-## Next Steps
-
-- Learn about [action registration](/customize/tools-register)
-- Explore [tools overview](/customize/tools-basic)
-- Check out [real examples](https://github.com/browser-use/browser-use/tree/main/examples/custom-functions)