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
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.mdxindex 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, ActionResultcontroller = 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.mdxindex 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, Agentcontroller = 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:```pythoncontroller = 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.mdxindex 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}"- )-```[email protected]('My tool')+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```pythonreturn 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)