Metadata-Version: 2.4
Name: pyagentbrowser
Version: 0.31.1rc6
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
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
License-File: NOTICE
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#readme
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: Upstream agent-browser, https://github.com/vercel-labs/agent-browser
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)

pyagentbrowser embeds the native Rust [`agent-browser`](https://github.com/vercel-labs/agent-browser) engine in Python. It gives agents accessibility snapshots, stable element refs, and before-and-after evidence for browser actions.

```bash
uv add pyagentbrowser
```

```python
from agentbrowser import Browser

browser = Browser()
browser.open("https://example.com")
page = browser.observe()

print(page.text)
```

`Browser` starts lazily and stays active until `browser.close()` is called. Keep the same object across notebook cells or interactive Python commands. `browser.session.status()` reports browser and restore lifecycle state. `close()` returns the terminal save result. Screenshots returned by `browser.capture.screenshot()` render inline in notebook frontends.

`Snapshot` binds accessibility refs to the page state that produced them. Ref actions return an `ActionResult` containing the original snapshot, the resulting snapshot, and their diff.

Use `browser.find` for live CSS, XPath, and semantic queries. Namespaces such as `browser.capture`, `browser.tabs`, `browser.network`, and `browser.cdp` expose focused browser capabilities. Every action in the pinned native engine remains available through `browser.native`.

## Documentation

- [Get started](docs/getting-started.md)
- [Guides](docs/guides.md)
- [API reference](docs/api.md)
- [Runnable examples](examples/)

## Installation options

The distribution is named `pyagentbrowser`. Python imports it as `agentbrowser`. Wheels support Python 3.11 through 3.14 on macOS, Linux, and x86-64 Windows.

```bash
uv add "pyagentbrowser[images]"  # Pillow-backed screenshot helpers
uv add "pyagentbrowser[cdp]"     # CDP frames, targets, and evaluation
```

Local launches find an installed Chromium browser or prepare Chrome for Testing through the native installer.

## Development

```bash
make install
make check
```

`make test-integration` exercises the Python, PyO3, adapter, and CDP seams against a real browser. `make check-release` builds and installs both distribution artifacts.

## License

Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

