Browser

Browser Sessions provide direct access to Chrome browsers via DevTools Protocol (CDP), enabling advanced automation and custom browser control.

What is a Browser Session?

A raw browser instance with:

• CDP URL: Direct Chrome DevTools Protocol access
• Live URL: Real-time browser viewing
• Timeout-based lifecycle: Automatic cleanup after inactivity
• Profile support: Inherit saved browser state

Unlike AI agent sessions, browser sessions give you direct programmatic control.

Key Properties

• id: Unique browser session identifier
• status: "active" or "stopped"
• cdpUrl: Chrome DevTools Protocol URL for automation
• liveUrl: Real-time browser viewing URL
• timeoutAt: When the session will automatically stop

Creating Browser Sessions

1
import { BrowserUseClient } from "browser-use-sdk";
2
3
const client = new BrowserUseClient({ apiKey: "bu_..." });
4
5
// Basic browser session
6
const browserSession = await client.browsers.createBrowserSession({
7
    timeout: 30 // minutes
8
});
9
10
// With profile (inherit login state)
11
const profileBrowser = await client.browsers.createBrowserSession({
12
    profileId: "profile_123",
13
    proxyCountryCode: "US",
14
    timeout: 60
15
});
16
17
console.log(`CDP URL: ${browserSession.cdpUrl}`);
18
console.log(`Watch live: ${browserSession.liveUrl}`);

Using CDP for Automation

1
import { chromium } from 'playwright';
2
3
// Connect to the browser session
4
const browser = await chromium.connectOverCDP(browserSession.cdpUrl);
5
const context = browser.contexts()[0];
6
const page = context.pages()[0];
7
8
// Direct browser automation
9
await page.goto('https://example.com');
10
await page.fill('#username', 'admin');
11
await page.fill('#password', 'secret');
12
await page.click('#login');
13
14
// Take screenshot
15
const screenshot = await page.screenshot();
16
17
// Close when done
18
await browser.close();

Managing Browser Sessions

1
// List all browser sessions
2
const sessions = await client.browsers.listBrowserSessions();
3
4
// Get specific session
5
const session = await client.browsers.getBrowserSession(sessionId);
6
7
// Stop session
8
await client.browsers.updateBrowserSession(sessionId, { action: "stop" });
9
10
// Filter by status
11
const activeSessions = await client.browsers.listBrowserSessions({
12
    filterBy: "active"
13
});

Automation Libraries

Browser sessions work with any CDP-compatible automation library:

Playwright:

1
import { chromium } from 'playwright';
2
const browser = await chromium.connectOverCDP(cdpUrl);

Puppeteer:

1
import puppeteer from 'puppeteer';
2
const browser = await puppeteer.connect({ browserWSEndpoint: cdpUrl });

Selenium:

1
from selenium import webdriver
2
from urllib.parse import urlparse
3
4
options = webdriver.ChromeOptions()
5
parsed_url = urlparse(cdp_url)
6
debugger_address = f"{parsed_url.hostname}:{parsed_url.port}"
7
options.add_experimental_option("debuggerAddress", debugger_address)
8
driver = webdriver.Chrome(options=options)

Browser vs Agent Sessions

Browser Sessions (Direct Control):

• Raw CDP access for custom automation
• Use your own automation scripts
• Full control over browser behavior
• Requires programming automation logic

Agent Sessions (AI-Powered):

• AI agent executes natural language instructions
• Separate AI-powered automation system
• Automatic task completion
• No programming required

Common Use Cases

Custom Automation Workflows:

1
const browser = await client.browsers.createBrowserSession({ timeout: 60 });
2
const pwBrowser = await chromium.connectOverCDP(browser.cdpUrl);
3
4
// Multi-step custom workflow
5
const page = pwBrowser.contexts()[0].pages()[0];
6
await page.goto('https://admin.example.com');
7
await page.waitForSelector('#dashboard');
8
9
// Custom data extraction
10
const data = await page.evaluate(() => {
11
    return Array.from(document.querySelectorAll('.metric')).map(el => ({
12
        label: el.querySelector('.label').textContent,
13
        value: el.querySelector('.value').textContent
14
    }));
15
});
16
17
console.log('Extracted metrics:', data);

Integration Testing:

1
// Create browser for testing
2
const browser = await client.browsers.createBrowserSession({
3
    profileId: testProfileId,
4
    timeout: 30
5
});
6
7
// Run test suite
8
const playwright = await chromium.connectOverCDP(browser.cdpUrl);
9
await runTestSuite(playwright);
10
11
// Cleanup
12
await client.browsers.updateBrowserSession(browser.id, { action: "stop" });

Web Scraping with State:

1
// Browser with login profile
2
const browser = await client.browsers.createBrowserSession({
3
    profileId: "logged_in_profile",
4
    proxyCountryCode: "US"
5
});
6
7
// Already logged in from profile
8
const page = (await chromium.connectOverCDP(browser.cdpUrl)).contexts()[0].pages()[0];
9
await page.goto('https://protected-data.example.com');
10
11
// Scrape authenticated content
12
const protectedData = await page.locator('.protected-content').textContent();

Best Practices

Session Management:

• Set appropriate timeouts based on task duration
• Always stop sessions when done to free resources
• Use profiles to preserve login state across sessions

Automation:

• Handle network errors and timeouts gracefully
• Use explicit waits for dynamic content
• Take screenshots for debugging

Performance:

• Reuse profiles to avoid repeated login flows
• Close sessions promptly to avoid timeout charges
• Use appropriate proxy locations for target websites

Security:

• Don’t expose CDP URLs publicly
• Use profiles to isolate different users
• Monitor session usage for suspicious activity

Next Steps