BrowserFabric

Python SDK for BrowserFabric — the cloud browser for AI agents. Run remote sessions with saved context, live human takeover, and tools to observe, act, and verify.

Install

pip install browserfabric

Quick Start

import browserfabric
import asyncio

async def main():
    async with browserfabric.browser(base_url="https://api.browserfabric.com") as session:
        await session.navigate("https://example.com")
        state = await session.observe_page()
        print(state["elements"])

asyncio.run(main())

Agent interface (1.1.0+)

After navigating to your form, use the names in the current observation:

state = await session.observe_page()
submit = next(e["ref"] for e in state["elements"] if e["name"] == "Continue")
result = await session.act(
    state["tab_id"], state["observation_id"],
    [{"type": "click", "ref": submit}],
    wait_for={"text": "Welcome"},
)
print(result["status"])

The sync session exposes the same methods. Use tabs() for explicit tab control, observe_page(since=...) for a diff, browser_screenshot(tab_id) for base64 PNG, and cancel() to interrupt running work.

act preserves recovery observations on tool failures. Check status: verified means your condition matched; completed means actions ran without an outcome check. On failure or interruption, inspect the current page and completed steps before retrying. Transport errors still raise.

SDK-generated request IDs stay the same across transport retries. Explicit IDs must be unique per operation and reused only with identical payloads. Deduplication covers the last 64 requests in the live session, not a backend restart.

Complete interface contract.

The SDK retains its self-hosted default (http://localhost:9000). For the hosted service, set the base URL to https://api.browserfabric.com, as in these examples.

Authentication

Set your API key as an environment variable or pass it directly:

# Via environment variable
export BROWSERFABRIC_API_KEY=bf_your_key_here

# Or pass directly
async with browserfabric.browser(api_key="bf_...") as session:
    ...

Persistent Sessions

Save and restore browser state (cookies, localStorage) across sessions:

# Save state on close
async with browserfabric.browser(base_url="https://api.browserfabric.com", persist=True) as session:
    await session.navigate("https://app.example.com/login")
    await session.type("#email", "user@example.com")
    await session.type("#password", "secret")
    await session.click("#submit")
    ctx = await session.save_context("my-app-login")

# Restore later
async with browserfabric.browser(base_url="https://api.browserfabric.com", context_id=ctx["context_id"]) as session:
    # Already logged in
    await session.navigate("https://app.example.com/dashboard")

CDP WebSocket

Connect with Playwright directly for full browser control:

from playwright.async_api import async_playwright

# Get the CDP WebSocket URL from session info
info = await session.session_info()
ws_url = info["ws_url"]

# Connect with Playwright
pw = await async_playwright().start()
browser = await pw.chromium.connect_over_cdp(ws_url)
page = browser.contexts[0].pages[0]
await page.goto("https://example.com")

Available Methods

Self-Hosted

Point to your own BrowserFabric instance:

async with browserfabric.browser(base_url="http://your-server:9000") as session:
    ...

License

MIT