Metadata-Version: 2.4
Name: pyagentbrowser
Version: 0.31.1rc0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
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: 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.11, <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/ed2e105
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

[![PyPI](https://img.shields.io/pypi/v/pyagentbrowser.svg?label=pip&logo=PyPI&logoColor=white)](https://pypi.org/project/pyagentbrowser/)
[![Release Check](https://github.com/peter-gy/pyagentbrowser/actions/workflows/check-release.yml/badge.svg)](https://github.com/peter-gy/pyagentbrowser/actions/workflows/check-release.yml)
[![License](https://img.shields.io/github/license/peter-gy/pyagentbrowser)](LICENSE)

The `pyagentbrowser` distribution drives the native Rust `agent-browser` engine
from Python. Import it as `agentbrowser`. It exposes page navigation, browser
snapshots, element refs, action evidence, screenshots, cookies, storage, native
active-frame state, and CDP helpers through one Python package.

```bash
python -m pip install pyagentbrowser
```

Requires Python 3.11 through 3.14 on macOS or Linux, with Chrome or Chromium
available on the host.

## Usage

```python
from agentbrowser import Browser, LaunchOptions

with Browser.launch(LaunchOptions(headless=True)) as browser:
    browser.page.set_content(
        """
        <h1>Example catalog</h1>
        <button>More information</button>
        <p id="status"></p>
        <script>
        document.querySelector("button").addEventListener("click", () => {
          document.querySelector("#status").textContent = "Details loaded"
        })
        </script>
        """
    )

    page = browser.agent.observe()
    print(page.text)

    browser.find.text("More information").click()
    print(browser.find.css("#status").text())
```

Snapshot refs stay tied to the page state that created them. After navigation
or a large DOM update, call `browser.agent.observe()` again and continue from
the new snapshot.

For notebooks and REPL sessions, `agentbrowser.notebook` exposes one process-local
default browser:

```python
import agentbrowser as ab
from agentbrowser import LaunchOptions

ab.notebook.configure(launch_options=LaunchOptions(headless=True))
ab.notebook.page.set_content(
    """
    <h1>Notebook page</h1>
    <button>More information</button>
    <p id="status"></p>
    <script>
    document.querySelector("button").addEventListener("click", () => {
      document.querySelector("#status").textContent = "Notebook details loaded"
    })
    </script>
    """
)

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

print(page.text)
print(ab.notebook.find.css("#status").text())
ab.notebook.close()
```

Use `ab.notebook.reset(force=True)` after an interrupted notebook run when the native
browser state should be discarded.

## Capabilities

- **Native browser control:** Launch Chrome, attach over CDP, navigate pages,
  switch tabs, wait for readiness, and close sessions.
- **Snapshot-driven actions:** Observe an accessibility snapshot, find refs by
  text, role, name, CSS, or XPath, then fill, click, press, or inspect the
  matching element.
- **Evidence after actions:** Use `click_and_observe()` to capture the next
  page snapshot and a text diff after a click.
- **Artifacts and state:** Capture screenshots, save and restore browser state,
  derive stable session ids, inspect cookies, storage, network entries, CDP
  frames, and native active-frame state.
- **Typed escape hatches:** Call `browser.native.execute(action, **params)` for
  raw native responses, or use `browser.cdp` for CDP frame and
  execution-context work.

## Optional Extras

```bash
python -m pip install "pyagentbrowser[images]"
python -m pip install "pyagentbrowser[cdp]"
```

`images` adds Pillow helpers for screenshots. `cdp` adds websocket-backed CDP
frame and context evaluation.

## Resources

- [Install](docs/install.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)

