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
replace old cursorrules with new AGENTS.md
Alezander994cb5262ed85
diff --git a/.cursor/rules/browser-use-rules.mdc b/.cursor/rules/browser-use-rules.mdcdeleted file mode 100644index 58a192f65..000000000--- a/.cursor/rules/browser-use-rules.mdc+++ /dev/null@@ -1,61 +0,0 @@-----description:-globs:-alwaysApply: true------## 🧠 General Guidelines for Contributing to `browser-use`--**Browser-Use** is an AI agent that autonomously interacts with the web. It takes a user-defined task, navigates web pages using Chromium via CDP, processes HTML, and repeatedly queries a language model (like `gpt-4.1-mini`) to decide the next action—until the task is completed.-------### 🧰 Development Rules--- ✅ **Always use [`uv`](mdc:https:/github.com/astral-sh/uv) instead of `pip`**- For deterministic and fast dependency installs.--```bash-uv venv --python 3.11-source .venv/bin/activate-uv sync-```--- ✅ **Use real model names**- Do **not** replace `gpt-4o` with `gpt-4`. The model `gpt-4o` is a distinct release and supported.--- ✅ **Type-safe coding**- Use **Pydantic v2 models** for all internal action schemas, task inputs/outputs, and tools I/O. This ensures robust validation and LLM-call integrity.--- ✅ **Pre-commit formatting**- ALWAYS make sure to run pre-commit before making PRs.---------### Notes:--- Use descriptive names and docstrings for each action.-- Prefer returning `ActionResult` with structured content to help the agent reason better.-------## 🧠 Creating and Running an Agent--To define a task and run a browser-use agent:--```python-from browser_use import Agent, ChatOpenAI--task = "Find the CEO of OpenAI and return their name"-model = ChatOpenAI(model="gpt-4.1-mini")--agent = Agent(task=task, llm=model, tools=tools)--history = await agent.run()-```--# Never create random examples--When I ask you to implement a feature never create new files that show off that feature -> the code just gets messy. If you do anything to test it out, just do the inline code inside the terminal (if you want).diff --git a/AGENTS.MD b/AGENTS.MDnew file mode 100644index 000000000..de47b5f6f--- /dev/null+++ b/AGENTS.MD@@ -0,0 +1,924 @@+<guidelines>+Browser-Use is an AI agent that autonomously interacts with the web. It takes a user-defined task, navigates web pages using Chromium via CDP, processes HTML, and repeatedly queries a language model (like `gpt-4.1-mini`) to decide the next action—until the task is completed.++# Development Rules+- Always use [`uv`](mdc:https:/github.com/astral-sh/uv) instead of `pip`+```bash+uv venv --python 3.11+source .venv/bin/activate+uv sync+```++- Do not replace model names. Users try new models which you will not know about yet.++- Type-safe coding: Use Pydantic v2 models for all internal action schemas, task inputs/outputs, and tools I/O. This ensures robust validation and LLM-call integrity.++- Pre-commit formatting: ALWAYS make sure to run pre-commit before making PRs.++- Use descriptive names and docstrings for each action.++- Prefer returning `ActionResult` with structured content to help the agent reason better.++- Follow the documentation in <browser_use_docs/>: some docs have been truncated, if unsure, you can visit or request the information from specific docs pages before proceeding.++- Never create random examples: When asked to implement a feature never create new files that show off that feature -> the code just gets messy. If you do anything to test it out, just use inline code inside the terminal (if you want).++</guidelines>++<browser_use_docs>+# Human Quickstart+Source: (go to or request this content to learn more) https://docs.browser-use.com/quickstart++## 1. Fast setup++<Tabs>+ <Tab title="uv">+ ```bash create environment theme={null}+ uv venv --python 3.12+ ```+ </Tab>++ <Tab title="pip">+ ```bash create environment with python >= 3.11 theme={null}+ python3.12 -m venv .venv+ ```+ </Tab>+</Tabs>++<Tabs>+ <Tab title="Mac/Linux">+ ```bash activate environment theme={null}+ source .venv/bin/activate+ ```+ </Tab>++ <Tab title="Windows">+ ```bash activate environment theme={null}+ .venv\Scripts\activate+ ```+ </Tab>+</Tabs>++<Tabs>+ <Tab title="uv">+ ```bash install browser-use & chromium theme={null}+ uv pip install browser-use+ uvx playwright install chromium --with-deps+ ```+ </Tab>++ <Tab title="pip">+ ```bash install browser-use & chromium theme={null}+ pip install browser-use+ pip install playwright && playwright install chromium --with-deps+ ```+ </Tab>+</Tabs>++## 2. Choose your favorite LLM++Create a `.env` file and add your API key. Don't have one? Start with a [free Gemini key](https://aistudio.google.com/app/u/1/apikey?pli=1).++<Tabs>+ <Tab title="Mac/Linux">+ ```bash create .env file theme={null}+ touch .env+ ```+ </Tab>++ <Tab title="Windows">+ ```cmd create .env file theme={null}+ echo. > .env+ ```+ </Tab>+</Tabs>++<Tabs>+ <Tab title="Google">+ ```bash add your key to .env file theme={null}+ GEMINI_API_KEY=+ ```+ </Tab>++ <Tab title="OpenAI">+ ```bash add your key to .env file theme={null}+ OPENAI_API_KEY=+ ```+ </Tab>++ <Tab title="Anthropic">+ ```bash add your key to .env file theme={null}+ ANTHROPIC_API_KEY=+ ```+ </Tab>+</Tabs>++See [Supported Models](/customize/supported-models) for more.++## 3. Run your first agent++<Tabs>+ <Tab title="Google">+ ```python agent.py theme={null}+ from browser_use import Agent, ChatGoogle+ from dotenv import load_dotenv+ import asyncio++ load_dotenv()++ async def main():+ llm = ChatGoogle(model="gemini-flash-latest")+ task = "Find the number 1 post on Show HN"+ agent = Agent(task=task, llm=llm)+ await agent.run()++ if __name__ == "__main__":+ asyncio.run(main())+ ```+ </Tab>++ <Tab title="OpenAI">+ ```python agent.py theme={null}+ from browser_use import Agent, ChatOpenAI+ from dotenv import load_dotenv+ import asyncio++ load_dotenv()++ async def main():+ llm = ChatOpenAI(model="gpt-4.1-mini")+ task = "Find the number 1 post on Show HN"+ agent = Agent(task=task, llm=llm)+ await agent.run()++ if __name__ == "__main__":+ asyncio.run(main())+ ```+ </Tab>++ <Tab title="Anthropic">+ ```python agent.py theme={null}+ from browser_use import Agent, ChatAnthropic+ from dotenv import load_dotenv+ import asyncio++ load_dotenv()++ async def main():+ llm = ChatAnthropic(model='claude-sonnet-4-0', temperature=0.0)+ task = "Find the number 1 post on Show HN"+ agent = Agent(task=task, llm=llm)+ await agent.run()++ if __name__ == "__main__":+ asyncio.run(main())+ ```+ </Tab>+</Tabs>+++# Actor All Parameters+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/actor/all-parameters++Complete API reference for Browser Actor classes, methods, and parameters including BrowserSession, Page, Element, and Mouse+++# Actor Basics+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/actor/basics+Low-level Playwright-like browser automation with direct and full CDP control and precise element interactions+++# Actor Examples+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/actor/examples+Comprehensive examples for Browser Actor automation tasks including forms, JavaScript, mouse operations, and AI features+++# Agent All Parameters+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/agent/all-parameters++Complete reference for all agent configuration options++## Available Parameters++### Core Settings++* `tools`: Registry of [our tools](https://github.com/browser-use/browser-use/blob/main/browser_use/tools/service.py) the agent can call. [Example for custom tools](https://github.com/browser-use/browser-use/tree/main/examples/custom-functions)+* `browser`: Browser object where you can specify the browser settings.+* `output_model_schema`: Pydantic model class for structured output validation. [Example](https://github.com/browser-use/browser-use/blob/main/examples/features/custom_output.py)++### Vision & Processing++* `use_vision` (default: `"auto"`): Vision mode - `"auto"` includes screenshot tool but only uses vision when requested, `True` always includes screenshots, `False` never includes screenshots and excludes screenshot tool+* `vision_detail_level` (default: `'auto'`): Screenshot detail level - `'low'`, `'high'`, or `'auto'`+* `page_extraction_llm`: Separate LLM model for page content extraction. You can choose a small & fast model because it only needs to extract text from the page (default: same as `llm`)++### Actions & Behavior++* `initial_actions`: List of actions to run before the main task without LLM. [Example](https://github.com/browser-use/browser-use/blob/main/examples/features/initial_actions.py)+* `max_actions_per_step` (default: `10`): Maximum actions per step, e.g. for form filling the agent can output 10 fields at once. We execute the actions until the page changes.+* `max_failures` (default: `3`): Maximum retries for steps with errors+* `final_response_after_failure` (default: `True`): If True, attempt to force one final model call with intermediate output after max\_failures is reached+* `use_thinking` (default: `True`): Controls whether the agent uses its internal "thinking" field for explicit reasoning steps.+* `flash_mode` (default: `False`): Fast mode that skips evaluation, next goal and thinking and only uses memory. If `flash_mode` is enabled, it overrides `use_thinking` and disables the thinking process entirely. [Example](https://github.com/browser-use/browser-use/blob/main/examples/getting_started/05_fast_agent.py)++### System Messages++* `override_system_message`: Completely replace the default system prompt.+* `extend_system_message`: Add additional instructions to the default system prompt. [Example](https://github.com/browser-use/browser-use/blob/main/examples/features/custom_system_prompt.py)++### File & Data Management++* `save_conversation_path`: Path to save complete conversation history+* `save_conversation_path_encoding` (default: `'utf-8'`): Encoding for saved conversations+* `available_file_paths`: List of file paths the agent can access+* `sensitive_data`: Dictionary of sensitive data to handle carefully. [Example](https://github.com/browser-use/browser-use/blob/main/examples/features/sensitive_data.py)++### Visual Output++* `generate_gif` (default: `False`): Generate GIF of agent actions. Set to `True` or string path+* `include_attributes`: List of HTML attributes to include in page analysis++### Performance & Limits++* `max_history_items`: Maximum number of last steps to keep in the LLM memory. If `None`, we keep all steps.+* `llm_timeout` (default: `90`): Timeout in seconds for LLM calls+* `step_timeout` (default: `120`): Timeout in seconds for each step+* `directly_open_url` (default: `True`): If we detect a url in the task, we directly open it.++### Advanced Options++* `calculate_cost` (default: `False`): Calculate and track API costs+* `display_files_in_done_text` (default: `True`): Show file information in completion messages++### Backwards Compatibility++* `controller`: Alias for `tools` for backwards compatibility.+* `browser_session`: Alias for `browser` for backwards compatibility.+++# Agent Basics+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/agent/basics++++```python theme={null}+from browser_use import Agent, ChatOpenAI++agent = Agent(+ task="Search for latest news about AI",+ llm=ChatOpenAI(model="gpt-4.1-mini"),+)++async def main():+ history = await agent.run(max_steps=100)+```++* `task`: The task you want to automate.+* `llm`: Your favorite LLM. See <a href="/customize/supported-models">Supported Models</a>.++The agent is executed using the async `run()` method:++* `max_steps` (default: `100`): Maximum number of steps an agent can take.+++# Agent Output Format+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/agent/output-format++## Agent History++The `run()` method returns an `AgentHistoryList` object with the complete execution history:++```python theme={null}+history = await agent.run()++# Access useful information+history.urls() # List of visited URLs+history.screenshot_paths() # List of screenshot paths+history.screenshots() # List of screenshots as base64 strings+history.action_names() # Names of executed actions+history.extracted_content() # List of extracted content from all actions+history.errors() # List of errors (with None for steps without errors)+history.model_actions() # All actions with their parameters+history.model_outputs() # All model outputs from history+history.last_action() # Last action in history++# Analysis methods+history.final_result() # Get the final extracted content (last step)+history.is_done() # Check if agent completed successfully+history.is_successful() # Check if agent completed successfully (returns None if not done)+history.has_errors() # Check if any errors occurred+history.model_thoughts() # Get the agent's reasoning process (AgentBrain objects)+history.action_results() # Get all ActionResult objects from history+history.action_history() # Get truncated action history with essential fields+history.number_of_steps() # Get the number of steps in the history+history.total_duration_seconds() # Get total duration of all steps in seconds++# Structured output (when using output_model_schema)+history.structured_output # Property that returns parsed structured output+```++See all helper methods in the [AgentHistoryList source code](https://github.com/browser-use/browser-use/blob/main/browser_use/agent/views.py#L301).++## Structured Output++For structured output, use the `output_model_schema` parameter with a Pydantic model. [Example](https://github.com/browser-use/browser-use/blob/main/examples/features/custom_output.py).+++# Agent Prompting Guide+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/agent/prompting-guide++Tips and tricks++Prompting can trasticly improve performance and solve existing limitations of the library.++### 1. Be Specific vs Open-Ended++✅ Specific (Recommended)++```python theme={null}+task = """+1. Go to https://quotes.toscrape.com/+2. Use extract action with the query "first 3 quotes with their authors"+3. Save results to quotes.csv using write_file action+4. Do a google search for the first quote and find when it was written+"""+```++❌ Open-Ended++```python theme={null}+task = "Go to web and make money"+```++### 2. Name Actions Directly++When you know exactly what the agent should do, reference actions by name:++```python theme={null}+task = """+1. Use search action to find "Python tutorials"+2. Use click to open first result in a new tab+3. Use scroll action to scroll down 2 pages+4. Use extract to extract the names of the first 5 items+5. Wait for 2 seconds if the page is not loaded, refresh it and wait 10 sec+6. Use send_keys action with "Tab Tab ArrowDown Enter"+"""+```++See [Available Tools](/customize/tools/available) for the complete list of actions.++### 3. Handle interaction problems via keyboard navigation++Sometimes buttons can't be clicked (you found a bug in the library - open an issue).+Good news - often you can work around it with keyboard navigation!++```python theme={null}+task = """+If the submit button cannot be clicked:+1. Use send_keys action with "Tab Tab Enter" to navigate and activate+2. Or use send_keys with "ArrowDown ArrowDown Enter" for form submission+"""+```++### 4. Custom Actions Integration++```python theme={null}+# When you have custom actions[email protected]("Get 2FA code from authenticator app")+async def get_2fa_code():+ # Your implementation+ pass++task = """+Login with 2FA:+1. Enter username/password+2. When prompted for 2FA, use get_2fa_code action+3. NEVER try to extract 2FA codes from the page manually+4. ALWAYS use the get_2fa_code action for authentication codes+"""+```++### 5. Error Recovery++```python theme={null}+task = """+Robust data extraction:+1. Go to openai.com to find their CEO+2. If navigation fails due to anti-bot protection:+ - Use google search to find the CEO+3. If page times out, use go_back and try alternative approach+"""+```++The key to effective prompting is being specific about actions.+++# Agent Supported Models+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/agent/supported-models+LLMs supported (changes frequently, check the documentation when needed)+++# Browser All Parameters+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/browser/all-parameters++Complete reference for all browser configuration options++<Note>+ The `Browser` instance also provides all [Actor](/customize/actor/all-parameters) methods for direct browser control (page management, element interactions, etc.).+</Note>++## Core Settings++* `cdp_url`: CDP URL for connecting to existing browser instance (e.g., `"http://localhost:9222"`)++## Display & Appearance++* `headless` (default: `None`): Run browser without UI. Auto-detects based on display availability (`True`/`False`/`None`)+* `window_size`: Browser window size for headful mode. Use dict `{'width': 1920, 'height': 1080}` or `ViewportSize` object+* `window_position` (default: `{'width': 0, 'height': 0}`): Window position from top-left corner in pixels+* `viewport`: Content area size, same format as `window_size`. Use `{'width': 1280, 'height': 720}` or `ViewportSize` object+* `no_viewport` (default: `None`): Disable viewport emulation, content fits to window size+* `device_scale_factor`: Device scale factor (DPI). Set to `2.0` or `3.0` for high-resolution screenshots++## Browser Behavior++* `keep_alive` (default: `None`): Keep browser running after agent completes+* `allowed_domains`: Restrict navigation to specific domains. Domain pattern formats:+ * `'example.com'` - Matches only `https://example.com/*`+ * `'*.example.com'` - Matches `https://example.com/*` and any subdomain `https://*.example.com/*`+ * `'http*://example.com'` - Matches both `http://` and `https://` protocols+ * `'chrome-extension://*'` - Matches any Chrome extension URL+ * Security: Wildcards in TLD (e.g., `example.*`) are not allowed for security+ * Use list like `['*.google.com', 'https://example.com', 'chrome-extension://*']`+ * Performance: Lists with 100+ domains are automatically optimized to sets for O(1) lookup. Pattern matching is disabled for optimized lists. Both `www.example.com` and `example.com` variants are checked automatically.+* `prohibited_domains`: Block navigation to specific domains. Uses same pattern formats as `allowed_domains`. When both `allowed_domains` and `prohibited_domains` are set, `allowed_domains` takes precedence. Examples:+ * `['nsfw.com', '*.gambling-site.net']` - Block specific sites and all subdomains+ * `['https://explicit-content.org']` - Block specific protocol/domain combination+ * Performance: Lists with 100+ domains are automatically optimized to sets for O(1) lookup (same as `allowed_domains`)+* `enable_default_extensions` (default: `True`): Load automation extensions (uBlock Origin, cookie handlers, ClearURLs)+* `cross_origin_iframes` (default: `False`): Enable cross-origin iframe support (may cause complexity)+* `is_local` (default: `True`): Whether this is a local browser instance. Set to `False` for remote browsers. If we have a `executable_path` set, it will be automatically set to `True`. This can effect your download behavior.++## User Data & Profiles++* `user_data_dir` (default: auto-generated temp): Directory for browser profile data. Use `None` for incognito mode+* `profile_directory` (default: `'Default'`): Chrome profile subdirectory name (`'Profile 1'`, `'Work Profile'`, etc.)+* `storage_state`: Browser storage state (cookies, localStorage). Can be file path string or dict object++## Network & Security++* `proxy`: Proxy configuration using `ProxySettings(server='http://host:8080', bypass='localhost,127.0.0.1', username='user', password='pass')`+* `permissions` (default: `['clipboardReadWrite', 'notifications']`): Browser permissions to grant. Use list like `['camera', 'microphone', 'geolocation']`+* `headers`: Additional HTTP headers for connect requests (remote browsers only)++## Browser Launch++* `executable_path`: Path to browser executable for custom installations. Platform examples:+ * macOS: `'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'`+ * Windows: `'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe'`+ * Linux: `'/usr/bin/google-chrome'`+* `channel`: Browser channel (`'chromium'`, `'chrome'`, `'chrome-beta'`, `'msedge'`, etc.)+* `args`: Additional command-line arguments for the browser. Use list format: `['--disable-gpu', '--custom-flag=value', '--another-flag']`+* `env`: Environment variables for browser process. Use dict like `{'DISPLAY': ':0', 'LANG': 'en_US.UTF-8', 'CUSTOM_VAR': 'test'}`+* `chromium_sandbox` (default: `True` except in Docker): Enable Chromium sandboxing for security+* `devtools` (default: `False`): Open DevTools panel automatically (requires `headless=False`)+* `ignore_default_args`: List of default args to disable, or `True` to disable all. Use list like `['--enable-automation', '--disable-extensions']`++## Timing & Performance++* `minimum_wait_page_load_time` (default: `0.25`): Minimum time to wait before capturing page state in seconds+* `wait_for_network_idle_page_load_time` (default: `0.5`): Time to wait for network activity to cease in seconds+* `wait_between_actions` (default: `0.5`): Time to wait between agent actions in seconds++## AI Integration++* `highlight_elements` (default: `True`): Highlight interactive elements for AI vision+* `paint_order_filtering` (default: `True`): Enable paint order filtering to optimize DOM tree by removing elements hidden behind others. Slightly experimental++## Downloads & Files++* `accept_downloads` (default: `True`): Automatically accept all downloads+* `downloads_path`: Directory for downloaded files. Use string like `'./downloads'` or `Path` object+* `auto_download_pdfs` (default: `True`): Automatically download PDFs instead of viewing in browser++## Device Emulation++* `user_agent`: Custom user agent string. Example: `'Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)'`+* `screen`: Screen size information, same format as `window_size`++## Recording & Debugging++* `record_video_dir`: Directory to save video recordings as `.mp4` files+* `record_video_size` (default: `ViewportSize`): The frame size (width, height) of the video recording.+* `record_video_framerate` (default: `30`): The framerate to use for the video recording.+* `record_har_path`: Path to save network trace files as `.har` format+* `traces_dir`: Directory to save complete trace files for debugging+* `record_har_content` (default: `'embed'`): HAR content mode (`'omit'`, `'embed'`, `'attach'`)+* `record_har_mode` (default: `'full'`): HAR recording mode (`'full'`, `'minimal'`)++## Advanced Options++* `disable_security` (default: `False`): ⚠️ NOT RECOMMENDED - Disables all browser security features+* `deterministic_rendering` (default: `False`): ⚠️ NOT RECOMMENDED - Forces consistent rendering but reduces performance++*++## Browser vs BrowserSession++`Browser` is an alias for `BrowserSession` - they are exactly the same class:+Use `Browser` for cleaner, more intuitive code.+++# Browser Basics+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/browser/basics++*++```python theme={null}+from browser_use import Agent, Browser, ChatOpenAI++browser = Browser(+ headless=False, # Show browser window+ window_size={'width': 1000, 'height': 700}, # Set window size+)++agent = Agent(+ task='Search for Browser Use',+ browser=browser,+ llm=ChatOpenAI(model='gpt-4.1-mini'),+)+++async def main():+ await agent.run()+```+++# Browser: Real Browser+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/browser/real-browser+Connect your existing Chrome browser to preserve authentication.++# Browser: Remote Browser+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/browser/remote+The easiest way to use a cloud browser is with the built-in Browser-Use cloud service:+++# Lifecycle Hooks+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/hooks+Customize agent behavior with lifecycle hooks+++# MCP Server+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/mcp-server+Expose browser-use capabilities via Model Context Protocol for AI assistants like Claude Desktop+++# Tools: Add Tools+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/tools/add++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](https://github.com/browser-use/browser-use/blob/main/examples/browser/playwright_integration.py))+* ...++Simply add `@tools.action(...)` to your function.++```python theme={null}+from browser_use import Tools, Agent++tools = Tools()+[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}'+```++```python theme={null}+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.+++# Tools: Available Tools+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/tools/available+Here is the [source code](https://github.com/browser-use/browser-use/blob/main/browser_use/tools/service.py) for the default tools:++### Navigation & Browser Control++* `search` - Search queries (DuckDuckGo, Google, Bing)+* `navigate` - Navigate to URLs+* `go_back` - Go back in browser history+* `wait` - Wait for specified seconds++### Page Interaction++* `click` - Click elements by their index+* `input` - Input text into form fields+* `upload_file` - Upload files to file inputs+* `scroll` - Scroll the page up/down+* `find_text` - Scroll to specific text on page+* `send_keys` - Send special keys (Enter, Escape, etc.)++### JavaScript Execution++* `evaluate` - Execute custom JavaScript code on the page (for advanced interactions, shadow DOM, custom selectors, data extraction)++### Tab Management++* `switch` - Switch between browser tabs+* `close` - Close browser tabs++### Content Extraction++* `extract` - Extract data from webpages using LLM++### Visual Analysis++* `screenshot` - Request a screenshot in your next browser state for visual confirmation++### Form Controls++* `dropdown_options` - Get dropdown option values+* `select_dropdown` - Select dropdown options++### File Operations++* `write_file` - Write content to files+* `read_file` - Read file contents+* `replace_file` - Replace text in files++### Task Completion++* `done` - Complete the task (always available)++++# Tools: Basics+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/tools/basics+Tools are the functions that the agent has to interact with the world.++## Quick Example++```python theme={null}+from browser_use import Tools, ActionResult, Browser++tools = Tools()+[email protected]('Ask human for help with a question')+def ask_human(question: str, browser: Browser) -> ActionResult:+ answer = input(f'{question} > ')+ return f'The human responded with: {answer}'++agent = Agent(+ task='Ask human for help',+ llm=llm,+ tools=tools,+)+```++<Note>+ Use `browser` parameter in tools for deterministic [Actor](/customize/actor/basics) actions.+</Note>+++# Tools: Remove Tools+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/tools/remove++You can exclude default tools:++```python theme={null}+from browser_use import Tools++tools = Tools(exclude_actions=['search', 'wait'])+agent = Agent(task='...', llm=llm, tools=tools)+```+++# Tools: Tool Response+Source: (go to or request this content to learn more) https://docs.browser-use.com/customize/tools/response+Tools return results using `ActionResult` or simple strings.++## Return Types++```python theme={null}[email protected]('My tool')+def my_tool() -> str:+ return "Task completed successfully"+[email protected]('Advanced tool')+def advanced_tool() -> ActionResult:+ return ActionResult(+ extracted_content="Main result",+ long_term_memory="Remember this info",+ error="Something went wrong",+ is_done=True,+ success=True,+ attachments=["file.pdf"],+ )+```++# Get Help+Source: (go to or request this content to learn more) https://docs.browser-use.com/development/get-help++More than 20k developers help each other++1. Check our [GitHub Issues](https://github.com/browser-use/browser-use/issues)+2. Ask in our [Discord community](https://link.browser-use.com/discord)+3. Get support for your enterprise with [[email protected]](mailto:[email protected])+++# Costs+Source: (go to or request this content to learn more) https://docs.browser-use.com/development/monitoring/costs+Track token usage and API costs for your browser automation tasks++## Cost Tracking++To track token usage and costs, enable cost calculation:++```python theme={null}+from browser_use import Agent, ChatOpenAI++agent = Agent(+ task="Search for latest news about AI",+ llm=ChatOpenAI(model="gpt-4.1-mini"),+ calculate_cost=True # Enable cost tracking+)++history = await agent.run()++# Get usage from history+print(f"Token usage: {history.usage}")++# Or get from usage summary+usage_summary = await agent.token_cost_service.get_usage_summary()+print(f"Usage summary: {usage_summary}")+```+++# Observability+Source: (go to or request this content to learn more) https://docs.browser-use.com/development/monitoring/observability+Trace Browser Use's agent execution steps and browser sessions+Browser Use has a native integration with [Laminar](https://lmnr.ai) - open-source platform for tracing, evals and labeling of AI agents.+Read more about Laminar in the [Laminar docs](https://docs.lmnr.ai).+++# Telemetry+Source: (go to or request this content to learn more) https://docs.browser-use.com/development/monitoring/telemetry++Understanding Browser Use's telemetry++## Overview++Browser Use is free under the MIT license. To help us continue improving the library, we collect anonymous usage data with [PostHog](https://posthog.com) . This information helps us understand how the library is used, fix bugs more quickly, and prioritize new features.++## Opting Out++You can disable telemetry by setting the environment variable:++```bash .env theme={null}+ANONYMIZED_TELEMETRY=false+```++Or in your Python code:++```python theme={null}+import os+os.environ["ANONYMIZED_TELEMETRY"] = "false"+```++<Note>+ Even when enabled, telemetry has zero impact on the library's performance. Code is available in [Telemetry+ Service](https://github.com/browser-use/browser-use/tree/main/browser_use/telemetry).+</Note>+++# Contribution Guide+Source: (go to or request this content to learn more) https://docs.browser-use.com/development/setup/contribution-guide++## Mission++* Make developers happy+* Do more clicks than human+* Tell your computer what to do, and it gets it done.+* Make agents faster and more reliable.++## What to work on?++* This space is moving fast. We have 10 ideas daily. Let's exchange some.+* Browse our [GitHub Issues](https://github.com/browser-use/browser-use/issues)+* Check out our most active issues on [Discord](https://discord.gg/zXJJHtJf3k)+* Get inspiration in [`#showcase-your-work`](https://discord.com/channels/1303749220842340412/1305549200678850642) channel++## What makes a great PR?++1. Why do we need this PR?+2. Include a demo screenshot/gif+3. Make sure the PR passes all CI tests+4. Keep your PR focused on a single feature++## How?++1. Fork the repository+2. Create a new branch for your feature+3. Submit a PR++We are overwhelmed with Issues. Feel free to bump your issues/PRs with comments periodically if you need faster feedback.+++# Local Setup+Source: (go to or request this content to learn more) https://docs.browser-use.com/development/setup/local-setup++We're excited to have you join our community of contributors.+## Welcome to Browser Use Development!++```bash theme={null}+git clone https://github.com/browser-use/browser-use+cd browser-use+uv sync --all-extras --dev+# or pip install -U git+https://github.com/browser-use/browser-use.git@main+```++## Configuration+Set up your environment variables:++```bash theme={null}+# Copy the example environment file+cp .env.example .env++# set logging level+# BROWSER_USE_LOGGING_LEVEL=debug+```++## Helper Scripts++For common development tasks++```bash theme={null}+# Complete setup script - installs uv, creates a venv, and installs dependencies+./bin/setup.sh++# Run all pre-commit hooks (formatting, linting, type checking)+./bin/lint.sh++# Run the core test suite that's executed in CI+./bin/test.sh+```++## Run examples++```bash theme={null}+uv run examples/simple.py+```++++# Example Code: News-Use (News Monitor)+Source: (go to or request this content to learn more) https://docs.browser-use.com/examples/apps/news-use+Monitor news websites and extract articles with sentiment analysis using browser agents and Google Gemini.+++# Example Code:Vibetest-Use (Automated QA)+Source: (go to or request this content to learn more) https://docs.browser-use.com/examples/apps/vibetest-use+Run multi-agent Browser-Use tests to catch UI bugs, broken links, and accessibility issues before they ship.+++# Fast Agent+Source: (go to or request this content to learn more) https://docs.browser-use.com/examples/templates/fast-agent+Optimize agent performance for maximum speed and efficiency.+++# Follow up tasks+Source: (go to or request this content to learn more) https://docs.browser-use.com/examples/templates/follow-up-tasks+Follow up tasks with the same browser session.+++# Parallel Agents+Source: (go to or request this content to learn more) https://docs.browser-use.com/examples/templates/parallel-browser+Run multiple agents in parallel with separate browser instances+++# Playwright Integration+Source: (go to or request this content to learn more) https://docs.browser-use.com/examples/templates/playwright-integration+Advanced example showing Playwright and Browser-Use working together+++# Guide: Secure Setup+Source: (go to or request this content to learn more) https://docs.browser-use.com/examples/templates/secure+++# Guide: Sensitive Data+Source: (go to or request this content to learn more) https://docs.browser-use.com/examples/templates/sensitive-data+Handle secret information securely and avoid sending PII & passwords to the LLM.+</browser_use_docs>