pyagentbrowser 0.27.1rc0

Python SDK for controlling the native agent-browser engine in-process

pyagentbrowser

Python bindings for the native Rust agent-browser engine, exposing snapshots, element refs, action evidence, browser state, and policy confirmations without shelling out.

The distribution is pyagentbrowser. The import package is agentbrowser.

Install

uv add pyagentbrowser
# or
python -m pip install pyagentbrowser

Requires Python 3.10 through 3.14 and a Chrome/Chromium browser available to agent-browser. See docs/install.md for Chrome and source build notes.

Basic Usage

from agentbrowser import Browser

with Browser(headless=True) as browser:
    browser.page.open("https://example.com")
    page = browser.agent.observe()
    print(page.text)

    browser.find.text("More information").click()

Default Session

For notebooks, scripts, and REPLs:

import agentbrowser as ab

ab.configure(headless=True, allowed_domains="*.example.com")
ab.page.open("example.com")

page = ab.agent.observe()
ab.find.text("More information").click()

print(ab.page.title(), ab.page.url())
ab.close()

The root helpers are namespace proxies over one process-local default Browser. They expose the same synchronous namespaces as Browser, including ab.page, ab.agent, ab.find, ab.capture, ab.tabs, ab.frames, ab.cdp, ab.network, ab.cookies, ab.storage, ab.scripts, and ab.diagnostics.

In notebooks, interrupted runs can leave the process-local default browser in a bad native state. Use ab.reset(force=True) to discard it, or pass force=True to ab.configure(...) when replacing it.

When attaching to a running Chrome, configure connects immediately so tab and state helpers are available before navigation:

browser = ab.configure(cdp_port=9222)
print(browser.tabs.list())

For notebook scratchpads, labelled tabs and XPath locators cover repeatable page exploration without one-off JavaScript glue:

browser.tabs.open("https://example.com", label="scratch")
browser.page.ready(timeout_ms=15_000)

print(browser.find.xpath("//h1").text())
print(browser.find.xpath("//a[contains(., 'More information')]").attribute("href"))

Snapshot Refs And Evidence

from agentbrowser import Browser

with Browser(headless=True) as browser:
    browser.launch()
    browser.page.set_content(
        """
        <label>Email <input aria-label="Email" /></label>
        <label>Password <input aria-label="Password" type="password" /></label>
        <button onclick="document.body.dataset.done = 'yes'">Continue</button>
        <p aria-live="polite"></p>
        <script>
        document.querySelector("button").addEventListener("click", () => {
          document.querySelector("p").textContent = "Signed in"
        })
        </script>
        """
    )

    page = browser.agent.observe()
    page.find(name="Email").fill("[e-mail]")
    page.find(name="Password").fill("correct horse battery staple")

    evidence = page.find(role="button", name="Continue", exact=True).click_and_observe(
        wait_for_text="Signed in"
    )
    print(evidence.after.text)
    print(evidence.diff.text)

Snapshot refs belong to the page state that produced them. After navigation or large DOM changes, take a fresh snapshot. After click_and_observe(), continue from evidence.after.

Optional Extras

uv add "pyagentbrowser[images]"  # Screenshot.image and Screenshot.pil()
uv add "pyagentbrowser[cdp]"     # frame/context evaluation via browser.cdp

shot = browser.capture.screenshot("page.png", full_page=True)
print(shot.path, shot.bytes())

frame = browser.frames.get(selector="#target-frame")
print(frame.evaluate("location.href"))
print(browser.cdp.evaluate("document.title", frame="#target-frame"))

Headless Chromium screenshots hide native scrollbars by default. Construct Browser(hide_scrollbars=False) when scrollbars are part of the artifact.

Tool Boundary

Use pyagentbrowser when Python code needs native agent-browser artifacts in-process. Use browser-use for autonomous agent loops, Playwright for deterministic browser testing, Selenium for WebDriver/Grid infrastructure, and the upstream agent-browser CLI for shell workflows and starting the dashboard UI. See docs/choosing-a-tool.md.

Links

• Install
• Documentation index
• Quickstart
• Concepts
• API reference
• Examples
• Choosing a tool
• Development
• Security
• Upstream tracking