Tools And Actions

Tools and Actions

Use this sub-skill when the user needs Browser Use actions, custom tools, file operations, upload/download handling, sensitive data placeholders, or action validation. Prefer ChatBrowserUse in examples unless the user already chose another model.

Route Here

• User asks to add @tools.action(...), Tools(), Controller, custom actions, action filters, 2FA helpers, human-in-the-loop actions, deterministic browser helpers, or direct tools.<action>() calls.
• User asks which default actions exist, how to remove actions, or why an action schema/model is rejected.
• User asks about ActionResult, extracted_content, long_term_memory, error, is_done, success, attachments/images, or completion semantics.
• User asks about available_file_paths, write_file, read_file, replace_file, upload_file, downloaded files, or file containment errors.
• User asks how sensitive_data works, how to use <secret>name</secret>, or how to keep secrets scoped to allowed domains.
• User hit tool validation, parameter injection, domain filter, file upload, or security guardrail failures.

Route Elsewhere

• Agent construction, task prompting, run loops, history inspection, callbacks, initial actions, or Python workflow structure: ../agent-programming/SKILL.md.
• Browser/Profile/CDP/session/proxy/download directory/domain navigation configuration: ../browser-control/SKILL.md.
• LLM adapters, structured output models, extraction LLMs, cost, fallback models, or provider credentials: ../llm-and-output/SKILL.md.
• Terminal browser-use / bu CLI sessions and CLI upload commands: ../cli-and-sessions/SKILL.md.
• Cloud/sandbox/MCP/skills/telemetry/production integrations: ../production-integrations/SKILL.md.

Safe Defaults

• Import Tools, ActionResult, and BrowserSession from browser_use; Controller is a backwards-compatible alias for Tools.
• Use Pydantic v2 models for complex custom action input; keep action function parameters explicit and typed.
• Name injected browser parameters exactly browser_session, page_extraction_llm, file_system, available_file_paths, page_url, cdp_client, has_sensitive_data, extraction_schema, or context.
• Do not define **kwargs on a custom action; the registry rejects it. Use explicit parameters or a Pydantic param_model.
• Return ActionResult when the agent needs reasoning context, memory, errors, completion status, files, or attachments; simple strings are accepted but less expressive.
• Scope dangerous or credentialed custom actions with allowed_domains=[...] when possible.
• Use Tools(exclude_actions=[...]) or tools.exclude_action(name) to remove defaults that do not fit the task.
• Pass user-provided upload files through Agent(..., available_file_paths=[...]); never invent local paths.
• Use sensitive_data placeholders instead of embedding passwords or API keys in tasks.

Minimal Custom Tool

from browser_use import ActionResult, Agent, BrowserSession, ChatBrowserUse, Tools

tools = Tools()

@tools.action('Ask the user for a one-line confirmation')
async def ask_user(question: str) -> ActionResult:
    answer = input(f'{question} > ')
    return ActionResult(extracted_content=f'User answered: {answer}')

agent = Agent(task='Ask for confirmation, then continue', llm=ChatBrowserUse(), tools=tools)

For browser-aware actions, use the exact injected name:

@tools.action('Read current page URL')
async def current_url(browser_session: BrowserSession) -> ActionResult:
    url = await browser_session.get_current_page_url()
    return ActionResult(extracted_content=url, long_term_memory=f'Current URL: {url}')

Custom Action Patterns

• Loose parameters: async def fill_field(index: int, text: str, browser_session: BrowserSession); Browser Use auto-generates a Pydantic model for non-special parameters.
• Pydantic model first: define a model and pass param_model=MyParams, then write async def action(params: MyParams, browser_session: BrowserSession).
• Domain-filtered action: @tools.action('Use only on billing pages', allowed_domains=['https://billing.example.com']).
• Sequence-ending action: pass terminates_sequence=True for navigation-like actions where queued multi-actions should stop after execution.
• Direct call in tests/debugging: many registered actions can be called as await tools.read_file(file_name='x.md', browser_session=session, file_system=fs, available_file_paths=[]).

See references/custom-tools.md for full patterns and validation rules.

Default Actions

Core defaults include:

• Navigation and tabs: search, navigate, go_back, wait, switch, close.
• Page interaction: click, input, upload_file, scroll, find_text, send_keys, dropdown actions.
• Page content: extract, search_page, find_elements, evaluate, screenshot, save_pdf.
• File operations: write_file, read_file, replace_file.
• Completion: done or structured done when output_model is configured.

See references/default-actions.md for action parameters, when to exclude defaults, JavaScript evaluation cautions, and file-action behavior.