Skip to content

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

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.mdc
index 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:
```python
from 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.yml
index 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_dotenv
load_dotenv() # tip: always load_dotenv() before other imports
- from browser_use import Agent, BrowserSession, Controller
+ from browser_use import Agent, BrowserSession, Tools
from browser_use.llm import ChatOpenAI
agent = Agent(
diff --git a/.github/ISSUE_TEMPLATE/2_bug_report.yml b/.github/ISSUE_TEMPLATE/2_bug_report.yml
index 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_dotenv
load_dotenv() # tip: always load_dotenv() before other imports
- from browser_use import Agent, BrowserSession, Controller
+ from browser_use import Agent, BrowserSession, Tools
from browser_use.llm import ChatOpenAI
agent = Agent(
diff --git a/.github/workflows/package.yaml b/.github/workflows/package.yaml
index 5f1d707b9..42455bf36 100644
--- a/.github/workflows/package.yaml
+++ b/.github/workflows/package.yaml
@@ -53,4 +53,4 @@ jobs:
source /tmp/testenv/bin/activate
fi
uv 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.md
index 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
```python
import asyncio
-from browser_use import Agent, Controller, ChatOpenAI
+from browser_use import Agent, Tools, ChatOpenAI
from browser_use.mcp.client import MCPClient
async def main():
# Initialize controller
- controller = Controller()
+ controller = Tools()
# Connect to multiple MCP servers
filesystem_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 agent
diff --git a/browser_use/__init__.py b/browser_use/__init__.py
index 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.py
index 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 BrowserStateSummary
from 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__.py
index 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 c
Usage:
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 directly
gmail = GmailService(access_token="your_access_token_here")
diff --git a/browser_use/mcp/client.py b/browser_use/mcp/client.py
index 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's
MCP tools are dynamically discovered and registered as browser-use actions.
Example usage:
- from browser_use import Controller
+ from browser_use import Tools
from browser_use.mcp.client import MCPClient
- controller = Controller()
+ controller = Tools()
# Connect to an MCP server
mcp_client = MCPClient(
diff --git a/browser_use/mcp/controller.py b/browser_use/mcp/controller.py
index 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: lis
Example:
```python
- from browser_use import Controller
+ from browser_use import Tools
from browser_use.mcp.controller import register_mcp_tools
- controller = Controller()
+ controller = Tools()
# Register Playwright MCP tools
mcp = await register_mcp_tools(controller.registry, 'npx', ['@playwright/mcp@latest', '--headless'])
diff --git a/browser_use/mcp/server.py b/browser_use/mcp/server.py
index 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.mdx
index 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 items
diff --git a/docs/customize/mcp-client.mdx b/docs/customize/mcp-client.mdx
index 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]"
```python
import os
-from browser_use import Agent, Controller
+from browser_use import Agent, Tools
from browser_use.mcp.client import MCPClient
# Create controller
-controller = Controller()
+controller = Tools()
# Connect to MCP server
mcp_client = MCPClient(
diff --git a/docs/customize/mcp-server.mdx b/docs/customize/mcp-server.mdx
index 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 browser
graph LR
A[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.mdx
index 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.mdx
index 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.mdx
index 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.py
index 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.py
index 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.py
index 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.py
index 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.fixture
def 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.py
index 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.fixture
def 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.py
index 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.fixture
def 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.py
index 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.fixture
def 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.py
index 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.py
index 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.py
index 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 = None
result = 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.py
index 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.py
index f164b531c..7733e0631 100644
--- a/tests/old/test_google_sheets_real.py
+++ b/tests/old/test_google_sheets_real.py
@@ -10,7 +10,7 @@ import os
import pytest
from 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.fixture
def controller():
"""Create a controller instance (Google Sheets actions are already registered)."""
- return Controller()
+ return Tools()
@pytest.mark.asyncio
diff --git a/tests/old/test_self_registered_actions.py b/tests/old/test_self_registered_actions.py
index 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 Agent
from browser_use.agent.views import AgentHistoryList
from browser_use.browser import BrowserProfile, BrowserSession
from 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.fixture
async 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.py
index 346b78301..73c5d68b0 100644
--- a/tests/old/test_vision.py
+++ b/tests/old/test_vision.py
@@ -13,11 +13,11 @@ import pytest
sys.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, Tools
from browser_use.llm import ChatOpenAI
llm = 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 label
diff --git a/tests/old/test_wait_for_element.py b/tests/old/test_wait_for_element.py
index f573e81d8..98a06f552 100644
--- a/tests/old/test_wait_for_element.py
+++ b/tests/old/test_wait_for_element.py
@@ -12,7 +12,7 @@ import pytest
from dotenv import load_dotenv
# Third-party imports
-from browser_use import Agent, Controller
+from browser_use import Agent, Tools
# Local imports
from 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.py
index 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 navigation
goto_action = ActionModel.model_validate_json(actions[0])