Docs/SDK/Browser Setup

Browser Setup

Learn how to initialize and configure the PredicateBrowser for your automation needs.

PredicateBrowser Initialization

from predicate import PredicateBrowser

# Free tier (local processing only)
browser = PredicateBrowser(headless=False)

# Pro tier (server-side processing)
browser = PredicateBrowser(api_key="sk_...",

Parameters:

  • api_key / apiKey (optional): Your Predicate Systems subscription key. Required for Pro/Enterprise features.
  • api_url / apiUrl (optional): Custom API endpoint. Defaults to https://api.sentienceapi.com.
  • headless (optional): Run browser in headless mode. Auto-detects based on environment.
  • viewport (optional): Browser viewport size. Defaults to {"width": 1280, "height": 800}.

Viewport Configuration

Configure the browser viewport size to match your target screen resolution. The default viewport is 1280x800, which works well for most websites.

from predicate import PredicateBrowser

# Default viewport (1280x800)
browser = PredicateBrowser()

# Custom viewport for desktop (1920x1080)
browser = PredicateBrowser(viewport={"width": 1920, "height": 1080})

Common Viewport Sizes:

  • Desktop HD: 1920x1080
  • Desktop Standard: 1280x800 (default)
  • Laptop: 1366x768
  • iPad: 768x1024
  • iPhone SE: 375x667
  • iPhone 12/13: 390x844

Why viewport matters:

  • Responsive websites render differently at different sizes
  • Some elements may be hidden on mobile viewports
  • Desktop viewports show more content above the fold
  • Consistent viewport ensures reproducible automation

Working with Existing Playwright Contexts

NEW in v0.90.16: Integrate PredicateBrowser with your existing Playwright workflows using from_existing() and from_page() class methods.

From Existing BrowserContext

Create a PredicateBrowser from an existing Playwright BrowserContext:

from predicate import PredicateBrowser
from playwright.sync_api import sync_playwright

# Create Playwright context with custom settings
with sync_playwright() as p:
    # Launch with custom settings
    context = p.chromium.launch_persistent_context(

From Existing Page

Create a PredicateBrowser from an existing Playwright Page:

from predicate import PredicateBrowser
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=False)
    context = browser.

Use Cases:

  • Integrate Predicate into existing Playwright test suites
  • Add semantic element detection to legacy automation scripts
  • Use Predicate features alongside custom Playwright logic
  • Migrate gradually from Playwright to Predicate

Benefits:

  • No need to rewrite existing Playwright code
  • Mix Playwright's low-level control with Predicate's semantic queries
  • Leverage existing browser contexts and authentication
  • Incremental adoption path

Residential Proxy Support

If you're running your agents from a datacenter (AWS, DigitalOcean, etc.), your IP address may be flagged by anti-bot services like Cloudflare. Using a residential proxy routes your traffic through a residential IP address, making your agent appear more like a regular user.

# Method 1: Pass proxy directly when creating browser
browser = PredicateBrowser(
    api_key="your_key",
    proxy="http://username:password@proxy.example.com:8080"
)

# Method 2: Use environment variable (easier for production)
# export SENTIENCE_PROXY="http://username:password@proxy.example.com:8080"
browser = PredicateBrowser(api_key="your_key")

Supported proxy formats:

  • HTTP: http://user:pass@proxy.com:8080
  • HTTPS: https://user:pass@proxy.com:8443
  • SOCKS5: socks5://user:pass@proxy.com:1080

What happens automatically:

  • All browser traffic routes through the proxy (including the extension)
  • WebRTC leak protection prevents your real IP from being exposed
  • Self-signed SSL certificates are automatically accepted (common with residential proxies)
  • Works seamlessly with agents - no code changes needed

Authentication Session Injection

Save time and tokens by starting your agent already logged in! Instead of having your agent click through login screens (which costs 5-10 steps and hundreds of tokens), you can inject a pre-saved authentication session.

Option 1: Pre-recorded Session (Best for Testing)

from predicate import PredicateBrowser, save_storage_state

# Step 1: Log in manually and save the session
browser = PredicateBrowser()
browser.start()
browser.goto("https://example.com")
# ... log in manually in the browser window ...
save_storage_state(browser.context,

Option 2: Persistent Sessions (Best for Production)

# First run: Agent logs in, session is saved
browser = PredicateBrowser(user_data_dir="./chrome_profile")
browser.start()
browser.goto("https://example.com")
agent.act("Click sign in")
agent.act("Type email"

Benefits:

  • Skip login steps: Save 5-10 agent actions and hundreds of tokens per run
  • Bypass CAPTCHAs: Valid sessions often bypass bot detection
  • Reduce costs: No need to pay for login actions
  • Access authenticated pages: Agent can access "My Orders", "My Account", etc.

Video Recording

Record your browser automation sessions as video files! This is perfect for creating tutorial videos, debugging automation failures, monitoring agent behavior, and generating documentation.

from predicate import PredicateBrowser

# Enable video recording by specifying output directory
browser = PredicateBrowser(record_video_dir="./recordings")
browser.start()

# All browser actions are now being recorded
browser.page.goto("https://example.com")
browser.

Video Format:

  • Videos are saved in WebM format (VP8 codec)
  • Compatible with most video players and browsers
  • Can be converted to MP4 using ffmpeg if needed

Tips:

  • The output directory is created automatically if it doesn't exist
  • Video files are only finalized when the browser closes
  • Each browser session creates one video file
  • Use descriptive filenames with output_path for easier organization
  • For high-quality marketing videos, use 1920x1080 resolution
Previous
Agent Quick Start
Next
Predicate Debugger Integration