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
Update Tool imports in docs, readme, and docstrings
Magnus Müller13dd73b23a23
diff --git a/.cursor/rules/browser-use-rules.mdc b/.cursor/rules/browser-use-rules.mdcindex 86552b8fc..5850ce6f5 100644--- a/.cursor/rules/browser-use-rules.mdc+++ b/.cursor/rules/browser-use-rules.mdc@@ -54,9 +54,9 @@ To add a new action that your browser agent can execute:```pythonfrom playwright.async_api import Page-from browser_use.core.controller import Controller, ActionResult+from browser_use.core.controller import Tools, ActionResult-controller = Controller()+controller = Tools()@controller.registry.action("Search the web for a specific query")async def search_web(query: str, page: Page):diff --git a/.github/ISSUE_TEMPLATE/1_element_detection_bug.yml b/.github/ISSUE_TEMPLATE/1_element_detection_bug.ymlindex 80fbe6035..2ff1cefab 100644--- a/.github/ISSUE_TEMPLATE/1_element_detection_bug.yml+++ b/.github/ISSUE_TEMPLATE/1_element_detection_bug.yml@@ -111,7 +111,7 @@ body:placeholder: |from dotenv import load_dotenvload_dotenv() # tip: always load_dotenv() before other imports- from browser_use import Agent, BrowserSession, Controller+ from browser_use import Agent, BrowserSession, Toolsfrom browser_use.llm import ChatOpenAIagent = Agent(diff --git a/.github/ISSUE_TEMPLATE/2_bug_report.yml b/.github/ISSUE_TEMPLATE/2_bug_report.ymlindex 39bbc9b2c..da424def9 100644--- a/.github/ISSUE_TEMPLATE/2_bug_report.yml+++ b/.github/ISSUE_TEMPLATE/2_bug_report.yml@@ -53,7 +53,7 @@ body:placeholder: |from dotenv import load_dotenvload_dotenv() # tip: always load_dotenv() before other imports- from browser_use import Agent, BrowserSession, Controller+ from browser_use import Agent, BrowserSession, Toolsfrom browser_use.llm import ChatOpenAIagent = Agent(diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yamlindex 5f1d707b9..42455bf36 100644--- a/.github/workflows/package.yaml+++ b/.github/workflows/package.yaml@@ -53,4 +53,4 @@ jobs:source /tmp/testenv/bin/activatefiuv pip install *.whl- python -c 'from browser_use import Agent, BrowserProfile, BrowserSession, Controller, ActionModel, ActionResult'+ python -c 'from browser_use import Agent, BrowserProfile, BrowserSession, Tools, ActionModel, ActionResult'diff --git a/README.md b/README.mdindex f0314e8a3..2db9f0233 100644--- a/README.md+++ b/README.md@@ -125,12 +125,12 @@ Browser-use agents can connect to multiple external MCP servers to extend their```pythonimport asyncio-from browser_use import Agent, Controller, ChatOpenAI+from browser_use import Agent, Tools, ChatOpenAIfrom browser_use.mcp.client import MCPClientasync def main():# Initialize controller- controller = Controller()+ controller = Tools()# Connect to multiple MCP serversfilesystem_client = MCPClient(@@ -157,7 +157,7 @@ async def main():agent = Agent(task="Find the latest pdf report in my documents and create a GitHub issue about it",llm=ChatOpenAI(model="gpt-4.1-mini"),- controller=controller # Controller has tools from both MCP servers+ controller=controller # Tools has tools from both MCP servers)# Run the agentdiff --git a/browser_use/__init__.py b/browser_use/__init__.pyindex 65825d618..934b765ce 100644--- a/browser_use/__init__.py+++ b/browser_use/__init__.py@@ -74,8 +74,8 @@ _LAZY_IMPORTS = {'BrowserSession': ('browser_use.browser', 'BrowserSession'),'Browser': ('browser_use.browser', 'BrowserSession'), # Alias for BrowserSession'BrowserProfile': ('browser_use.browser', 'BrowserProfile'),- # Controller (moderate weight)- 'Controller': ('browser_use.tools.service', 'Controller'),+ # Tools (moderate weight)+ 'Tools': ('browser_use.tools.service', 'Tools'),# DOM service (moderate weight)'DomService': ('browser_use.dom.service', 'DomService'),# Chat models (very heavy imports)diff --git a/browser_use/browser/events.py b/browser_use/browser/events.pyindex c84f6518d..24c80aee5 100644--- a/browser_use/browser/events.py+++ b/browser_use/browser/events.py@@ -12,7 +12,7 @@ from browser_use.browser.views import BrowserStateSummaryfrom browser_use.dom.views import EnhancedDOMTreeNode# ============================================================================-# Agent/Controller -> BrowserSession Events (High-level browser actions)+# Agent/Tools -> BrowserSession Events (High-level browser actions)# ============================================================================diff --git a/browser_use/integrations/gmail/__init__.py b/browser_use/integrations/gmail/__init__.pyindex e963b4227..3b8bda183 100644--- a/browser_use/integrations/gmail/__init__.py+++ b/browser_use/integrations/gmail/__init__.py@@ -5,10 +5,10 @@ This integration enables agents to read email content and extract verification cUsage:from browser_use.integrations.gmail import GmailService, register_gmail_actions# Option 1: Register Gmail actions with file-based authentication- controller = Controller()+ controller = Tools()register_gmail_actions(controller)# Option 2: Register Gmail actions with direct access token (recommended for production)- controller = Controller()+ controller = Tools()register_gmail_actions(controller, access_token="your_access_token_here")# Option 3: Use the service directlygmail = GmailService(access_token="your_access_token_here")diff --git a/browser_use/mcp/client.py b/browser_use/mcp/client.pyindex 3f282cddc..3da6984a9 100644--- a/browser_use/mcp/client.py+++ b/browser_use/mcp/client.py@@ -4,10 +4,10 @@ This module provides integration between external MCP servers and browser-use'sMCP tools are dynamically discovered and registered as browser-use actions.Example usage:- from browser_use import Controller+ from browser_use import Toolsfrom browser_use.mcp.client import MCPClient- controller = Controller()+ controller = Tools()# Connect to an MCP servermcp_client = MCPClient(diff --git a/browser_use/mcp/controller.py b/browser_use/mcp/controller.pyindex 17ffa11e8..6b792719c 100644--- a/browser_use/mcp/controller.py+++ b/browser_use/mcp/controller.py@@ -248,10 +248,10 @@ async def register_mcp_tools(registry: Registry, mcp_command: str, mcp_args: lisExample:```python- from browser_use import Controller+ from browser_use import Toolsfrom browser_use.mcp.controller import register_mcp_tools- controller = Controller()+ controller = Tools()# Register Playwright MCP toolsmcp = await register_mcp_tools(controller.registry, 'npx', ['@playwright/mcp@latest', '--headless'])diff --git a/browser_use/mcp/server.py b/browser_use/mcp/server.pyindex 23865c04c..0af805751 100644--- a/browser_use/mcp/server.py+++ b/browser_use/mcp/server.py@@ -711,7 +711,7 @@ class BrowserUseServer:return 'Error: No browser session active'if not self.controller:- return 'Error: Controller not initialized'+ return 'Error: Tools not initialized'state = await self.browser_session.get_browser_state_summary()diff --git a/docs/customize/hooks.mdx b/docs/customize/hooks.mdxindex ede04c056..0b9260f25 100644--- a/docs/customize/hooks.mdx+++ b/docs/customize/hooks.mdx@@ -83,7 +83,7 @@ await agent.run(When working with agent hooks, you have access to the entire `Agent` instance. Here are some useful data points you can access:- `agent.task` lets you see what the main task is, `agent.add_new_task(...)` lets you queue up a new one-- `agent.controller` give access to the `Controller()` object and `Registry()` containing the available actions+- `agent.controller` give access to the `Tools()` object and `Registry()` containing the available actions- `agent.controller.registry.execute_action('click_element_by_index', {'index': 123}, browser_session=agent.browser_session)`- `agent.context` lets you access any user-provided context object passed in to `Agent(context=...)`- `agent.sensitive_data` contains the sensitive data dict, which can be updated in-place to add/remove/modify itemsdiff --git a/docs/customize/mcp-client.mdx b/docs/customize/mcp-client.mdxindex 976ec1df7..2710e3e96 100644--- a/docs/customize/mcp-client.mdx+++ b/docs/customize/mcp-client.mdx@@ -25,11 +25,11 @@ uv pip install "browser-use[cli]"```pythonimport os-from browser_use import Agent, Controller+from browser_use import Agent, Toolsfrom browser_use.mcp.client import MCPClient# Create controller-controller = Controller()+controller = Tools()# Connect to MCP servermcp_client = MCPClient(diff --git a/docs/customize/mcp-server.mdx b/docs/customize/mcp-server.mdxindex 5bcdbd5a0..0f2a2a9c4 100644--- a/docs/customize/mcp-server.mdx+++ b/docs/customize/mcp-server.mdx@@ -19,7 +19,7 @@ The MCP server acts as a bridge between MCP-compatible AI assistants and browsergraph LRA[Claude Desktop] -->|MCP Protocol| B[Browser-use MCP Server]B --> C[Browser]- B --> D[Controller]+ B --> D[Tools]B --> E[FileSystem]C --> F[Playwright Browser]diff --git a/docs/customize/tools/add.mdx b/docs/customize/tools/add.mdxindex 1db955a50..0a038dfee 100644--- a/docs/customize/tools/add.mdx+++ b/docs/customize/tools/add.mdx@@ -20,9 +20,9 @@ Examples:Simply add `@controller.action(...)` to your function.```python-from browser_use import Controller, Agent+from browser_use import Tools, Agent-controller = Controller()+controller = Tools()@controller.action(description='Ask human for help with a question')def ask_human(question: str) -> ActionResult:diff --git a/docs/customize/tools/basics.mdx b/docs/customize/tools/basics.mdxindex 21c9d4bcf..e7edf7ac7 100644--- a/docs/customize/tools/basics.mdx+++ b/docs/customize/tools/basics.mdx@@ -10,9 +10,9 @@ mode: "wide"```python-from browser_use import Controller, ActionResult+from browser_use import Tools, ActionResult-controller = Controller()+controller = Tools()@controller.action('Ask human for help with a question')def ask_human(question: str) -> ActionResult:diff --git a/docs/customize/tools/remove.mdx b/docs/customize/tools/remove.mdxindex 916eef150..98a59611a 100644--- a/docs/customize/tools/remove.mdx+++ b/docs/customize/tools/remove.mdx@@ -7,9 +7,9 @@ mode: "wide"```python-from browser_use import Controller+from browser_use import Tools-controller = Controller(exclude_actions=['search_google', 'wait'])+controller = Tools(exclude_actions=['search_google', 'wait'])agent = Agent(task='...', llm=llm, controller=controller)```diff --git a/tests/ci/test_browser_event_ClickElementEvent.py b/tests/ci/test_browser_event_ClickElementEvent.pyindex aecb3a2d8..e95b3a5f4 100644--- a/tests/ci/test_browser_event_ClickElementEvent.py+++ b/tests/ci/test_browser_event_ClickElementEvent.py@@ -65,7 +65,7 @@ async def browser_session():@pytest.fixture(scope='function')def controller():- """Create and provide a Controller instance."""+ """Create and provide a Tools instance."""return Tools()diff --git a/tests/ci/test_browser_event_GetDropdownOptionsEvent.py b/tests/ci/test_browser_event_GetDropdownOptionsEvent.pyindex 49aa347bc..124874320 100644--- a/tests/ci/test_browser_event_GetDropdownOptionsEvent.py+++ b/tests/ci/test_browser_event_GetDropdownOptionsEvent.py@@ -267,7 +267,7 @@ async def browser_session():@pytest.fixture(scope='function')def controller():- """Create and provide a Controller instance."""+ """Create and provide a Tools instance."""return Tools()diff --git a/tests/ci/test_browser_event_GetDropdownOptionsEvent_aria_menus.py b/tests/ci/test_browser_event_GetDropdownOptionsEvent_aria_menus.pyindex c2334731a..bc84beb1a 100644--- a/tests/ci/test_browser_event_GetDropdownOptionsEvent_aria_menus.py+++ b/tests/ci/test_browser_event_GetDropdownOptionsEvent_aria_menus.py@@ -141,7 +141,7 @@ async def browser_session():@pytest.fixture(scope='function')def controller():- """Create and provide a Controller instance."""+ """Create and provide a Tools instance."""return Tools()diff --git a/tests/ci/test_browser_event_NavigateToUrlEvent.py b/tests/ci/test_browser_event_NavigateToUrlEvent.pyindex b4f410d67..dd97952e9 100644--- a/tests/ci/test_browser_event_NavigateToUrlEvent.py+++ b/tests/ci/test_browser_event_NavigateToUrlEvent.py@@ -54,7 +54,7 @@ async def browser_session():@pytest.fixturedef controller():- """Create and provide a Controller instance."""+ """Create and provide a Tools instance."""return Tools()diff --git a/tests/ci/test_browser_event_ScrollEvent.py b/tests/ci/test_browser_event_ScrollEvent.pyindex 292b2594a..23c886ba1 100644--- a/tests/ci/test_browser_event_ScrollEvent.py+++ b/tests/ci/test_browser_event_ScrollEvent.py@@ -72,7 +72,7 @@ async def browser_session():@pytest.fixturedef controller():- """Create and provide a Controller instance."""+ """Create and provide a Tools instance."""return Tools()diff --git a/tests/ci/test_browser_event_TypeTextEvent.py b/tests/ci/test_browser_event_TypeTextEvent.pyindex df822f9bd..fa3a952d6 100644--- a/tests/ci/test_browser_event_TypeTextEvent.py+++ b/tests/ci/test_browser_event_TypeTextEvent.py@@ -69,7 +69,7 @@ async def browser_session():@pytest.fixturedef controller():- """Create and provide a Controller instance."""+ """Create and provide a Tools instance."""return Tools()diff --git a/tests/ci/test_browser_event_TypeTextEvent2.py b/tests/ci/test_browser_event_TypeTextEvent2.pyindex df822f9bd..fa3a952d6 100644--- a/tests/ci/test_browser_event_TypeTextEvent2.py+++ b/tests/ci/test_browser_event_TypeTextEvent2.py@@ -69,7 +69,7 @@ async def browser_session():@pytest.fixturedef controller():- """Create and provide a Controller instance."""+ """Create and provide a Tools instance."""return Tools()diff --git a/tests/ci/test_browser_session_tab_management.py b/tests/ci/test_browser_session_tab_management.pyindex a03385b4e..e7c45545a 100644--- a/tests/ci/test_browser_session_tab_management.py+++ b/tests/ci/test_browser_session_tab_management.py@@ -85,7 +85,7 @@ async def browser_session(base_url):@pytest.fixture(scope='module')def controller():- """Create and provide a Controller instance."""+ """Create and provide a Tools instance."""return Tools()diff --git a/tests/ci/test_controller.py b/tests/ci/test_controller.pyindex 51e571fbb..36fe55c72 100644--- a/tests/ci/test_controller.py+++ b/tests/ci/test_controller.py@@ -86,12 +86,12 @@ async def browser_session():@pytest.fixture(scope='function')def controller():- """Create and provide a Controller instance."""+ """Create and provide a Tools instance."""return Tools()-class TestControllerIntegration:- """Integration tests for Controller using actual browser instances."""+class TestToolsIntegration:+ """Integration tests for Tools using actual browser instances."""async def test_registry_actions(self, controller, browser_session):"""Test that the registry contains the expected default actions."""diff --git a/tests/ci/test_mcp_server.py b/tests/ci/test_mcp_server.pyindex 3e7aedd1a..5db3270b4 100644--- a/tests/ci/test_mcp_server.py+++ b/tests/ci/test_mcp_server.py@@ -590,7 +590,7 @@ class TestMCPServerExtraction:server.controller = Noneresult = await server._extract_content('query')- assert result == 'Error: Controller not initialized'+ assert result == 'Error: Tools not initialized'async def test_extract_content_no_session(self):"""Test extraction without browser session."""diff --git a/tests/ci/test_registry.py b/tests/ci/test_registry.pyindex 81ff98376..43feab36a 100644--- a/tests/ci/test_registry.py+++ b/tests/ci/test_registry.py@@ -504,7 +504,7 @@ class TestRegistryEdgeCases:assert 'Should execute: test' in result.extracted_content-class TestExistingControllerActions:+class TestExistingToolsActions:"""Test that existing controller actions continue to work"""async def test_existing_action_models(self, registry, browser_session):@@ -665,7 +665,7 @@ class TestType2Pattern:assert len(fields) == 0 or all(f in ['title'] for f in fields)def test_no_special_params_action(self):- """Test action with no special params (like wait action in Controller)"""+ """Test action with no special params (like wait action in Tools)"""registry = Registry()@registry.action('Wait for x seconds default 3')diff --git a/tests/old/test_google_sheets_real.py b/tests/old/test_google_sheets_real.pyindex f164b531c..7733e0631 100644--- a/tests/old/test_google_sheets_real.py+++ b/tests/old/test_google_sheets_real.py@@ -10,7 +10,7 @@ import osimport pytestfrom browser_use.browser import BrowserProfile, BrowserSession-from browser_use.tools.service import Controller+from browser_use.tools.service import Tools# Test Google Sheets URL (public read-only spreadsheet for testing)TEST_GOOGLE_SHEET_URL = 'https://docs.google.com/spreadsheets/d/1INaIcfpYXlMRWO__de61SHFCaqt1lfHlcvtXZPItlpI/edit'@@ -33,7 +33,7 @@ async def browser_session():@pytest.fixturedef controller():"""Create a controller instance (Google Sheets actions are already registered)."""- return Controller()+ return Tools()@pytest.mark.asynciodiff --git a/tests/old/test_self_registered_actions.py b/tests/old/test_self_registered_actions.pyindex 4065e9123..09cb88907 100644--- a/tests/old/test_self_registered_actions.py+++ b/tests/old/test_self_registered_actions.py@@ -5,7 +5,7 @@ from browser_use.agent.service import Agentfrom browser_use.agent.views import AgentHistoryListfrom browser_use.browser import BrowserProfile, BrowserSessionfrom browser_use.llm import ChatAzureOpenAI-from browser_use.tools.service import Controller+from browser_use.tools.service import Tools@pytest.fixture@@ -23,7 +23,7 @@ async def browser_session():@pytest.fixtureasync def controller():"""Initialize the controller with self-registered actions"""- controller = Controller()+ controller = Tools()# Define custom actions without Pydantic models@controller.action('Print a message')diff --git a/tests/old/test_vision.py b/tests/old/test_vision.pyindex 346b78301..73c5d68b0 100644--- a/tests/old/test_vision.py+++ b/tests/old/test_vision.py@@ -13,11 +13,11 @@ import pytestsys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))-from browser_use import Agent, AgentHistoryList, BrowserSession, Controller+from browser_use import Agent, AgentHistoryList, BrowserSession, Toolsfrom browser_use.llm import ChatOpenAIllm = ChatOpenAI(model='gpt-4.1')-controller = Controller()+controller = Tools()# use this test to ask the model questions about the page like# which color do you see for bbox labels, list all with their labeldiff --git a/tests/old/test_wait_for_element.py b/tests/old/test_wait_for_element.pyindex f573e81d8..98a06f552 100644--- a/tests/old/test_wait_for_element.py+++ b/tests/old/test_wait_for_element.py@@ -12,7 +12,7 @@ import pytestfrom dotenv import load_dotenv# Third-party imports-from browser_use import Agent, Controller+from browser_use import Agent, Tools# Local importsfrom browser_use.browser import BrowserProfile, BrowserSession@@ -22,7 +22,7 @@ load_dotenv()# Initialize language model and controller.llm = ChatOpenAI(model='gpt-4.1')-controller = Controller()+controller = Tools()@pytest.mark.skip(reason='this is for local testing only')diff --git a/tests/scripts/debug_iframe_scrolling.py b/tests/scripts/debug_iframe_scrolling.pyindex 7772f44fe..245d072f8 100644--- a/tests/scripts/debug_iframe_scrolling.py+++ b/tests/scripts/debug_iframe_scrolling.py@@ -173,9 +173,9 @@ async def debug_iframe_scrolling():print('=' * 80)# Navigate to the page first- from browser_use.tools.service import Controller+ from browser_use.tools.service import Tools- controller = Controller()+ controller = Tools()# Create the action model for navigationgoto_action = ActionModel.model_validate_json(actions[0])