peter-gy/pyagentbrowser

pyagentbrowser embeds the native Rust agent-browser engine in a Python process. A Browser controller owns startup, ordered native work, snapshot-scoped element refs, safety policy, direct browser capabilities, and terminal cleanup.

Alpha: The public API and native integration can change between minor releases. Pin a version for production automation.

Quickstart

Install pyagentbrowser from the Python Package Index:

python -m pip install pyagentbrowser

The first local launch selects a configured, cached, or installed Chrome or Chromium executable. When discovery finds none, pyagentbrowser downloads Chrome for Testing. Local browsers run headlessly by default.

from agentbrowser import Browser

with Browser.launch() as browser:
    browser.page.set_content(
        "<button onclick=\"this.textContent='Done'\">Run</button>"
    )
    snapshot = browser.observe()
    result = snapshot.one(role="button", name="Run").click()

    print(result.after.one(role="button").name)
    print(result.diff.changed)

Done
True

The evidence model

Browser.observe() returns an accessibility Snapshot. Each Ref identifies one element inside that snapshot. A ref mutation returns an ActionResult with the source snapshot, resulting snapshot, and their SnapshotDiff.

Snapshot A -> Ref -> action and wait -> Snapshot B -> SnapshotDiff

Use browser.find for live CSS, XPath, role, text, label, placeholder, alternative text, title, and test ID queries. Live queries resolve when each operation runs. Snapshot-scoped refs preserve the inspected page state and add transition evidence.

What you can automate

• Navigate, inspect, and act on pages
• Read documents and capture screenshots, PDFs, diffs, and downloads
• Manage tabs, named sessions, cookies, Web Storage, and restored state
• Route requests, record HTTP Archive files, and inspect diagnostics
• Evaluate targets, frames, and contexts through the Chrome DevTools Protocol
• Invoke page-provided WebMCP tools
• Observe a Python-owned browser session in the dashboard
• Use agent skills and marimo code mode
• Call the raw native protocol

Choose a runtime

Browser is synchronous. AsyncBrowser mirrors its browser, snapshot, ref, query, policy, and capability APIs with awaitable native operations.

Browser.launch() starts a local browser before returning. Browser() starts lazily. Browser.attach(CDPTarget(...)) connects to an existing Chrome DevTools Protocol endpoint. All three paths share the same typed result and lifecycle model.

Installation options

Wheels support Python 3.11 through 3.14 on macOS arm64 and x86-64, manylinux 2.28-compatible Linux arm64 and x86-64, and Windows x86-64.

uv add pyagentbrowser
uv add "pyagentbrowser[images]"  # Pillow image loading for Screenshot
uv add "pyagentbrowser[cdp]"     # Direct Chrome DevTools Protocol clients

Learn and contribute

• What is pyagentbrowser?
• Runtime model
• Safety model
• API reference
• Troubleshooting
• Contributing

Serve the documentation through Portless with make docs-dev. The main checkout uses https://docs.pyagentbrowser.localhost/, while linked worktrees receive a branch-prefixed subdomain.

License

pyagentbrowser is licensed under the Apache License 2.0. See NOTICE for bundled software attribution.