Skip to content

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

Support Anthropic driver with Browser Use Cloud

Gregor Žunič7ad29205f9db
diff --git a/browser_use/browser/cloud/cloud.py b/browser_use/browser/cloud/cloud.py
index c9670394d..ddf264298 100644
--- a/browser_use/browser/cloud/cloud.py
+++ b/browser_use/browser/cloud/cloud.py
@@ -35,7 +35,7 @@ class CloudBrowserClient:
Returns:
CloudBrowserResponse: Contains CDP URL and other browser info
"""
- url = f'{self.api_base_url}/api/v2/browsers'
+ url = f'{self.api_base_url}/api/v3/browsers'
# Try to get API key from environment variable first, then auth config
api_token = os.getenv('BROWSER_USE_API_KEY')
@@ -124,7 +124,7 @@ class CloudBrowserClient:
if not session_id:
raise CloudBrowserError('No session ID provided and no current session available')
- url = f'{self.api_base_url}/api/v2/browsers/{session_id}'
+ url = f'{self.api_base_url}/api/v3/browsers/{session_id}'
# Try to get API key from environment variable first, then auth config
api_token = os.getenv('BROWSER_USE_API_KEY')
diff --git a/browser_use/browser/cloud/views.py b/browser_use/browser/cloud/views.py
index 20459c369..0751bb2a7 100644
--- a/browser_use/browser/cloud/views.py
+++ b/browser_use/browser/cloud/views.py
@@ -76,8 +76,9 @@ class CloudBrowserResponse(BaseModel):
id: str
status: str
- liveUrl: str = Field(alias='liveUrl')
- cdpUrl: str = Field(alias='cdpUrl')
+ # V3 clears connection URLs after a browser stops.
+ liveUrl: str | None = Field(alias='liveUrl')
+ cdpUrl: str | None = Field(alias='cdpUrl')
timeoutAt: str = Field(alias='timeoutAt')
startedAt: str = Field(alias='startedAt')
finishedAt: str | None = Field(alias='finishedAt', default=None)
diff --git a/browser_use/browser/session.py b/browser_use/browser/session.py
index 379663c47..30070cefc 100644
--- a/browser_use/browser/session.py
+++ b/browser_use/browser/session.py
@@ -806,6 +806,8 @@ class BrowserSession(BaseModel):
# Use cloud_browser_params if provided, otherwise create empty request
cloud_params = self.browser_profile.cloud_browser_params or CreateBrowserRequest()
cloud_browser_response = await self._cloud_browser_client.create_browser(cloud_params)
+ if not cloud_browser_response.cdpUrl:
+ raise CloudBrowserError('Cloud browser response did not include a CDP URL')
self.browser_profile.cdp_url = cloud_browser_response.cdpUrl
self.browser_profile.is_local = False
self.logger.info('🌤️ Successfully connected to cloud browser service')
diff --git a/browser_use/integrations/anthropic/browser_use.py b/browser_use/integrations/anthropic/browser_use.py
index 6e5d7e60b..bc7cf1a6d 100644
--- a/browser_use/integrations/anthropic/browser_use.py
+++ b/browser_use/integrations/anthropic/browser_use.py
@@ -51,15 +51,18 @@ class Reference:
class BrowserUse(BetaAsyncAbstractBrowserToolset20260801):
"""Expose Browser Use as the Anthropic 31-member browser toolset.
- With no argument, Browser Use creates and manages a BrowserSession. A supplied
- BrowserSession is borrowed and must already be running. ``document_resolver``
- maps policy-approved document IDs to files visible on the browser host.
+ With no argument, Browser Use creates and manages a local BrowserSession. Pass
+ ``use_cloud=True`` to create and manage a Browser Use Cloud session instead. A
+ supplied BrowserSession is borrowed and must already be running.
+ ``document_resolver`` maps policy-approved document IDs to files visible on the
+ browser host.
"""
def __init__(
self,
browser: BrowserSession | None = None,
*,
+ use_cloud: bool = False,
document_resolver: Callable[[str], str] | None = None,
max_log_entries: int = 1000,
**options: Any,
@@ -72,8 +75,10 @@ class BrowserUse(BetaAsyncAbstractBrowserToolset20260801):
file_upload_config = configs.setdefault('file_upload', {})
file_upload_config.setdefault('enabled', False)
super().__init__(configs=configs, **options)
+ if browser is not None and use_cloud:
+ raise ValueError('Pass either a BrowserSession or use_cloud=True, not both.')
self._manages_browser = browser is None
- self.browser = browser or BrowserSession()
+ self.browser = browser or BrowserSession(use_cloud=use_cloud)
self._document_resolver = document_resolver
self._released = False
self._closing = False
diff --git a/examples/integrations/anthropic/README.md b/examples/integrations/anthropic/README.md
index 99fac98f9..4ca80120d 100644
--- a/examples/integrations/anthropic/README.md
+++ b/examples/integrations/anthropic/README.md
@@ -38,10 +38,30 @@ async with browser, AsyncAnthropic() as client:
existing session, pass it as `BrowserUse(session)`; the application keeps
responsibility for starting and stopping that session.
-## Existing, remote, or Cloud browser
+## Browser Use Cloud
+
+Set `BROWSER_USE_API_KEY` and select Cloud directly on the driver:
+
+```python
+browser = BrowserUse(use_cloud=True)
+bash = Bash(output_dir='outputs')
+
+async with browser, AsyncAnthropic() as client:
+ runner = client.beta.messages.tool_runner(
+ model=model,
+ tools=[browser, bash],
+ messages=[{'role': 'user', 'content': task}],
+ )
+ result = await runner.until_done()
+```
+
+The driver creates the Cloud browser, connects over CDP, and stops the Cloud
+browser when the context exits.
+
+## Existing or remote browser
Pass any started `BrowserSession` to the driver. This is the same shape for an
-existing local browser, a remote CDP endpoint, and Browser Use Cloud:
+existing local browser or a remote CDP endpoint:
```python
import os
@@ -67,10 +87,9 @@ finally:
await session.kill()
```
-For Browser Use Cloud, construct the session with `BrowserSession(use_cloud=True)`
-instead. Set `BROWSER_USE_API_KEY` before starting it. Bash still runs beside
-the SDK process, so files it creates are local to that process. Remote uploads
-need a browser-host path or an application `document_resolver`.
+Bash still runs beside the SDK process, so files it creates are local to that
+process. Remote uploads need a browser-host path or an application
+`document_resolver`.
## Approval callback
diff --git a/tests/ci/browser/test_cloud_browser.py b/tests/ci/browser/test_cloud_browser.py
index 4b30d38d6..7ff0dcaef 100644
--- a/tests/ci/browser/test_cloud_browser.py
+++ b/tests/ci/browser/test_cloud_browser.py
@@ -81,6 +81,7 @@ class TestCloudBrowserClient:
# Verify auth headers were included
mock_client.post.assert_called_once()
call_args = mock_client.post.call_args
+ assert call_args.args[0] == 'https://api.browser-use.com/api/v3/browsers'
assert 'X-Browser-Use-API-Key' in call_args.kwargs['headers']
assert call_args.kwargs['headers']['X-Browser-Use-API-Key'] == 'test-token'
@@ -172,8 +173,8 @@ class TestCloudBrowserClient:
mock_response_data = {
'id': 'test-browser-id',
'status': 'stopped',
- 'liveUrl': 'https://live.browser-use.com?wss=test',
- 'cdpUrl': 'wss://test.proxy.daytona.works',
+ 'liveUrl': None,
+ 'cdpUrl': None,
'timeoutAt': '2025-09-17T04:35:36.049892',
'startedAt': '2025-09-17T03:35:36.049974',
'finishedAt': '2025-09-17T04:35:36.049892',
@@ -197,12 +198,14 @@ class TestCloudBrowserClient:
assert result.id == 'test-browser-id'
assert result.status == 'stopped'
+ assert result.liveUrl is None
+ assert result.cdpUrl is None
assert result.finishedAt is not None
# Verify correct API call
mock_client.patch.assert_called_once()
call_args = mock_client.patch.call_args
- assert 'test-browser-id' in call_args.args[0] # URL contains session ID
+ assert call_args.args[0] == 'https://api.browser-use.com/api/v3/browsers/test-browser-id'
assert call_args.kwargs['json'] == {'action': 'stop'}
assert 'X-Browser-Use-API-Key' in call_args.kwargs['headers']
diff --git a/tests/ci/integrations/test_anthropic_browser_use.py b/tests/ci/integrations/test_anthropic_browser_use.py
index 2408ce385..9c2eef7f8 100644
--- a/tests/ci/integrations/test_anthropic_browser_use.py
+++ b/tests/ci/integrations/test_anthropic_browser_use.py
@@ -100,6 +100,24 @@ def test_browser_use_and_bash_construct_with_a_compatible_sdk() -> None:
assert bash.to_dict()['name'] == 'bash'
+def test_browser_use_can_own_a_cloud_browser() -> None:
+ pytest.importorskip('anthropic.tools.browser')
+ from browser_use.integrations.anthropic import BrowserUse
+
+ browser = BrowserUse(use_cloud=True)
+ assert browser._manages_browser is True
+ assert browser.browser.browser_profile.use_cloud is True
+
+
+def test_browser_use_rejects_a_borrowed_browser_with_cloud_selection() -> None:
+ pytest.importorskip('anthropic.tools.browser')
+ from browser_use import BrowserSession
+ from browser_use.integrations.anthropic import BrowserUse
+
+ with pytest.raises(ValueError, match='either a BrowserSession or use_cloud=True'):
+ BrowserUse(BrowserSession(), use_cloud=True)
+
+
def _tabs(active: str) -> list[dict]:
return [
{'tab_id': 'tab-a', 'url': 'https://a.example', 'title': 'A', 'active': active == 'tab-a'},