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
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.mdcindex 5850ce6f5..eac6ccc7b 100644--- a/.cursor/rules/browser-use-rules.mdc+++ b/.cursor/rules/browser-use-rules.mdc@@ -41,7 +41,7 @@ uv syncDo **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:```pythonfrom 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 resultsresult = ...@@ -82,7 +82,7 @@ from browser_use import Agent, ChatOpenAItask = "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.ymlindex 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 thisstep, then I manually click a browser extension in the navbar that automates the mouse movevement.validations:required: falsediff --git a/README.md b/README.mdindex 2db9f0233..059641907 100644--- a/README.md+++ b/README.md@@ -129,8 +129,8 @@ from browser_use import Agent, Tools, ChatOpenAIfrom browser_use.mcp.client import MCPClientasync def main():- # Initialize controller- controller = Tools()+ # Initialize tools+ tools = Tools()# Connect to multiple MCP serversfilesystem_client = MCPClient(@@ -148,16 +148,16 @@ async def main():# Connect and register tools from both serversawait 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 toolsagent = 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 agentdiff --git a/browser_use/agent/service.py b/browser_use/agent/service.pyindex 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 parameterssensitive_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 = llmself.preload = preloadself.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 outputself.output_model_schema = output_model_schemaif 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 = Nonedef _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 actionsif 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 messageself.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 actionsif 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.pyindex 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_filerecord.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.pyindex 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()