browser_use.py
1 """Browser Use cloud browser provider.""" 2 3 import logging 4 import os 5 import threading 6 import uuid 7 from typing import Any, Dict, Optional 8 9 import requests 10 11 from tools.browser_providers.base import CloudBrowserProvider 12 from tools.managed_tool_gateway import resolve_managed_tool_gateway 13 from tools.tool_backend_helpers import managed_nous_tools_enabled, prefers_gateway 14 15 logger = logging.getLogger(__name__) 16 _pending_create_keys: Dict[str, str] = {} 17 _pending_create_keys_lock = threading.Lock() 18 19 _BASE_URL = "https://api.browser-use.com/api/v3" 20 _DEFAULT_MANAGED_TIMEOUT_MINUTES = 5 21 _DEFAULT_MANAGED_PROXY_COUNTRY_CODE = "us" 22 23 24 def _get_or_create_pending_create_key(task_id: str) -> str: 25 with _pending_create_keys_lock: 26 existing = _pending_create_keys.get(task_id) 27 if existing: 28 return existing 29 30 created = f"browser-use-session-create:{uuid.uuid4().hex}" 31 _pending_create_keys[task_id] = created 32 return created 33 34 35 def _clear_pending_create_key(task_id: str) -> None: 36 with _pending_create_keys_lock: 37 _pending_create_keys.pop(task_id, None) 38 39 40 def _should_preserve_pending_create_key(response: requests.Response) -> bool: 41 if response.status_code >= 500: 42 return True 43 44 if response.status_code != 409: 45 return False 46 47 try: 48 payload = response.json() 49 except Exception: 50 return False 51 52 if not isinstance(payload, dict): 53 return False 54 55 error = payload.get("error") 56 if not isinstance(error, dict): 57 return False 58 59 message = str(error.get("message") or "").lower() 60 return "already in progress" in message 61 62 63 class BrowserUseProvider(CloudBrowserProvider): 64 """Browser Use (https://browser-use.com) cloud browser backend.""" 65 66 def provider_name(self) -> str: 67 return "Browser Use" 68 69 def is_configured(self) -> bool: 70 return self._get_config_or_none() is not None 71 72 # ------------------------------------------------------------------ 73 # Config resolution (direct API key OR managed Nous gateway) 74 # ------------------------------------------------------------------ 75 76 def _get_config_or_none(self) -> Optional[Dict[str, Any]]: 77 api_key = os.environ.get("BROWSER_USE_API_KEY") 78 if api_key and not prefers_gateway("browser"): 79 return { 80 "api_key": api_key, 81 "base_url": _BASE_URL, 82 "managed_mode": False, 83 } 84 85 managed = resolve_managed_tool_gateway("browser-use") 86 if managed is None: 87 return None 88 89 return { 90 "api_key": managed.nous_user_token, 91 "base_url": managed.gateway_origin.rstrip("/"), 92 "managed_mode": True, 93 } 94 95 def _get_config(self) -> Dict[str, Any]: 96 config = self._get_config_or_none() 97 if config is None: 98 message = ( 99 "Browser Use requires a direct BROWSER_USE_API_KEY credential." 100 ) 101 if managed_nous_tools_enabled(): 102 message = ( 103 "Browser Use requires either a direct BROWSER_USE_API_KEY " 104 "credential or a managed Browser Use gateway configuration." 105 ) 106 raise ValueError(message) 107 return config 108 109 # ------------------------------------------------------------------ 110 # Session lifecycle 111 # ------------------------------------------------------------------ 112 113 def _headers(self, config: Dict[str, Any]) -> Dict[str, str]: 114 headers = { 115 "Content-Type": "application/json", 116 "X-Browser-Use-API-Key": config["api_key"], 117 } 118 return headers 119 120 def create_session(self, task_id: str) -> Dict[str, object]: 121 config = self._get_config() 122 managed_mode = bool(config.get("managed_mode")) 123 124 headers = self._headers(config) 125 if managed_mode: 126 headers["X-Idempotency-Key"] = _get_or_create_pending_create_key(task_id) 127 128 # Keep gateway-backed sessions short so billing authorization does not 129 # default to a long Browser-Use timeout when Hermes only needs a task- 130 # scoped ephemeral browser. 131 payload = ( 132 { 133 "timeout": _DEFAULT_MANAGED_TIMEOUT_MINUTES, 134 "proxyCountryCode": _DEFAULT_MANAGED_PROXY_COUNTRY_CODE, 135 } 136 if managed_mode 137 else {} 138 ) 139 140 response = requests.post( 141 f"{config['base_url']}/browsers", 142 headers=headers, 143 json=payload, 144 timeout=30, 145 ) 146 147 if not response.ok: 148 if managed_mode and not _should_preserve_pending_create_key(response): 149 _clear_pending_create_key(task_id) 150 raise RuntimeError( 151 f"Failed to create Browser Use session: " 152 f"{response.status_code} {response.text}" 153 ) 154 155 session_data = response.json() 156 if managed_mode: 157 _clear_pending_create_key(task_id) 158 session_name = f"hermes_{task_id}_{uuid.uuid4().hex[:8]}" 159 external_call_id = response.headers.get("x-external-call-id") if managed_mode else None 160 161 logger.info("Created Browser Use session %s", session_name) 162 163 cdp_url = session_data.get("cdpUrl") or session_data.get("connectUrl") or "" 164 165 return { 166 "session_name": session_name, 167 "bb_session_id": session_data["id"], 168 "cdp_url": cdp_url, 169 "features": {"browser_use": True}, 170 "external_call_id": external_call_id, 171 } 172 173 def close_session(self, session_id: str) -> bool: 174 try: 175 config = self._get_config() 176 except ValueError: 177 logger.warning("Cannot close Browser Use session %s — missing credentials", session_id) 178 return False 179 180 try: 181 response = requests.patch( 182 f"{config['base_url']}/browsers/{session_id}", 183 headers=self._headers(config), 184 json={"action": "stop"}, 185 timeout=10, 186 ) 187 if response.status_code in (200, 201, 204): 188 logger.debug("Successfully closed Browser Use session %s", session_id) 189 return True 190 else: 191 logger.warning( 192 "Failed to close Browser Use session %s: HTTP %s - %s", 193 session_id, 194 response.status_code, 195 response.text[:200], 196 ) 197 return False 198 except Exception as e: 199 logger.error("Exception closing Browser Use session %s: %s", session_id, e) 200 return False 201 202 def emergency_cleanup(self, session_id: str) -> None: 203 config = self._get_config_or_none() 204 if config is None: 205 logger.warning("Cannot emergency-cleanup Browser Use session %s — missing credentials", session_id) 206 return 207 try: 208 requests.patch( 209 f"{config['base_url']}/browsers/{session_id}", 210 headers=self._headers(config), 211 json={"action": "stop"}, 212 timeout=5, 213 ) 214 except Exception as e: 215 logger.debug("Emergency cleanup failed for Browser Use session %s: %s", session_id, e)