Skip to main content

Add Browser Capabilities to AI with Browser Use

Browser Use is a Python library that allows AI agents to control a browser. By integrating Browserless with Browser Use, you can provide your AI applications with powerful web browsing capabilities without managing browser infrastructure.

Prerequisites​

  • Python 3.11 or higher
  • An active Browserless API Token (available in your account dashboard)

Step-by-Step Setup​

1. Get your API Key

Go to your Browserless Account Dashboard and copy your API token.

Then set the BROWSERLESS_API_TOKEN environment variable in your .env file:

BROWSERLESS_API_TOKEN=your-token-here
OPENAI_API_KEY=your-openai-key-here
2. Create a virtual environment

Set up a Python virtual environment to manage your dependencies:

uv venv --python 3.11
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
3. Install required packages

Install Browser Use and other required packages:

uv add browser-use python-dotenv
4. Create the main.py file

Create a new file named main.py with the following complete code:

from browser_use import Agent, BrowserSession
from browser_use.llm import ChatOpenAI
from dotenv import load_dotenv
import os
import asyncio

load_dotenv()

async def main():
    # Get the token from environment variables
    browserless_token = os.getenv('BROWSERLESS_API_TOKEN')
    if not browserless_token:
        raise ValueError("BROWSERLESS_API_TOKEN environment variable is required")
    
    browser_session = BrowserSession(cdp_url=f"wss://production-sfo.browserless.io?token={browserless_token}")

    llm = ChatOpenAI(model="gpt-4o-mini", api_key=os.getenv('OPENAI_API_KEY'))

    agent = Agent(
        task="find me the top cheapest trainer on ebay.co.uk",
        llm=llm,
        browser_session=browser_session
    )
    result = await agent.run()
    print(result)

if __name__ == "__main__":
    asyncio.run(main())
5. Run your application

Run your application with the following command:

python main.py

You should see output indicating that the browser is initialized and the agent is running.

How It Works​

1. Connection Setup: Browser Use connects to Browserless using the WebSocket endpoint with your API token 2. Agent Configuration: The AI agent is configured with a task and a language model 3. Automation: The agent uses the browser to navigate and interact with websites 4. LLM Integration: The agent leverages an LLM (like GPT-4o) to interpret web content and make decisions

Additional Configuration​

Proxy Support​

You can enable a residential proxy for improved website compatibility:

browser_session = BrowserSession(cdp_url=f"wss://production-sfo.browserless.io?token={os.environ['BROWSERLESS_API_TOKEN']}&proxy=residential")

Browser Session Configuration​

Customize the browser session with additional settings:

from browser_use import BrowserSession
from browser_use.browser import BrowserProfile

browser_session = BrowserSession(
    cdp_url=f"wss://production-sfo.browserless.io?token={os.environ['BROWSERLESS_API_TOKEN']}",
    browser_profile=BrowserProfile(
        user_agent="Custom User Agent",
        viewport_size={"width": 1920, "height": 1080},
        headless=True,
    )
)

Advanced Configuration Options​

Using Different Browserless Regions​

You can connect to different Browserless regions for better performance:

# US West Coast (default)
browser_session = BrowserSession(cdp_url=f"wss://production-sfo.browserless.io?token={browserless_token}")

# Europe (London)
browser_session = BrowserSession(cdp_url=f"wss://production-lon.browserless.io?token={browserless_token}")

Stealth Mode and Proxy Support​

Enable stealth mode and residential proxies for better website compatibility:

browser_session = BrowserSession(
    cdp_url=f"wss://production-sfo.browserless.io?token={browserless_token}&stealth=true&proxy=residential"
)

Custom Browser Configuration​

Configure browser settings using BrowserProfile:

from browser_use.browser import BrowserProfile

browser_session = BrowserSession(
    cdp_url=f"wss://production-sfo.browserless.io?token={browserless_token}",
    browser_profile=BrowserProfile(
        user_agent="Custom User Agent",
        viewport_size={"width": 1920, "height": 1080},
        headless=True,
    )
)

Complete Example with Cloud Browser​

Here's a complete example that demonstrates the modern BrowserSession approach:

"""Simple browser-use + Browserless.io connection example"""

import asyncio
import os
from browser_use import Agent
from browser_use.browser import BrowserSession
from browser_use.llm import ChatOpenAI

async def main():
    # Setup LLM
    llm = ChatOpenAI(model="gpt-4o-mini", api_key=os.getenv('OPENAI_API_KEY'))
    
    # Setup browser session (cloud or local)
    browser_session = None
    if os.getenv('BROWSERLESS_WS_URL') and os.getenv('BROWSERLESS_API_TOKEN'):
        # Use Browserless.io cloud browser
        url = f"{os.getenv('BROWSERLESS_WS_URL')}?token={os.getenv('BROWSERLESS_API_TOKEN')}"
        browser_session = BrowserSession(cdp_url=url)
        print("🌐 Using cloud browser")
    else:
        print("🏠 Using local browser")
    
    # Create and run agent
    agent = Agent(
        task="Go to example.com and tell me the main heading",
        llm=llm,
        browser_session=browser_session
    )
    
    result = await agent.run(max_steps=5)
    print(f"✅ Done! Result: {type(result).__name__}")

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

For more information about browser automation with Browserless, please refer to:

Advanced Usage​

For more advanced usage scenarios, please refer to: