Skip to content

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

Shorter tools

Magnus Müller22acf58424ac
diff --git a/browser_use/tools/service.py b/browser_use/tools/service.py
index 5815b618d..4c3b883f0 100644
--- a/browser_use/tools/service.py
+++ b/browser_use/tools/service.py
@@ -115,7 +115,7 @@ class Tools(Generic[Context]):
# Basic Navigation Actions
@self.registry.action(
- 'Search query (defaults DuckDuckGo). Options: duckduckgo, google, bing.',
+ 'Search query.',
param_model=SearchAction,
)
async def search(params: SearchAction, browser_session: BrowserSession):
@@ -158,7 +158,7 @@ class Tools(Generic[Context]):
return ActionResult(error=f'Failed to search {params.search_engine} for "{params.query}": {str(e)}')
@self.registry.action(
- 'Navigate to URL. Set new_tab=True to open in new tab.',
+ 'Navigate to URL.',
param_model=GoToUrlAction,
)
async def go_to_url(params: GoToUrlAction, browser_session: BrowserSession):
@@ -218,7 +218,7 @@ class Tools(Generic[Context]):
error_msg = f'Failed to go back: {str(e)}'
return ActionResult(error=error_msg)
- @self.registry.action('Wait x seconds (default 3, max 30). ')
+ @self.registry.action('Wait for page load.')
async def wait(seconds: int = 3):
# Cap wait time at maximum 30 seconds
# Reduce the wait time by 3 seconds to account for the llm call which takes at least 3 seconds
@@ -234,7 +234,7 @@ class Tools(Generic[Context]):
# Element Interaction Actions
@self.registry.action(
- 'Click element by index from browser_state. Set ctrl=True to open in new tab.',
+ 'Click element.',
param_model=ClickElementAction,
)
async def click(params: ClickElementAction, browser_session: BrowserSession):
@@ -288,7 +288,7 @@ class Tools(Generic[Context]):
return ActionResult(error=error_msg)
@self.registry.action(
- 'Input text into element by index from browser_state.',
+ 'Input text.',
param_model=InputTextAction,
)
async def input_text(
@@ -350,7 +350,7 @@ class Tools(Generic[Context]):
return ActionResult(error=error_msg)
@self.registry.action(
- 'Upload file to element by index from browser_state.',
+ 'Upload file.',
param_model=UploadFileAction,
)
async def upload_file(
@@ -501,7 +501,7 @@ class Tools(Generic[Context]):
# Tab Management Actions
- @self.registry.action('Switch to tab by tab_id.', param_model=SwitchTabAction)
+ @self.registry.action('Switch tab.', param_model=SwitchTabAction)
async def switch_tab(params: SwitchTabAction, browser_session: BrowserSession):
# Simple switch tab logic
try:
@@ -523,7 +523,7 @@ class Tools(Generic[Context]):
memory = f'Attempted to switch to tab #{params.tab_id}'
return ActionResult(extracted_content=memory, long_term_memory=memory)
- @self.registry.action('Close tab by tab_id.', param_model=CloseTabAction)
+ @self.registry.action('Close tab.', param_model=CloseTabAction)
async def close_tab(params: CloseTabAction, browser_session: BrowserSession):
# Simple close tab logic
try:
@@ -555,11 +555,7 @@ class Tools(Generic[Context]):
# This action is temporarily disabled as it needs refactoring to use events
@self.registry.action(
- """Extract semantic data from page markdown via LLM query (e.g. product info, prices).
-Use when: on right page, know what to extract, haven't used on same page before.
-Can't get: interactive elements (buttons, links, dropdowns).
-Set extract_links=True for URLs. Use start_from_char if truncated.
-If fails, use scroll_to_text or scroll instead.""",
+ """Extract page data via LLM. Use when on right page, know what to extract. Can't get interactive elements.""",
)
async def extract_structured_data(
query: str,
@@ -679,9 +675,7 @@ You will be given a query and the markdown of a webpage that has been filtered t
raise RuntimeError(str(e))
@self.registry.action(
- """Scroll page by num_pages (down=True for down, False for up). Default 1 page, use 0.5 for half, 10 for bottom.
-For specific containers, use frame_element_index from browser_state (works with dropdowns, custom UI).
-Multiple pages (>=1.0) scroll sequentially. Page height from viewport or 1000px fallback.""",
+ 'Scroll page. Multiple pages scroll sequentially.',
param_model=ScrollAction,
)
async def scroll(params: ScrollAction, browser_session: BrowserSession):
@@ -790,7 +784,7 @@ Multiple pages (>=1.0) scroll sequentially. Page height from viewport or 1000px
return ActionResult(error=error_msg)
@self.registry.action(
- 'Send special keys (Escape, Enter, PageDown) or shortcuts (Control+o, Control+Shift+T).',
+ 'Send keys.',
param_model=SendKeysAction,
)
async def send_keys(params: SendKeysAction, browser_session: BrowserSession):
@@ -809,7 +803,7 @@ Multiple pages (>=1.0) scroll sequentially. Page height from viewport or 1000px
return ActionResult(error=error_msg)
@self.registry.action(
- description='Scroll to text on page. Prefer over step-by-step scrolling when target known.',
+ description='Scroll to text.',
)
async def scroll_to_text(text: str, browser_session: BrowserSession): # type: ignore
# Dispatch scroll to text event
@@ -831,7 +825,7 @@ Multiple pages (>=1.0) scroll sequentially. Page height from viewport or 1000px
long_term_memory=f"Tried scrolling to text '{text}' but it was not found",
)
- @self.registry.action('Request screenshot in next browser state. Use for visual confirmation or complex visual content.')
+ @self.registry.action('Request screenshot.')
async def take_screenshot():
"""Request that a screenshot be included in the next observation"""
memory = 'Requested screenshot for next observation'
@@ -847,7 +841,7 @@ Multiple pages (>=1.0) scroll sequentially. Page height from viewport or 1000px
# Dropdown Actions
@self.registry.action(
- 'Get dropdown values (<select>, ARIA select). Only for dropdown elements.',
+ 'Get dropdown options.',
param_model=GetDropdownOptionsAction,
)
async def get_dropdown_options(params: GetDropdownOptionsAction, browser_session: BrowserSession):
@@ -873,7 +867,7 @@ Multiple pages (>=1.0) scroll sequentially. Page height from viewport or 1000px
)
@self.registry.action(
- 'Select dropdown option by exact text (native <select>, ARIA, custom). Searches element and children.',
+ 'Select dropdown option.',
param_model=SelectDropdownOptionAction,
)
async def select_dropdown_option(params: SelectDropdownOptionAction, browser_session: BrowserSession):
@@ -916,7 +910,7 @@ Multiple pages (>=1.0) scroll sequentially. Page height from viewport or 1000px
return ActionResult(error=error_msg)
# File System Actions
- @self.registry.action('Write/append to file (.md, .txt, .json, .csv, .pdf). PDF: write markdown, auto-converts to PDF.')
+ @self.registry.action('Write/append file.')
async def write_file(
file_name: str,
content: str,
@@ -936,15 +930,13 @@ Multiple pages (>=1.0) scroll sequentially. Page height from viewport or 1000px
logger.info(f'💾 {result}')
return ActionResult(extracted_content=result, long_term_memory=result)
- @self.registry.action(
- 'Replace old_str with new_str in file. old_str must match exactly. For todo.md updates or specific edits.'
- )
+ @self.registry.action('Replace in file.')
async def replace_file_str(file_name: str, old_str: str, new_str: str, file_system: FileSystem):
result = await file_system.replace_file_str(file_name, old_str, new_str)
logger.info(f'💾 {result}')
return ActionResult(extracted_content=result, long_term_memory=result)
- @self.registry.action('Read file from file system.')
+ @self.registry.action('Read file.')
async def read_file(file_name: str, available_file_paths: list[str], file_system: FileSystem):
if available_file_paths and file_name in available_file_paths:
result = await file_system.read_file(file_name, external_file=True)
@@ -974,22 +966,11 @@ Multiple pages (>=1.0) scroll sequentially. Page height from viewport or 1000px
)
@self.registry.action(
- """Execute JavaScript with Runtime.evaluate (returnByValue:true, awaitPromise:true).
-
-SYNTAX RULES - ALWAYS wrap in IIFE or get "Uncaught at line 0":
-- IIFE: (function(){ ... })() or async: (async function(){ ... })()
-- Add try-catch, proper semicolons, validate elements exist
+ """Execute JS. MUST wrap in IIFE: (function(){...})() or async: (async function(){...})()
+Use when other tools fail or need custom logic.
-Use when other tools fail or need custom logic (forms, hover, drag, extract links, custom selectors, shadow DOM, React/Vue/Angular, etc.).
-
-Examples:
CORRECT: (function(){ try { const el = document.querySelector('#id'); return el ? el.value : 'not found'; } catch(e) { return 'Error: ' + e.message; } })()
-CORRECT: (async function(){ try { await new Promise(r => setTimeout(r, 100)); return 'done'; } catch(e) { return 'Error: ' + e.message; } })()
-WRONG: document.querySelector('#id').value (no IIFE)
-
-Shadow DOM: (function(){ try { const hosts = document.querySelectorAll('*'); for (let host of hosts) { if (host.shadowRoot) { const el = host.shadowRoot.querySelector('#target'); if (el) return el.textContent; } } return 'Not found'; } catch(e) { return 'Error: ' + e.message; } })()
-
-Returns strings, numbers, booleans, objects/arrays. Use JSON.stringify() for complex objects.""",
+WRONG: document.querySelector('#id').value""",
)
async def execute_js(code: str, browser_session: BrowserSession):
# Execute JavaScript with proper error handling and promise support
@@ -1154,7 +1135,7 @@ Returns strings, numbers, booleans, objects/arrays. Use JSON.stringify() for com
self.display_files_in_done_text = display_files_in_done_text
@self.registry.action(
- 'Complete task with return text. Set success=True if finished, False if not (e.g. max steps reached).',
+ 'Complete task with structured output.',
param_model=StructuredOutputAction[output_model],
)
async def done(params: StructuredOutputAction):
@@ -1176,7 +1157,7 @@ Returns strings, numbers, booleans, objects/arrays. Use JSON.stringify() for com
else:
@self.registry.action(
- 'Complete task with summary. Set success=True if completed successfully. Include files in files_to_display.',
+ 'Complete task.',
param_model=DoneAction,
)
async def done(params: DoneAction, file_system: FileSystem):
diff --git a/browser_use/tools/views.py b/browser_use/tools/views.py
index c93ecc02a..a019890e6 100644
--- a/browser_use/tools/views.py
+++ b/browser_use/tools/views.py
@@ -6,7 +6,7 @@ from pydantic import BaseModel, ConfigDict, Field
# Action Input Models
class SearchAction(BaseModel):
query: str
- search_engine: str = 'duckduckgo' # Options: 'duckduckgo', 'google', 'bing'
+ search_engine: str = Field(default='duckduckgo', description='duckduckgo, google, bing')
# Backward compatibility alias
@@ -15,65 +15,59 @@ SearchAction = SearchAction
class GoToUrlAction(BaseModel):
url: str
- new_tab: bool = False # True to open in new tab, False to navigate in current tab
+ new_tab: bool = Field(default=False)
class ClickElementAction(BaseModel):
- index: int = Field(ge=1, description='index of the element to click')
+ index: int = Field(ge=1, description='from browser_state')
ctrl: bool | None = Field(
default=None,
- description='Set to True to open the navigation in a new background tab (Ctrl+Click behavior). Optional.',
+ description='True=New background tab (Ctrl+Click)',
)
# expect_download: bool = Field(default=False, description='set True if expecting a download, False otherwise') # moved to downloads_watchdog.py
# click_count: int = 1 # TODO
class InputTextAction(BaseModel):
- index: int = Field(ge=0, description='index of the element to input text into, 0 is the page')
+ index: int = Field(ge=1, description='from browser_state')
text: str
- clear_existing: bool = Field(default=True, description='set True to clear existing text, False to append to existing text')
+ clear_existing: bool = Field(default=True, description='True to clear, False to append')
class DoneAction(BaseModel):
- text: str
- success: bool
- files_to_display: list[str] | None = []
+ text: str = Field(description='summary for user')
+ success: bool = Field(description='True if completed')
+ files_to_display: list[str] | None = Field(default=[], description='files to display')
T = TypeVar('T', bound=BaseModel)
class StructuredOutputAction(BaseModel, Generic[T]):
- success: bool = True
+ success: bool = Field(default=True, description='True if finished, False if not')
data: T
class SwitchTabAction(BaseModel):
- tab_id: str = Field(
- min_length=4,
- max_length=4,
- description="tab_id to switch to which is displayed as 'Tab <tab_id>' in the browser_state.",
- ) # last 4 chars of TargetID
+ tab_id: str = Field(min_length=4, max_length=4, description="from browser_state ('Tab <tab_id>')")
class CloseTabAction(BaseModel):
- tab_id: str = Field(
- min_length=4, max_length=4, description="tab_id to close which is displayed as 'Tab <tab_id>' in the browser_state."
- ) # last 4 chars of TargetID
+ tab_id: str = Field(min_length=4, max_length=4, description="from browser_state ('Tab <tab_id>')")
class ScrollAction(BaseModel):
- down: bool # True to scroll down, False to scroll up
- num_pages: float = 1.0 # Number of pages to scroll (0.5 = half page, 1.0 = one page, etc.)
- frame_element_index: int | None = None # Optional element index to find scroll container for
+ down: bool = Field(description='True=down, False=up')
+ num_pages: float = Field(default=1.0, description='pages to scroll (0.5=half, 1=page, 10=bottom)')
+ frame_element_index: int | None = Field(default=None, description='index for specific container')
class SendKeysAction(BaseModel):
- keys: str
+ keys: str = Field(description='keys (Escape, Enter, PageDown) or shortcuts (Control+o)')
class UploadFileAction(BaseModel):
- index: int
+ index: int = Field(description='from browser_state')
path: str
@@ -82,19 +76,15 @@ class ExtractPageContentAction(BaseModel):
class NoParamsAction(BaseModel):
- """
- Accepts absolutely anything in the incoming data
- and discards it, so the final parsed model is empty.
- """
+ """Accepts any input, discards it, returns empty model."""
model_config = ConfigDict(extra='ignore')
- # No fields defined - all inputs are ignored automatically
class GetDropdownOptionsAction(BaseModel):
- index: int = Field(ge=1, description='index of the dropdown element to get the option values for')
+ index: int = Field(ge=1, description='dropdown from browser_state')
class SelectDropdownOptionAction(BaseModel):
- index: int = Field(ge=1, description='index of the dropdown element to select an option for')
- text: str = Field(description='the text or exact value of the option to select')
+ index: int = Field(ge=1, description='dropdown from browser_state')
+ text: str = Field(description='exact text/value to select')