Skip to content

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

Squashed commit of the following:

Magnus Müllerde0488031d7e
diff --git a/.env.example b/.env.example
index c9ba4cb58..d57d2c24e 100644
--- a/.env.example
+++ b/.env.example
@@ -20,7 +20,7 @@ CDP_LOGGING_LEVEL=WARNING
ANONYMIZED_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_here
diff --git a/.gitignore b/.gitignore
index 8f39744c0..837aae7b1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -67,3 +67,6 @@ all_github_issues.md
todo-input-token.md
TOOL_CHANGES_SUMMARY.md
+
+
+claude-code-todo
diff --git a/browser_use/agent/prompts.py b/browser_use/agent/prompts.py
index 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_description
self.max_actions_per_step = max_actions_per_step
self.use_thinking = use_thinking
self.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.py
index 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 default
llm = 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 = llm
if 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 URLs
if urls_replaced:
diff --git a/browser_use/agent/system_prompt_flash.md b/browser_use/agent/system_prompt_flash.md
index 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__.py
index 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 ChatAnthropicBedrock
from browser_use.llm.aws.chat_bedrock import ChatAWSBedrock
from browser_use.llm.azure.chat import ChatAzureOpenAI
+ from browser_use.llm.browser_use.chat import ChatBrowserUse
from browser_use.llm.cerebras.chat import ChatCerebras
from browser_use.llm.deepseek.chat import ChatDeepSeek
from 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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.py
index 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.mdx
index 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.mdx
index 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.mdx
index 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). For
detailed pricing information, see our [pricing page](/cloud/v1/pricing).
</Note>
diff --git a/docs/cloud/v1/webhooks.mdx b/docs/cloud/v1/webhooks.mdx
index 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 Webhooks
diff --git a/examples/cloud/README.md b/examples/cloud/README.md
index 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 dependencies
3. **Environment Variables**: Configure your API settings
diff --git a/examples/cloud/env.example b/examples/cloud/env.example
index 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/api
BROWSER_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.py
new file mode 100644
index 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())