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
Clear use_cloud missing-key error; captcha cloud hint only for non-cloud browsers
Gregor Žuničf0af8268b8ea
diff --git a/browser_use/agent/service.py b/browser_use/agent/service.pyindex 783889764..4bfd19844 100644--- a/browser_use/agent/service.py+++ b/browser_use/agent/service.py@@ -61,6 +61,7 @@ from browser_use.agent.views import (PlanItem,StepMetadata,)+from browser_use.browser.cloud.views import CloudBrowserAuthErrorfrom browser_use.browser.events import _get_timeoutfrom browser_use.browser.session import DEFAULT_BROWSER_PROFILEfrom browser_use.browser.views import BrowserStateSummary@@ -1660,10 +1661,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):if judgement.failure_reason:judge_log += f' Failure Reason: {judgement.failure_reason}\n'if judgement.reached_captcha:- self.logger.warning(- 'Agent was blocked by a captcha. Cloud browsers include stealth fingerprinting and proxy rotation to avoid this.\n'- ' Try: Browser(use_cloud=True) | Get an API key: https://cloud.browser-use.com?utm_source=oss&utm_medium=captcha_nudge'- )+ self._log_cloud_captcha_hint()judge_log += f' {judgement.reasoning}\n'self.logger.info(judge_log)@@ -2161,8 +2159,27 @@ class Agent(Generic[Context, AgentStructuredOutput]):self.logger.debug(message)return message- def _log_final_outcome_messages(self) -> None:+ def _log_cloud_captcha_hint(self) -> None:+ """Point local-browser users at cloud browsers after a captcha block, at most once per run."""+ if getattr(self, '_cloud_captcha_hint_logged', False) or not CONFIG.BROWSER_USE_CLOUD_HINTS:+ return+ session = self.browser_session+ if session is not None:+ profile = session.browser_profile+ host = urlparse(session.cdp_url or '').hostname or ''+ if profile.use_cloud or profile.cloud_browser_params is not None or host.endswith('.browser-use.com'):+ return # already on a Browser Use cloud browser+ self._cloud_captcha_hint_logged = True+ self.logger.warning(+ 'Agent was blocked by a captcha. Cloud browsers include stealth fingerprinting and proxy rotation to avoid this.\n'+ ' Try: Browser(use_cloud=True) | Get an API key: https://cloud.browser-use.com?utm_source=oss&utm_medium=captcha_nudge\n'+ ' Silence this hint: BROWSER_USE_CLOUD_HINTS=false'+ )++ def _log_final_outcome_messages(self, cloud_auth_failed: bool = False) -> None:"""Log helpful messages to user based on agent run outcome"""+ if cloud_auth_failed:+ return # the missing/invalid key message already says what to do; it is not a bug to report# Check if agent failedis_successful = self.history.is_successful()@@ -2176,10 +2193,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):has_captcha_issue = any(keyword in final_result_str for keyword in captcha_keywords)if has_captcha_issue:- self.logger.warning(- 'Agent was blocked by a captcha. Cloud browsers include stealth fingerprinting and proxy rotation to avoid this.\n'- ' Try: Browser(use_cloud=True) | Get an API key: https://cloud.browser-use.com?utm_source=oss&utm_medium=captcha_nudge'- )+ self._log_cloud_captcha_hint()# General failure messageself.logger.info('')@@ -2510,7 +2524,9 @@ class Agent(Generic[Context, AgentStructuredOutput]):loop = asyncio.get_event_loop()agent_run_error: str | None = None # Initialize error tracking variable+ cloud_auth_failed = Falseself._force_exit_telemetry_logged = False # ADDED: Flag for custom telemetry on force exit+ self._cloud_captcha_hint_logged = Falseshould_delay_close = False# Set up the signal handler with callbacks specific to this agent@@ -2669,7 +2685,12 @@ class Agent(Generic[Context, AgentStructuredOutput]):return self.historyexcept Exception as e:- self.logger.error(f'Agent run failed with exception: {e}', exc_info=True)+ if isinstance(e, CloudBrowserAuthError):+ # Actionable config error: show the message once, without a traceback.+ cloud_auth_failed = True+ self.logger.error(f'Agent run failed: {e}')+ else:+ self.logger.error(f'Agent run failed with exception: {e}', exc_info=True)agent_run_error = str(e)raise e@@ -2717,7 +2738,7 @@ class Agent(Generic[Context, AgentStructuredOutput]):self.eventbus.dispatch(output_event)# Log final messages to user based on outcome- self._log_final_outcome_messages()+ self._log_final_outcome_messages(cloud_auth_failed=cloud_auth_failed)# Stop the event bus gracefully, waiting for all events to be processed# Configurable via TIMEOUT_AgentEventBusStop env var (default: 3.0s)diff --git a/browser_use/browser/cloud/cloud.py b/browser_use/browser/cloud/cloud.pyindex 13ae07833..76d34b099 100644--- a/browser_use/browser/cloud/cloud.py+++ b/browser_use/browser/cloud/cloud.py@@ -17,6 +17,24 @@ logger = logging.getLogger(__name__)_BROWSER_API_VERSIONS = ('v2', 'v3', 'v4')+MISSING_API_KEY_MESSAGE = (+ 'BROWSER_USE_API_KEY is not set. Browser(use_cloud=True) needs a Browser Use Cloud API key.\n'+ ' 1. Create a key (free to start): '+ 'https://cloud.browser-use.com/new-api-key?utm_source=oss&utm_medium=use_cloud\n'+ ' 2. Set it: export BROWSER_USE_API_KEY=your-key (or put it in .env and call load_dotenv())'+)+++def resolve_api_key() -> str | None:+ """Return the Browser Use Cloud API key from BROWSER_USE_API_KEY, then the saved auth config."""+ api_token = os.getenv('BROWSER_USE_API_KEY')+ if api_token:+ return api_token+ try:+ return CloudAuthConfig.load_from_file().api_token+ except Exception:+ return None+class CloudBrowserClient:"""Client for browser-use cloud browser service."""@@ -77,22 +95,9 @@ class CloudBrowserClient:Returns:CloudBrowserResponse: Contains CDP URL and other browser info"""- # Try to get API key from environment variable first, then auth config- api_token = os.getenv('BROWSER_USE_API_KEY')-+ api_token = resolve_api_key()if not api_token:- # Fallback to auth config file- try:- auth_config = CloudAuthConfig.load_from_file()- api_token = auth_config.api_token- except Exception:- pass-- if not api_token:- raise CloudBrowserAuthError(- 'BROWSER_USE_API_KEY is not set. To use cloud browsers, get a key at:\n'- 'https://cloud.browser-use.com/new-api-key?utm_source=oss&utm_medium=use_cloud'- )+ raise CloudBrowserAuthError(MISSING_API_KEY_MESSAGE)headers = {'X-Browser-Use-API-Key': api_token, 'Content-Type': 'application/json', **(extra_headers or {})}@@ -165,22 +170,9 @@ class CloudBrowserClient:if not session_id:raise CloudBrowserError('No session ID provided and no current session available')- # Try to get API key from environment variable first, then auth config- api_token = os.getenv('BROWSER_USE_API_KEY')-- if not api_token:- # Fallback to auth config file- try:- auth_config = CloudAuthConfig.load_from_file()- api_token = auth_config.api_token- except Exception:- pass-+ api_token = resolve_api_key()if not api_token:- raise CloudBrowserAuthError(- 'BROWSER_USE_API_KEY is not set. To use cloud browsers, get a key at:\n'- 'https://cloud.browser-use.com/new-api-key?utm_source=oss&utm_medium=use_cloud'- )+ raise CloudBrowserAuthError(MISSING_API_KEY_MESSAGE)headers = {'X-Browser-Use-API-Key': api_token, 'Content-Type': 'application/json', **(extra_headers or {})}diff --git a/browser_use/browser/session.py b/browser_use/browser/session.pyindex c45f1213e..ba8779140 100644--- a/browser_use/browser/session.py+++ b/browser_use/browser/session.py@@ -21,7 +21,13 @@ from pydantic import BaseModel, ConfigDict, Field, PrivateAttrfrom uuid_extensions import uuid7strfrom browser_use.browser._cdp_timeout import TimeoutWrappedCDPClient-from browser_use.browser.cloud.cloud import CloudBrowserAuthError, CloudBrowserClient, CloudBrowserError+from browser_use.browser.cloud.cloud import (+ MISSING_API_KEY_MESSAGE,+ CloudBrowserAuthError,+ CloudBrowserClient,+ CloudBrowserError,+ resolve_api_key,+)# CDP logging is now handled by setup_logging() in logging_config.py# It automatically sets CDP logs to the same level as browser_use logs@@ -54,6 +60,7 @@ from browser_use.browser.events import ()from browser_use.browser.profile import BrowserProfile, ProxySettingsfrom browser_use.browser.views import BrowserStateSummary, TabInfo+from browser_use.config import CONFIGfrom browser_use.dom.views import DOMRect, EnhancedDOMTreeNode, SerializedDOMState, TargetInfofrom browser_use.observability import observe_debugfrom browser_use.utils import _log_pretty_url, create_task_with_error_handling, is_new_tab_page@@ -726,11 +733,20 @@ class BrowserSession(BaseModel):@observe_debug(ignore_input=True, ignore_output=True, name='browser_session_start')async def start(self) -> None:"""Start the browser session."""+ self._raise_if_cloud_api_key_missing()start_event = self.event_bus.dispatch(BrowserStartEvent())await start_event# Ensure any exceptions from the event handler are propagatedawait start_event.event_result(raise_if_any=True, raise_if_none=False)+ def _raise_if_cloud_api_key_missing(self) -> None:+ """Fail fast with one clear message instead of letting the event bus log the error several times."""+ profile = self.browser_profile+ if self.cdp_url or not (profile.use_cloud or profile.cloud_browser_params is not None):+ return+ if not resolve_api_key():+ raise CloudBrowserAuthError(MISSING_API_KEY_MESSAGE)+async def kill(self) -> None:"""Kill the browser session and reset all state."""self._intentional_stop = True@@ -897,7 +913,7 @@ class BrowserSession(BaseModel):details={'cdp_url': self.cdp_url, 'is_local': self.is_local},))- if self.is_local and not isinstance(e, (CloudBrowserAuthError, CloudBrowserError)):+ if self.is_local and CONFIG.BROWSER_USE_CLOUD_HINTS and not isinstance(e, (CloudBrowserAuthError, CloudBrowserError)):self.logger.warning('Local browser failed to start. Cloud browsers require no local install and work out of the box.\n'' Try: Browser(use_cloud=True) | Get an API key: https://cloud.browser-use.com?utm_source=oss&utm_medium=browser_launch_failure'diff --git a/browser_use/config.py b/browser_use/config.pyindex 1ac9b49ce..10909a131 100644--- a/browser_use/config.py+++ b/browser_use/config.py@@ -183,6 +183,10 @@ class OldConfig:def BROWSER_USE_VERSION_CHECK(self) -> bool:return os.getenv('BROWSER_USE_VERSION_CHECK', 'true').lower()[:1] in 'ty1'+ @property+ def BROWSER_USE_CLOUD_HINTS(self) -> bool:+ return os.getenv('BROWSER_USE_CLOUD_HINTS', 'true').lower()[:1] in 'ty1'+@propertydef WIN_FONT_DIR(self) -> str:return os.getenv('WIN_FONT_DIR', 'C:\\Windows\\Fonts')@@ -226,6 +230,7 @@ class FlatEnvConfig(BaseSettings):IS_IN_EVALS: bool = Field(default=False)WIN_FONT_DIR: str = Field(default='C:\\Windows\\Fonts')BROWSER_USE_VERSION_CHECK: bool = Field(default=True)+ BROWSER_USE_CLOUD_HINTS: bool = Field(default=True)# MCP-specific env varsBROWSER_USE_CONFIG_PATH: str | None = Field(default=None)diff --git a/tests/ci/test_cloud_hints.py b/tests/ci/test_cloud_hints.pynew file mode 100644index 000000000..15d9f539a--- /dev/null+++ b/tests/ci/test_cloud_hints.py@@ -0,0 +1,101 @@+"""Cloud browser messages: a clear missing-key error and captcha hints only where they help."""++import logging+from unittest.mock import AsyncMock, patch++import pytest++from browser_use import Agent+from browser_use.browser.cloud.cloud import CloudBrowserAuthError, CloudBrowserClient, resolve_api_key+from browser_use.browser.profile import BrowserProfile+from browser_use.browser.session import BrowserSession+from browser_use.sync.auth import CloudAuthConfig+from tests.ci.conftest import create_mock_llm+++def records():+ """Capture browser_use log records (the browser_use logger does not propagate to root)."""+ captured: list[logging.LogRecord] = []++ class _ListHandler(logging.Handler):+ def emit(self, record):+ captured.append(record)++ handler = _ListHandler(level=logging.DEBUG)+ logger = logging.getLogger('browser_use')+ logger.addHandler(handler)+ yield captured+ logger.removeHandler(handler)+++def no_api_key(monkeypatch, tmp_path):+ monkeypatch.delenv('BROWSER_USE_API_KEY', raising=False)+ monkeypatch.setenv('BROWSER_USE_CONFIG_DIR', str(tmp_path))+++def test_resolve_api_key_prefers_env_then_saved_login(no_api_key, monkeypatch):+ assert resolve_api_key() is None++ CloudAuthConfig(api_token='saved-token', user_id='u', authorized_at=None).save_to_file()+ assert resolve_api_key() == 'saved-token'++ monkeypatch.setenv('BROWSER_USE_API_KEY', 'env-token')+ assert resolve_api_key() == 'env-token'+++async def test_use_cloud_without_key_fails_before_any_request(no_api_key):+ session = BrowserSession(use_cloud=True)+ with patch.object(CloudBrowserClient, 'create_browser', new_callable=AsyncMock) as create_browser:+ with pytest.raises(CloudBrowserAuthError) as exc_info:+ await session.start()++ create_browser.assert_not_awaited()+ message = str(exc_info.value)+ assert 'BROWSER_USE_API_KEY is not set' in message+ assert 'https://cloud.browser-use.com/new-api-key?utm_source=oss&utm_medium=use_cloud' in message+ assert 'export BROWSER_USE_API_KEY=' in message+++async def test_agent_logs_missing_key_once_without_traceback(no_api_key, records):+ agent = Agent(task='open example.com', llm=create_mock_llm(), browser_session=BrowserSession(use_cloud=True))++ with pytest.raises(CloudBrowserAuthError):+ await agent.run(max_steps=1)++ key_errors = [r for r in records if r.levelno >= logging.ERROR and 'BROWSER_USE_API_KEY is not set' in r.getMessage()]+ assert len(key_errors) == 1+ assert key_errors[0].exc_info is None+ assert not any('Open a short issue on GitHub' in r.getMessage() for r in records)+++def _captcha_hints(records) -> int:+ return sum('blocked by a captcha' in r.getMessage() for r in records)+++ 'session_kwargs, expected',+ [+ ({'browser_profile': BrowserProfile(headless=True)}, 1),+ ({'use_cloud': True}, 0),+ ({'cdp_url': 'wss://0e5c5a0e-1111-2222-3333-444455556666.cdp1.browser-use.com'}, 0),+ ({'cdp_url': 'wss://connect.example-provider.com'}, 1),+ ],+)+async def test_captcha_hint_only_for_non_browser_use_browsers_and_once_per_run(records, session_kwargs, expected):+ agent = Agent(task='t', llm=create_mock_llm(), browser_session=BrowserSession(**session_kwargs))++ agent._log_cloud_captcha_hint()+ agent._log_cloud_captcha_hint()++ assert _captcha_hints(records) == expected+++async def test_cloud_hints_can_be_silenced(records, monkeypatch):+ monkeypatch.setenv('BROWSER_USE_CLOUD_HINTS', 'false')+ agent = Agent(task='t', llm=create_mock_llm(), browser_session=BrowserSession(browser_profile=BrowserProfile(headless=True)))++ agent._log_cloud_captcha_hint()++ assert _captcha_hints(records) == 0