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
Squashed commit of the following:
Magnus Müllerde0488031d7e
diff --git a/.env.example b/.env.exampleindex c9ba4cb58..d57d2c24e 100644--- a/.env.example+++ b/.env.example@@ -20,7 +20,7 @@ CDP_LOGGING_LEVEL=WARNINGANONYMIZED_TELEMETRY=true# Browser Use Cloud Configuration (optional)-# Your Browser Use Cloud API key - get it from: https://cloud.browser-use.com/billing+# Your Browser Use Cloud API key - get it from: https://cloud.browser-use.com/dashboard/api# BROWSER_USE_API_KEY=your_api_key_here# Custom API base URL (for enterprise installations)@@ -55,3 +55,10 @@ ANONYMIZED_TELEMETRY=true# BROWSER_USE_NO_PROXY=localhost,127.0.0.1,*.internal# BROWSER_USE_PROXY_USERNAME=username# BROWSER_USE_PROXY_PASSWORD=password+++# Browser use LLM+++# Your Browser Use Cloud API key - get it from: https://cloud.browser-use.com/dashboard/api+# BROWSER_USE_API_KEY=your_api_key_herediff --git a/.gitignore b/.gitignoreindex 8f39744c0..837aae7b1 100644--- a/.gitignore+++ b/.gitignore@@ -67,3 +67,6 @@ all_github_issues.mdtodo-input-token.mdTOOL_CHANGES_SUMMARY.md+++claude-code-tododiff --git a/browser_use/agent/prompts.py b/browser_use/agent/prompts.pyindex 49ea5c8bd..95ce4a321 100644--- a/browser_use/agent/prompts.py+++ b/browser_use/agent/prompts.py@@ -16,14 +16,12 @@ if TYPE_CHECKING:class SystemPrompt:def __init__(self,- action_description: str,max_actions_per_step: int = 10,override_system_message: str | None = None,extend_system_message: str | None = None,use_thinking: bool = True,flash_mode: bool = False,):- self.default_action_description = action_descriptionself.max_actions_per_step = max_actions_per_stepself.use_thinking = use_thinkingself.flash_mode = flash_mode@@ -66,15 +64,6 @@ class SystemPrompt:return self.system_message-# Functions:-# {self.default_action_description}--# Example:-# {self.example_response()}-# Your AVAILABLE ACTIONS:-# {self.default_action_description}--class AgentMessagePrompt:vision_detail_level: Literal['auto', 'low', 'high']diff --git a/browser_use/agent/service.py b/browser_use/agent/service.pyindex 8e549b63a..eef5534b3 100644--- a/browser_use/agent/service.py+++ b/browser_use/agent/service.py@@ -203,6 +203,10 @@ class Agent(Generic[Context, AgentStructuredOutput]):# No default LLM specified, use the original defaultllm = ChatGoogle(model='gemini-flash-latest')+ # set flashmode = True if llm is ChatBrowserUse+ if llm.provider == 'browser-use':+ flash_mode = True+if page_extraction_llm is None:page_extraction_llm = llmif available_file_paths is None:@@ -357,7 +361,6 @@ class Agent(Generic[Context, AgentStructuredOutput]):self._message_manager = MessageManager(task=task,system_message=SystemPrompt(- action_description=self.unfiltered_actions,max_actions_per_step=self.settings.max_actions_per_step,override_system_message=override_system_message,extend_system_message=extend_system_message,@@ -1192,9 +1195,15 @@ class Agent(Generic[Context, AgentStructuredOutput]):urls_replaced = self._process_messsages_and_replace_long_urls_shorter_ones(input_messages)+ # Build kwargs for ainvoke, including prompt_description for browser-use cloud+ kwargs: dict = {'output_format': self.AgentOutput}+ actual_llm = getattr(self.llm, '__wrapped__', self.llm)+ if getattr(actual_llm, 'provider', None) == 'browser-use':+ kwargs['prompt_description'] = self.tools.registry.get_prompt_description()+try:- response = await self.llm.ainvoke(input_messages, output_format=self.AgentOutput)- parsed = response.completion+ response = await self.llm.ainvoke(input_messages, **kwargs)+ parsed: AgentOutput = response.completion # type: ignore[assignment]# Replace any shortened URLs in the LLM response back to original URLsif urls_replaced:diff --git a/browser_use/agent/system_prompt_flash.md b/browser_use/agent/system_prompt_flash.mdindex 8e7b5f6f7..f2090b1cf 100644--- a/browser_use/agent/system_prompt_flash.md+++ b/browser_use/agent/system_prompt_flash.md@@ -22,9 +22,6 @@ CSV: use double quotes for commas.available_file_paths: downloaded/user files (read/upload only).</file_system>---<output>You must respond with a valid JSON in this exact format:{{diff --git a/browser_use/llm/__init__.py b/browser_use/llm/__init__.pyindex 9fbb197c0..c9e4090b6 100644--- a/browser_use/llm/__init__.py+++ b/browser_use/llm/__init__.py@@ -30,6 +30,7 @@ if TYPE_CHECKING:from browser_use.llm.aws.chat_anthropic import ChatAnthropicBedrockfrom browser_use.llm.aws.chat_bedrock import ChatAWSBedrockfrom browser_use.llm.azure.chat import ChatAzureOpenAI+ from browser_use.llm.browser_use.chat import ChatBrowserUsefrom browser_use.llm.cerebras.chat import ChatCerebrasfrom browser_use.llm.deepseek.chat import ChatDeepSeekfrom browser_use.llm.google.chat import ChatGoogle@@ -79,6 +80,7 @@ _LAZY_IMPORTS = {'ChatAnthropicBedrock': ('browser_use.llm.aws.chat_anthropic', 'ChatAnthropicBedrock'),'ChatAWSBedrock': ('browser_use.llm.aws.chat_bedrock', 'ChatAWSBedrock'),'ChatAzureOpenAI': ('browser_use.llm.azure.chat', 'ChatAzureOpenAI'),+ 'ChatBrowserUse': ('browser_use.llm.browser_use.chat', 'ChatBrowserUse'),'ChatCerebras': ('browser_use.llm.cerebras.chat', 'ChatCerebras'),'ChatDeepSeek': ('browser_use.llm.deepseek.chat', 'ChatDeepSeek'),'ChatGoogle': ('browser_use.llm.google.chat', 'ChatGoogle'),@@ -136,6 +138,7 @@ __all__ = [# Chat models'BaseChatModel','ChatOpenAI',+ 'ChatBrowserUse','ChatDeepSeek','ChatGoogle','ChatAnthropic',diff --git a/browser_use/llm/browser_use/__init__.py b/browser_use/llm/browser_use/__init__.pynew file mode 100644index 000000000..791a54499--- /dev/null+++ b/browser_use/llm/browser_use/__init__.py@@ -0,0 +1,3 @@+from browser_use.llm.browser_use.chat import ChatBrowserUse++__all__ = ['ChatBrowserUse']diff --git a/browser_use/llm/browser_use/chat.py b/browser_use/llm/browser_use/chat.pynew file mode 100644index 000000000..6f41d2091--- /dev/null+++ b/browser_use/llm/browser_use/chat.py@@ -0,0 +1,202 @@+"""+ChatBrowserUse - Client for browser-use cloud API++This wraps the BaseChatModel protocol and sends requests to the browser-use cloud API+for optimized browser automation LLM inference.+"""++import logging+import os+from typing import TypeVar, overload++import httpx+from pydantic import BaseModel++from browser_use.llm.base import BaseChatModel+from browser_use.llm.messages import BaseMessage+from browser_use.llm.views import ChatInvokeCompletion+from browser_use.observability import observe++T = TypeVar('T', bound=BaseModel)++logger = logging.getLogger(__name__)+++class ChatBrowserUse(BaseChatModel):+ """+ Client for browser-use cloud API.++ This sends requests to the browser-use cloud API which uses optimized models+ and prompts for browser automation tasks.++ Usage:+ agent = Agent(+ task="Find the number of stars of the browser-use repo",+ llm=ChatBrowserUse(),+ )+ """++ def __init__(+ self,+ fast: bool = False,+ api_key: str | None = None,+ base_url: str | None = None,+ timeout: float = 120.0,+ ):+ """+ Initialize ChatBrowserUse client.++ Args:+ fast: If True, uses fast model. If False, uses smart model.+ api_key: API key for browser-use cloud. Defaults to BROWSER_USE_API_KEY env var.+ base_url: Base URL for the API. Defaults to BROWSER_USE_LLM_URL env var or production URL.+ timeout: Request timeout in seconds.+ """+ self.fast = fast+ self.api_key = api_key or os.getenv('BROWSER_USE_API_KEY')+ self.base_url = base_url or os.getenv('BROWSER_USE_LLM_URL', 'https://llm.api.browser-use.com')+ self.timeout = timeout+ self.model = 'fast' if fast else 'smart'++ if not self.api_key:+ raise ValueError(+ 'You need to set the BROWSER_USE_API_KEY environment variable. '+ 'Get your key at https://cloud.browser-use.com/dashboard/api'+ )++ @property+ def provider(self) -> str:+ return 'browser-use'++ @property+ def name(self) -> str:+ return f'browser-use/{self.model}'++ @overload+ async def ainvoke(+ self, messages: list[BaseMessage], output_format: None = None, prompt_description: str | None = None+ ) -> ChatInvokeCompletion[str]: ...++ @overload+ async def ainvoke(+ self, messages: list[BaseMessage], output_format: type[T], prompt_description: str | None = None+ ) -> ChatInvokeCompletion[T]: ...++ @observe(name='chat_browser_use_ainvoke')+ async def ainvoke(+ self, messages: list[BaseMessage], output_format: type[T] | None = None, prompt_description: str | None = None+ ) -> ChatInvokeCompletion[T] | ChatInvokeCompletion[str]:+ """+ Send request to browser-use cloud API.++ Args:+ messages: List of messages to send+ output_format: Expected output format (Pydantic model)+ prompt_description: Action descriptions for the prompt (optional)++ Returns:+ ChatInvokeCompletion with structured response and usage info+ """+ # Prepare request payload+ payload = {+ 'messages': [self._serialize_message(msg) for msg in messages],+ 'fast': self.fast,+ }++ # Add output format schema if provided+ if output_format is not None:+ payload['output_format'] = output_format.model_json_schema()++ # Add prompt description if provided+ logger.debug(+ f'🔍 ChatBrowserUse received prompt_description: {prompt_description is not None}, length: {len(prompt_description) if prompt_description else 0}'+ )+ if prompt_description is not None:+ payload['prompt_description'] = prompt_description+ logger.debug('Added prompt_description to payload')++ # Make API request+ async with httpx.AsyncClient(timeout=self.timeout) as client:+ try:+ response = await client.post(+ f'{self.base_url}/v1/chat/completions',+ json=payload,+ headers={+ 'Authorization': f'Bearer {self.api_key}',+ 'Content-Type': 'application/json',+ },+ )+ response.raise_for_status()+ result = response.json()++ except httpx.HTTPStatusError as e:+ error_detail = ''+ try:+ error_data = e.response.json()+ error_detail = error_data.get('detail', str(e))+ except Exception:+ error_detail = str(e)++ error_msg = ''+ if e.response.status_code == 401:+ error_msg = f'Invalid API key. {error_detail}'+ elif e.response.status_code == 402:+ error_msg = f'Insufficient credits. {error_detail}'+ else:+ error_msg = f'API request failed: {error_detail}'++ raise ValueError(error_msg)++ except httpx.TimeoutException:+ error_msg = f'Request timed out after {self.timeout}s'+ raise ValueError(error_msg)++ except Exception as e:+ error_msg = f'Failed to connect to browser-use API: {e}'+ raise ValueError(error_msg)++ # Parse response - server returns structured data as dict+ if output_format is not None:+ # Server returns structured data as a dict, validate it+ completion_data = result['completion']+ logger.debug(+ f'📥 Got structured data from service: {list(completion_data.keys()) if isinstance(completion_data, dict) else type(completion_data)}'+ )++ # Convert action dicts to ActionModel instances if needed+ # llm-use returns dicts to avoid validation with empty ActionModel+ if isinstance(completion_data, dict) and 'action' in completion_data:+ actions = completion_data['action']+ if actions and isinstance(actions[0], dict):+ from typing import get_args++ # Get ActionModel type from output_format+ action_model_type = get_args(output_format.model_fields['action'].annotation)[0]++ # Convert dicts to ActionModel instances+ completion_data['action'] = [action_model_type.model_validate(action_dict) for action_dict in actions]++ completion = output_format.model_validate(completion_data)+ else:+ completion = result['completion']++ # Parse usage info+ usage = None+ if 'usage' in result:+ from browser_use.llm.views import ChatInvokeUsage++ usage = ChatInvokeUsage(**result['usage'])++ return ChatInvokeCompletion(+ completion=completion,+ usage=usage,+ )++ def _serialize_message(self, message: BaseMessage) -> dict:+ """Serialize a message to JSON format."""+ # Handle Union types by checking the actual message type+ msg_dict = message.model_dump()+ return {+ 'role': msg_dict['role'],+ 'content': msg_dict['content'],+ }diff --git a/browser_use/tokens/service.py b/browser_use/tokens/service.pyindex 8a12d9939..9b32e8294 100644--- a/browser_use/tokens/service.py+++ b/browser_use/tokens/service.py@@ -317,9 +317,9 @@ class TokenCost:token_cost_service = self# Create a wrapped version that tracks usage- async def tracked_ainvoke(messages, output_format=None):- # Call the original method- result = await original_ainvoke(messages, output_format)+ async def tracked_ainvoke(messages, output_format=None, **kwargs):+ # Call the original method, passing through any additional kwargs+ result = await original_ainvoke(messages, output_format, **kwargs)# Track usage if available (no await needed since add_usage is now sync)if result.usage:diff --git a/browser_use/tools/registry/views.py b/browser_use/tools/registry/views.pyindex 5cee81826..598cd9129 100644--- a/browser_use/tools/registry/views.py+++ b/browser_use/tools/registry/views.py@@ -25,18 +25,31 @@ class RegisteredAction(BaseModel):model_config = ConfigDict(arbitrary_types_allowed=True)def prompt_description(self) -> str:- """Get a description of the action for the prompt"""- skip_keys = ['title']- s = f'{self.description}: \n'- s += '{' + str(self.name) + ': '- s += str(- {- k: {sub_k: sub_v for sub_k, sub_v in v.items() if sub_k not in skip_keys}- for k, v in self.param_model.model_json_schema()['properties'].items()- }- )- s += '}'- return s+ """Get a description of the action for the prompt in unstructured format"""+ schema = self.param_model.model_json_schema()+ params = []++ if 'properties' in schema:+ for param_name, param_info in schema['properties'].items():+ # Build parameter description+ param_desc = param_name++ # Add type information if available+ if 'type' in param_info:+ param_type = param_info['type']+ param_desc += f'={param_type}'++ # Add description as comment if available+ if 'description' in param_info:+ param_desc += f' ({param_info["description"]})'++ params.append(param_desc)++ # Format: action_name: Description. (param1=type, param2=type, ...)+ if params:+ return f'{self.name}: {self.description}. ({", ".join(params)})'+ else:+ return f'{self.name}: {self.description}'class ActionModel(BaseModel):diff --git a/docs/cloud/v1/custom-sdk.mdx b/docs/cloud/v1/custom-sdk.mdxindex b52a992fe..1bd29ed4f 100644--- a/docs/cloud/v1/custom-sdk.mdx+++ b/docs/cloud/v1/custom-sdk.mdx@@ -81,7 +81,7 @@ export type Client = ReturnType<typeof createClient<paths>>export const client = createClient<paths>({baseUrl: 'https://api.browser-use.com/',- // NOTE: You can get your API key from https://cloud.browser-use.com/billing!+ // NOTE: You can get your API key from https://cloud.browser-use.com/dashboard/api!headers: { Authorization: `Bearer ${apiKey}` },})diff --git a/docs/cloud/v1/n8n-browser-use-integration.mdx b/docs/cloud/v1/n8n-browser-use-integration.mdxindex 6d6c1dfed..2ba293b77 100644--- a/docs/cloud/v1/n8n-browser-use-integration.mdx+++ b/docs/cloud/v1/n8n-browser-use-integration.mdx@@ -30,7 +30,7 @@ n8n glues everything together so your team gets the data instantly—no Python s## Prerequisites-1. **Browser Use Cloud API key** – grab one from your [Billing page](https://cloud.browser-use.com/billing).+1. **Browser Use Cloud API key** – grab one from your [Billing page](https://cloud.browser-use.com/dashboard/api).2. **n8n instance** – self-hosted or n8n.cloud. (The screenshots below use n8n 1.45+.)3. **Slack Incoming Webhook URL** – create one in your Slack workspace.diff --git a/docs/cloud/v1/quickstart.mdx b/docs/cloud/v1/quickstart.mdxindex 34129e2fc..10cb770e3 100644--- a/docs/cloud/v1/quickstart.mdx+++ b/docs/cloud/v1/quickstart.mdx@@ -18,7 +18,7 @@ mode: "wide"<Note>You need an active subscription and an API key from- [cloud.browser-use.com/billing](https://cloud.browser-use.com/billing). For+ [cloud.browser-use.com/dashboard/billing](https://cloud.browser-use.com/dashboard/billing). Fordetailed pricing information, see our [pricing page](/cloud/v1/pricing).</Note>diff --git a/docs/cloud/v1/webhooks.mdx b/docs/cloud/v1/webhooks.mdxindex 833233c85..7b42c3c4f 100644--- a/docs/cloud/v1/webhooks.mdx+++ b/docs/cloud/v1/webhooks.mdx@@ -11,7 +11,7 @@ Webhooks allow you to receive real-time notifications about events in your Brows<Note>You need an active subscription to create webhooks. See your billing page- [cloud.browser-use.com/billing](https://cloud.browser-use.com/billing)+ [cloud.browser-use.com/dashboard/billing](https://cloud.browser-use.com/dashboard/billing)</Note>## Setting Up Webhooksdiff --git a/examples/cloud/README.md b/examples/cloud/README.mdindex f60c3d5f2..df0cda940 100644--- a/examples/cloud/README.md+++ b/examples/cloud/README.md@@ -4,7 +4,7 @@ Welcome to the Browser Use Cloud examples! This folder contains progressively co## 📋 Prerequisites-1. **API Key**: Get your API key from [cloud.browser-use.com/billing](https://cloud.browser-use.com/billing)+1. **API Key**: Get your API key from [cloud.browser-use.com/dashboard/api](https://cloud.browser-use.com/dashboard/api)2. **Python Environment**: Python 3.11+ with dependencies3. **Environment Variables**: Configure your API settingsdiff --git a/examples/cloud/env.example b/examples/cloud/env.exampleindex 7d73866da..d205cd38e 100644--- a/examples/cloud/env.example+++ b/examples/cloud/env.example@@ -2,7 +2,7 @@# Copy this file to .env and fill in your values# Required: Your Browser Use Cloud API key-# Get it from: https://cloud.browser-use.com/billing+# Get it from: https://cloud.browser-use.com/dashboard/apiBROWSER_USE_API_KEY=your_api_key_here# Optional: Custom API base URL (for enterprise installations)diff --git a/examples/models/browser_use_llm.py b/examples/models/browser_use_llm.pynew file mode 100644index 000000000..9d9023fb9--- /dev/null+++ b/examples/models/browser_use_llm.py@@ -0,0 +1,37 @@+"""+Example of the fastest + smartest LLM for browser automation.++Setup:+1. Get your API key from https://cloud.browser-use.com/dashboard/api+2. Set environment variable: export BROWSER_USE_API_KEY="your-key"+"""++import asyncio+import os++from dotenv import load_dotenv+from lmnr import Laminar++from browser_use import Agent+from browser_use.llm import ChatBrowserUse++load_dotenv()++if not os.getenv('BROWSER_USE_API_KEY'):+ raise ValueError('BROWSER_USE_API_KEY is not set')++Laminar.initialize()+++async def main():+ agent = Agent(+ task='Find the number of stars of the browser-use repo',+ llm=ChatBrowserUse(),+ )++ # Run the agent+ await agent.run()+++if __name__ == '__main__':+ asyncio.run(main())