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
Simplify basics
Magnus Müller264090e86b4f
diff --git a/docs/customize/tools-basic.mdx b/docs/customize/tools-basic.mdxnew file mode 100644index 000000000..5ca688bb2--- /dev/null+++ b/docs/customize/tools-basic.mdx@@ -0,0 +1,38 @@+---+title: "Basics"+description: ""+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+...+++## Quick Example+++```python+from browser_use import Controller, ActionResult++controller = Controller()+[email protected](description='Ask human for help with a question')+def ask_human(question: str) -> ActionResult:+ answer = input(f'{question} > ')+ return f'The human responded with: {answer}'++agent = Agent(+ task='Ask human for help',+ llm=llm,+ controller=controller,+)+```diff --git a/docs/customize/tools-register.mdx b/docs/customize/tools-register.mdxnew file mode 100644index 000000000..6bd54ffab--- /dev/null+++ b/docs/customize/tools-register.mdx@@ -0,0 +1,69 @@+---+title: "Action Registration"+description: "Register custom actions, manage controllers, and configure domain restrictions"+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`.++```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>+### Excluding Actions++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, ...)+```++<Note>+ The controller is stateless and can be used to register multiple actions and+ multiple agents.+</Note>++## Domain Restrictions++You can restrict actions to only run on specific domains or pages using the `allowed_domains` or `page_filter` parameters:++### Domain-Based Restrictions++```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+ ...+```++## Next Steps++- 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)+diff --git a/docs/customize/tools-response.mdx b/docs/customize/tools-response.mdxnew file mode 100644index 000000000..721b687b6--- /dev/null+++ b/docs/customize/tools-response.mdx@@ -0,0 +1,211 @@+---+title: "Tool Response"+description: "Return structured responses from custom actions using ActionResult"+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.++## Basic ActionResult++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}"+ )+```++### 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:+ return ActionResult(+ extracted_content=summary,+ is_done=True,+ success=True, # Only valid when is_done=True+ long_term_memory=f"Task completed successfully: {summary}"+ )+```++### 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"+ )+```++## Memory Behavior++### Long-term Memory+Content in `long_term_memory` is always persisted and available to the agent across all future steps:++```python+return ActionResult(+ extracted_content="Found 5 products",+ long_term_memory="Product search completed: found iPhone 15, Samsung Galaxy S24, etc."+)+```++### One-time Content+Use `include_extracted_content_only_once=True` for content that should only be available for the immediate next step:++```python+return ActionResult(+ extracted_content="Temporary analysis results...",+ include_extracted_content_only_once=True+)+```++## 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+```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()+ }+ )+```++## 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)diff --git a/docs/docs.json b/docs/docs.jsonindex 45ba63082..d8145f7d4 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -60,6 +60,16 @@"customize/browser-parameters"]},+ {+ "group": "Tools",+ "icon": "wrench",+ "isDefaultOpen": false,+ "pages": [+ "customize/tools-basic",+ "customize/tools-register",+ "customize/tools-response"+ ]+ },{"group": "Examples","icon": "folder-open",@@ -71,8 +81,7 @@"customize/secure","customize/more-examples"]- },- "customize/custom-functions"+ }]},{