Metadata-Version: 2.4
Name: pyagentbrowser
Version: 0.27.1rc0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Typing :: Typed
Requires-Dist: typing-extensions>=4.14.0
Requires-Dist: websockets>=15.0 ; extra == 'cdp'
Requires-Dist: pillow>=12.0 ; extra == 'images'
Provides-Extra: cdp
Provides-Extra: images
License-File: LICENSE
Summary: Python SDK for controlling the native agent-browser engine in-process
Keywords: agent-browser,browser automation,evidence,refs,snapshots
Author-email: Péter Ferenc Gyarmati <dev.petergy@gmail.com>
License-Expression: Apache-2.0
Requires-Python: >=3.10, <3.15
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://github.com/peter-gy/pyagentbrowser/blob/main/docs/index.md
Project-URL: Homepage, https://github.com/peter-gy/pyagentbrowser
Project-URL: Issues, https://github.com/peter-gy/pyagentbrowser/issues
Project-URL: Repository, https://github.com/peter-gy/pyagentbrowser
Project-URL: Security, https://github.com/peter-gy/pyagentbrowser/security/policy
Project-URL: Upstream agent-browser commit, https://github.com/vercel-labs/agent-browser/commit/90050f2
Project-URL: agent-browser CDP mode, https://agent-browser.dev/cdp-mode
Project-URL: agent-browser commands, https://agent-browser.dev/commands
Project-URL: agent-browser docs, https://agent-browser.dev/

# 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

```bash
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](docs/install.md) for Chrome and source
build notes.

## Basic Usage

```python
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:

```python
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:

```python
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:

```python
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

```python
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("ada@example.com")
    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

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

```python
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](docs/choosing-a-tool.md).

## Links

- [Install](docs/install.md)
- [Documentation index](docs/index.md)
- [Quickstart](docs/quickstart.md)
- [Concepts](docs/concepts.md)
- [API reference](docs/api-reference.md)
- [Examples](examples/)
- [Choosing a tool](docs/choosing-a-tool.md)
- [Development](docs/development.md)
- [Security](SECURITY.md)
- [Upstream tracking](docs/internals/upstream.md)

