Skip to content

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

Agent service update tools with backward compatible

Magnus Müllerdbfaffa8d143
diff --git a/.cursor/rules/browser-use-rules.mdc b/.cursor/rules/browser-use-rules.mdc
index 5850ce6f5..eac6ccc7b 100644
--- a/.cursor/rules/browser-use-rules.mdc
+++ b/.cursor/rules/browser-use-rules.mdc
@@ -41,7 +41,7 @@ uv sync
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 controller I/O. This ensures robust validation and LLM-call integrity.
+ 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.
@@ -54,11 +54,11 @@ To add a new action that your browser agent can execute:
```python
from playwright.async_api import Page
-from browser_use.core.controller import Tools, ActionResult
+from browser_use.core.tools import Tools, ActionResult
-controller = Tools()
+tools = Tools()
[email protected]("Search the web for a specific query")
[email protected]("Search the web for a specific query")
async def search_web(query: str, page: Page):
# Implement your logic here, e.g., query a search engine and return results
result = ...
@@ -82,7 +82,7 @@ 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, controller=controller)
+agent = Agent(task=task, llm=model, tools=tools)
history = await agent.run()
```
diff --git a/.github/ISSUE_TEMPLATE/3_feature_request.yml b/.github/ISSUE_TEMPLATE/3_feature_request.yml
index f84e65e74..07888ce25 100644
--- a/.github/ISSUE_TEMPLATE/3_feature_request.yml
+++ b/.github/ISSUE_TEMPLATE/3_feature_request.yml
@@ -36,7 +36,7 @@ body:
A description of any troubleshooting, alternative approaches, workarounds, or other ideas you've considered to fix the problem.
placeholder: |
e.g. I tried upgrading to the latest version and telling it to hover in the prompt. I also tried
- telling the agent to ask for human help (using a custom controller action) when it gets to this
+ telling the agent to ask for human help (using a custom tools action) when it gets to this
step, then I manually click a browser extension in the navbar that automates the mouse movevement.
validations:
required: false
diff --git a/README.md b/README.md
index 2db9f0233..059641907 100644
--- a/README.md
+++ b/README.md
@@ -129,8 +129,8 @@ from browser_use import Agent, Tools, ChatOpenAI
from browser_use.mcp.client import MCPClient
async def main():
- # Initialize controller
- controller = Tools()
+ # Initialize tools
+ tools = Tools()
# Connect to multiple MCP servers
filesystem_client = MCPClient(
@@ -148,16 +148,16 @@ async def main():
# Connect and register tools from both servers
await filesystem_client.connect()
- await filesystem_client.register_to_controller(controller)
+ await filesystem_client.register_to_tools(tools)
await github_client.connect()
- await github_client.register_to_controller(controller)
+ await github_client.register_to_tools(tools)
- # Create agent with MCP-enabled controller
+ # Create agent with MCP-enabled tools
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 # Tools has tools from both MCP servers
+ tools=tools # Tools has tools from both MCP servers
)
# Run the agent
diff --git a/browser_use/agent/service.py b/browser_use/agent/service.py
index 5fd57c313..984c3b13f 100644
--- a/browser_use/agent/service.py
+++ b/browser_use/agent/service.py
@@ -136,7 +136,8 @@ class Agent(Generic[Context, AgentStructuredOutput]):
browser_profile: BrowserProfile | None = None,
browser_session: BrowserSession | None = None,
browser: Browser | None = None, # Alias for browser_session (cleaner naming)
- controller: Tools[Context] | None = None,
+ tools: Tools[Context] | None = None,
+ controller: Tools[Context] | None = None, # alias for tools for backwards compatibility
# Initial agent run parameters
sensitive_data: dict[str, str | dict[str, str]] | None = None,
initial_actions: list[dict[str, dict[str, Any]]] | None = None,
@@ -238,12 +239,17 @@ class Agent(Generic[Context, AgentStructuredOutput]):
self.llm = llm
self.preload = preload
self.include_recent_events = include_recent_events
- self.controller = controller if controller is not None else Tools(display_files_in_done_text=display_files_in_done_text)
+ if tools is not None:
+ self.tools = tools
+ elif controller is not None:
+ self.tools = controller
+ else:
+ self.tools = Tools(display_files_in_done_text=display_files_in_done_text)
# Structured output
self.output_model_schema = output_model_schema
if self.output_model_schema is not None:
- self.controller.use_structured_output_action(self.output_model_schema)
+ self.tools.use_structured_output_action(self.output_model_schema)
self.sensitive_data = sensitive_data
@@ -328,7 +334,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
# Initialize available actions for system prompt (only non-filtered actions)
# These will be used for the system prompt to maintain caching
- self.unfiltered_actions = self.controller.registry.get_prompt_description()
+ self.unfiltered_actions = self.tools.registry.get_prompt_description()
# Initialize message manager with state
# Initial system prompt with all actions - will be updated during each step
@@ -616,9 +622,9 @@ class Agent(Generic[Context, AgentStructuredOutput]):
# self.planner_model_name = None
def _setup_action_models(self) -> None:
- """Setup dynamic action models from controller's registry"""
+ """Setup dynamic action models from tools's registry"""
# Initially only include actions with no filters
- self.ActionModel = self.controller.registry.create_action_model()
+ self.ActionModel = self.tools.registry.create_action_model()
# Create output model with the dynamic actions
if self.settings.flash_mode:
self.AgentOutput = AgentOutput.type_with_custom_actions_flash_mode(self.ActionModel)
@@ -628,7 +634,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
self.AgentOutput = AgentOutput.type_with_custom_actions_no_thinking(self.ActionModel)
# used to force the done action when max_steps is reached
- self.DoneActionModel = self.controller.registry.create_action_model(include_actions=['done'])
+ self.DoneActionModel = self.tools.registry.create_action_model(include_actions=['done'])
if self.settings.flash_mode:
self.DoneAgentOutput = AgentOutput.type_with_custom_actions_flash_mode(self.DoneActionModel)
elif self.settings.use_thinking:
@@ -723,7 +729,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
await self._update_action_models_for_page(browser_state_summary.url)
# Get page-specific filtered actions
- page_filtered_actions = self.controller.registry.get_prompt_description(browser_state_summary.url)
+ page_filtered_actions = self.tools.registry.get_prompt_description(browser_state_summary.url)
# Page-specific actions will be included directly in the browser_state message
self.logger.debug(f'💬 Step {self.state.n_steps}: Creating state messages for context...')
@@ -1060,7 +1066,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
parsed.action = parsed.action[: self.settings.max_actions_per_step]
if not (hasattr(self.state, 'paused') and (self.state.paused or self.state.stopped)):
- log_response(parsed, self.controller.registry.registry, self.logger)
+ log_response(parsed, self.tools.registry.registry, self.logger)
self._log_next_action_summary(parsed)
return parsed
@@ -1641,7 +1647,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
time_start = time.time()
self.logger.info(f' 🦾 {blue}[ACTION {i + 1}/{total_actions}]{reset} {action_params}')
- result = await self.controller.act(
+ result = await self.tools.act(
action=action,
browser_session=self.browser_session,
file_system=self.file_system,
@@ -1863,7 +1869,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
params = action_dict[action_name]
# Get the parameter model for this action from registry
- action_info = self.controller.registry.registry.actions[action_name]
+ action_info = self.tools.registry.registry.actions[action_name]
param_model = action_info.param_model
# Create validated parameters using the appropriate param model
@@ -1926,7 +1932,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
async def _update_action_models_for_page(self, page_url: str) -> None:
"""Update action models with page-specific actions"""
# Create new action model with current page's filtered actions
- self.ActionModel = self.controller.registry.create_action_model(page_url=page_url)
+ self.ActionModel = self.tools.registry.create_action_model(page_url=page_url)
# Update output model with the new actions
if self.settings.flash_mode:
self.AgentOutput = AgentOutput.type_with_custom_actions_flash_mode(self.ActionModel)
@@ -1936,7 +1942,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):
self.AgentOutput = AgentOutput.type_with_custom_actions_no_thinking(self.ActionModel)
# Update done action model too
- self.DoneActionModel = self.controller.registry.create_action_model(include_actions=['done'], page_url=page_url)
+ self.DoneActionModel = self.tools.registry.create_action_model(include_actions=['done'], page_url=page_url)
if self.settings.flash_mode:
self.DoneAgentOutput = AgentOutput.type_with_custom_actions_flash_mode(self.DoneActionModel)
elif self.settings.use_thinking:
diff --git a/browser_use/logging_config.py b/browser_use/logging_config.py
index 353e57712..0ebfc65e0 100644
--- a/browser_use/logging_config.py
+++ b/browser_use/logging_config.py
@@ -100,8 +100,8 @@ def setup_logging(stream=None, log_level=None, force_setup=False, debug_log_file
record.name = 'Agent'
elif 'BrowserSession' in record.name:
record.name = 'BrowserSession'
- elif 'controller' in record.name:
- record.name = 'controller'
+ elif 'tools' in record.name:
+ record.name = 'tools'
elif 'dom' in record.name:
record.name = 'dom'
elif record.name.startswith('browser_use.'):
diff --git a/examples/simple.py b/examples/simple.py
index ac9c3b1f4..6471ca438 100644
--- a/examples/simple.py
+++ b/examples/simple.py
@@ -1,11 +1,23 @@
import asyncio
-from browser_use import Agent, ChatOpenAI
+from browser_use import Agent, Controller
+
+controller = Controller()
+
+
[email protected]('Ask human for help with a question')
+def ask_human(question: str) -> str:
+ answer = input(f'{question} > ')
+ return f'The human responded with: {answer}'
+
+
+agent = Agent(
+ task='Ask human for help',
+ controller=controller,
+)
async def main():
- task = 'Find the founders of browser-use'
- agent = Agent(task=task, llm=ChatOpenAI(model='gpt-4.1-mini'))
await agent.run()