Add Tools

Examples:

deterministic clicks
file handling
calling APIs
human-in-the-loop
browser interactions
calling LLMs
get 2fa codes
send emails
Playwright integration (see GitHub example)
…

Simply add @tools.action(...) to your function.

from browser_use import Tools, Agent, ActionResult

tools = Tools()

@tools.action(description='Ask human for help with a question')
async def ask_human(question: str) -> ActionResult:
    answer = input(f'{question} > ')
    return ActionResult(extracted_content=f'The human responded with: {answer}')

agent = Agent(task='...', llm=llm, tools=tools)

description (required) - What the tool does, the 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

The Agent fills your function parameters based on their names, type hints, & defaults.

Common Pitfall: Parameter names must match exactly! Use browser_session: BrowserSession (not browser: Browser). The agent injects special parameters by name matching, so using incorrect names will cause your tool to fail silently. See Available Objects below for the correct parameter names.

Add Tools from an MCP Server

The Python library can also import tools from an external MCP server. This extends a Browser Use agent; it is different from running Browser Use as an MCP server. Install uv and Browser Use, and set BROWSER_USE_API_KEY for the agent’s model. Warm the reference time server’s package cache before connecting:

uvx mcp-server-time==2026.8.18 --help

import asyncio
from browser_use import Agent, ChatBrowserUse, Tools
from browser_use.mcp.client import MCPClient

async def main():
    tools = Tools()
    client = MCPClient(
        server_name="time",
        command="uvx",
        args=["mcp-server-time==2026.8.18", "--local-timezone=UTC"],
    )
    try:
        await client.register_to_tools(
            tools, tool_filter=["get_current_time"], prefix="time_"
        )
        agent = Agent(
            task="Use time_get_current_time to report the current UTC time.",
            llm=ChatBrowserUse(),
            tools=tools,
        )
        await agent.run()
    finally:
        await client.disconnect()

asyncio.run(main())

tool_filter uses the server’s original names. prefix changes the names the agent sees and avoids collisions with built-in actions, which remain available. Keep the connection open until the agent finishes, then disconnect it. Create a fresh client for a new run. The current client launches local stdio servers, has a roughly 10-second connection budget, and reads one tools/list response. It does not yet discover tools on later catalog pages or connect directly to HTTP/SSE endpoints. Only run trusted servers: their subprocesses execute on your machine, and their tools may have side effects. The time lookup itself needs no model key; running the agent above uses your configured model and may incur model charges.

Available Objects

Your function has access to these objects:

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

Browser Interaction Examples

You can use browser_session to directly interact with page elements using CSS selectors:

from browser_use import Tools, Agent, ActionResult, BrowserSession

tools = Tools()

@tools.action(description='Click the submit button using CSS selector')
async def click_submit_button(browser_session: BrowserSession):
    # Get the current page
    page = await browser_session.must_get_current_page()

    # Get element(s) by CSS selector
    elements = await page.get_elements_by_css_selector('button[type="submit"]')

    if not elements:
        return ActionResult(extracted_content='No submit button found')

    # Click the first matching element
    await elements[0].click()

    return ActionResult(extracted_content='Submit button clicked!')

Available methods on Page:

get_elements_by_css_selector(selector: str) - Returns list of matching elements
get_element_by_prompt(prompt: str, llm) - Returns element or None using LLM
must_get_element_by_prompt(prompt: str, llm) - Returns element or raises error

Available methods on Element:

click() - Click the element
type(text: str) - Type text into the element
get_text() - Get element text content
See browser_use/actor/element.py for more methods

Pydantic Input

You can use Pydantic for the tool parameters:

import json
from pydantic import BaseModel, Field
from browser_use import Tools

tools = Tools()

class Cars(BaseModel):
    name: str = Field(description='The name of the car, e.g. "Toyota Camry"')
    price: int = Field(description='The price of the car as int in USD, e.g. 25000')

@tools.action(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'

task = "find cars and save them to file"

Domain Restrictions

Limit tools to specific domains:

@tools.action(
    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}'

Advanced Example

For a comprehensive example of custom tools with Playwright integration, see: Playwright Integration Example This shows how to create custom actions that use Playwright’s precise browser automation alongside Browser-Use.

Common Pitfalls

The agent injects special parameters by name, not by type. Using incorrect parameter names is the most common cause of tools failing silently.

❌ Wrong: Using `browser: Browser`

from browser_use import Tools, ActionResult, Browser

@tools.action('My action')
def my_action(browser: Browser) -> ActionResult:  # WRONG!
    # This will NOT receive the browser session
    pass

✅ Correct: Using `browser_session: BrowserSession`

from browser_use import Tools, ActionResult, BrowserSession

@tools.action('My action')
async def my_action(browser_session: BrowserSession) -> ActionResult:  # CORRECT!
    page = await browser_session.must_get_current_page()
    # Now you have access to the browser
    return ActionResult(extracted_content='Done')

Key Points

Use browser_session: BrowserSession - not browser: Browser
Use async functions - recommended for consistency with browser operations
Return ActionResult - not plain strings (though strings work, ActionResult provides more control)
Parameter names must match exactly - see Available Objects for the full list of injectable parameters

Get Started

Customize

Examples

Development

Add Tools from an MCP Server

Available Objects

Browser Interaction Examples

Pydantic Input

Domain Restrictions

Advanced Example

Common Pitfalls

❌ Wrong: Using `browser: Browser`

✅ Correct: Using `browser_session: BrowserSession`

Key Points

​Add Tools from an MCP Server

​Available Objects

​Browser Interaction Examples

​Pydantic Input

​Domain Restrictions

​Advanced Example

​Common Pitfalls

​❌ Wrong: Using browser: Browser

​✅ Correct: Using browser_session: BrowserSession

​Key Points

Add Tools from an MCP Server

Available Objects

Browser Interaction Examples

Pydantic Input

Domain Restrictions

Advanced Example

Common Pitfalls

❌ Wrong: Using `browser: Browser`

✅ Correct: Using `browser_session: BrowserSession`

Key Points