Docs/SDK/Browser Setup

Browser Setup

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

SentienceBrowser Initialization

from sentience import SentienceBrowser

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

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

# Context manager (auto-closes)
with SentienceBrowser(api_key="sk_...") as browser:
    browser.page.goto("https://example.com")
    # Browser automatically closes when done

Parameters:

api_key / apiKey (optional): Your SentienceAPI 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 sentience import SentienceBrowser

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

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

# Custom viewport for mobile (375x667 - iPhone SE)
browser = SentienceBrowser(viewport={"width": 375, "height": 667})

# Tablet viewport (768x1024 - iPad)
browser = SentienceBrowser(viewport={"width": 768, "height": 1024})

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 SentienceBrowser with your existing Playwright workflows using from_existing() and from_page() class methods.

From Existing BrowserContext

Create a SentienceBrowser from an existing Playwright BrowserContext:

from sentience import SentienceBrowser
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(
        "./user_data",
        headless=False,
        viewport={"width": 1920, "height": 1080}
    )

    # Convert to SentienceBrowser
    browser = SentienceBrowser.from_existing(context)

    # Now you can use all Sentience features
    browser.page.goto("https://example.com")
    from sentience import snapshot, find, click
    snap = snapshot(browser)
    button = find(snap, "role=button text~'Submit'")
    if button:
        click(browser, button.id)

From Existing Page

Create a SentienceBrowser from an existing Playwright Page:

from sentience import SentienceBrowser
from playwright.sync_api import sync_playwright

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

    # Navigate to page first
    page.goto("https://example.com")

    # Convert to SentienceBrowser
    sentience_browser = SentienceBrowser.from_page(page)

    # Use Sentience features on existing page
    from sentience import snapshot, find
    snap = snapshot(sentience_browser)
    links = [e for e in snap.elements if e.role == "link"]
    print(f"Found {len(links)} links on the page")

Use Cases:

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

Benefits:

No need to rewrite existing Playwright code
Mix Playwright's low-level control with Sentience'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 = SentienceBrowser(
    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 = SentienceBrowser(api_key="your_key")
# Automatically uses SENTIENCE_PROXY if set

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 sentience import SentienceBrowser, save_storage_state

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

# Step 2: Use the saved session in future runs
browser = SentienceBrowser(storage_state="auth.json")
browser.start()
# Your agent starts already logged in!

Option 2: Persistent Sessions (Best for Production)

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

# Second run: Agent is already logged in!
browser = SentienceBrowser(user_data_dir="./chrome_profile")
browser.start()
browser.goto("https://example.com/orders")
# No login needed - cookies persist automatically!

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 sentience import SentienceBrowser

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

# All browser actions are now being recorded
browser.page.goto("https://example.com")
browser.page.click("text=Click me")

# Close browser to save the video
video_path = browser.close()
print(f"Video saved to: {video_path}")
# Output: Video saved to: ./recordings/abc123.webm

# Custom resolution (1080p)
browser = SentienceBrowser(
    record_video_dir="./recordings",
    record_video_size={"width": 1920, "height": 1080}
)

# Rename video file
video_path = browser.close(output_path="./my_tutorial.webm")

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

Tracing & Debugging

Snapshot API