Browser Use Python SDK

3.4.3 · active · verified Fri Apr 10

The `browser-use-sdk` is the official Python SDK for the Browser Use Cloud API, enabling AI agents to automate complex web tasks. It provides state-of-the-art browser automation with features like stealth browsers, CAPTCHA solving, and residential proxies, allowing for data extraction, form filling, multi-step workflows, and research. The current version is 3.4.3, and it maintains an active release cadence with frequent updates.

Warnings

breaking SDK 3.0 introduced significant breaking changes, particularly affecting client initialization and the main task execution method. Users upgrading from pre-3.0 versions must update their code to use the new `AsyncBrowserUse` client and `client.run()` API, which offers a cleaner interface.
Fix: Migrate client instantiation to `from browser_use_sdk.v3 import AsyncBrowserUse` and adapt task execution to `await client.run('your task')`.
gotcha The SDK requires an API key for interaction with the Browser Use Cloud API. This key (`BROWSER_USE_API_KEY`) is typically read from environment variables. Failing to set a valid key will prevent tasks from running, often leading to errors or the agent getting stuck without clear explanations.
Fix: Ensure `BROWSER_USE_API_KEY` is set in your environment (e.g., `export BROWSER_USE_API_KEY=your_key`) or passed explicitly to the client constructor (`AsyncBrowserUse(api_key='your_key')`). Obtain your key from cloud.browser-use.com/settings.
gotcha The primary SDK client, `AsyncBrowserUse`, is inherently asynchronous. All API calls (e.g., `client.run()`) must be `await`ed within an `async` function. This `async` function must then be executed using an event loop, typically `asyncio.run()`. Attempting synchronous calls will result in runtime errors.
Fix: Wrap your SDK calls in `async def` functions and use `asyncio.run(your_async_function())` to execute them. Ensure Python's `asyncio` patterns are followed.
gotcha A common debugging scenario is the agent getting 'stuck on Step 1' or entering an infinite loop. This often points to issues like an invalid, expired, or out-of-credit API key, the selected LLM model lacking necessary tool-calling functionality, underlying network problems, or enabling vision (`use_vision=True`) with a model that doesn't support it.
Fix: Verify API key validity and credit balance. Check LLM model compatibility for tool-calling and vision features. Diagnose network connectivity. Review debug logs for more specific error messages from the underlying LLM calls.
gotcha While powerful, the SDK might exhibit unreliability when performing intricate web scraping or automation on highly dynamic, JavaScript-heavy websites, or those employing infinite scrolling. This can lead to partial data extraction, inconsistent behavior, or agents failing to navigate correctly on such pages.
Fix: For highly dynamic sites, consider adding explicit wait conditions, increasing timeouts, or carefully crafting prompts to guide the agent through page interactions. Monitor agent behavior closely on complex targets.

Install

pip install browser-use-sdk PyPI

Imports

AsyncBrowserUse
```
from browser_use_sdk.v3 import AsyncBrowserUse
```
The `BrowserUseClient` import pattern was used in older SDK versions (e.g., pre-3.0). Version 3 and above use `AsyncBrowserUse` from the `v3` submodule.

Quickstart

This quickstart demonstrates how to initialize the `AsyncBrowserUse` client and execute a natural language task. It expects the `BROWSER_USE_API_KEY` to be set as an environment variable. The `client.run()` method initiates an AI agent to perform the specified web automation task and returns the result.

import asyncio
import os
from browser_use_sdk.v3 import AsyncBrowserUse

async def main():
    api_key = os.environ.get('BROWSER_USE_API_KEY', '')
    if not api_key:
        print("Error: BROWSER_USE_API_KEY environment variable not set.")
        print("Please get your API key at cloud.browser-use.com/settings and set it.")
        return

    # The SDK automatically picks up BROWSER_USE_API_KEY from environment variables.
    # Alternatively, pass it explicitly: client = AsyncBrowserUse(api_key=api_key)
    client = AsyncBrowserUse()
    
    try:
        # Run an AI agent task with natural language instructions
        result = await client.run("Find the top 3 trending repositories on GitHub today and list their names and URLs")
        print("Agent Output:", result.output)
    except Exception as e:
        print(f"An error occurred during agent execution: {e}")

if __name__ == "__main__":
    asyncio.run(main())

view raw JSON →