What is pyagentbrowser?
pyagentbrowser embeds the native Rust agent-browser engine in a Python process. The pyagentbrowser distribution installs the agentbrowser import package, a typed Python API, the native engine, browser lifecycle management, safety policy, and action evidence.
The central object is a Browser controller. It owns a native session, which sends ordered actions to a local browser process or an attached browser. A Page binds one browser target, while a Frame binds one child browsing context.
The core objects
| Object | Role |
|---|---|
Browser | The synchronous Python controller. AsyncBrowser exposes the same browser contract with awaitable operations. |
| Native session | The ordered command and policy boundary owned by one controller. |
Page | A main-document handle for the active tab or one exact target returned by browser.tabs.get(). |
Frame | A child-document handle returned by page.frames. Its operations carry the same frame identity. |
Snapshot | An immutable observation of the browser accessibility tree, including the semantic roles, names, states, and relationships exposed for assistive technology. |
Ref | An element identity scoped to the snapshot that produced it. |
Query | An element lookup resolved against the live document each time an operation runs. |
ActionResult | The source snapshot, resulting snapshot, target ref, action name, and snapshot diff from one completed ref mutation. |
One interaction, end to end
from agentbrowser import Browser, Wait
with Browser.launch() as browser:
browser.page.open("https://example.com")
snapshot = browser.page.observe()
link = snapshot.one(role="link", name="Learn more")
result = link.click(wait=Wait.url("*://www.iana.org/*"))
print(result.before.origin)
print(result.after.origin)
print(result.diff.changed)Browser.launch() starts the browser before returning. page.observe() records the current accessibility tree. Snapshot.one() selects exactly one ref. Ref.click() performs the mutation, waits for the new URL, captures another snapshot with the same specification, and returns the transition evidence.
Two element models
Use a Ref when the workflow needs evidence tied to the page state the agent inspected. A ref mutation produces an ActionResult.
Use a Query when direct live-page control is the goal. A query resolves when each operation runs and returns the query or requested value.
| Need | Element model | Result |
|---|---|---|
| Explain what changed after an action | Snapshot-scoped Ref | ActionResult with before, after, and diff |
| Reuse a locator across live page updates | Query | Direct mutation or value |
| Revisit an element after its snapshot expires | Ref refreshed against a new snapshot | New Ref |
Product boundaries
The typed API owns stable Python workflows, input validation, result decoding, safety checks, and cleanup. browser.native exposes every action in the pinned engine through its JSON protocol while retaining those controller boundaries.
The accessibility tree is derived from the document and rendered semantics. It is smaller than the Document Object Model because it focuses on perceivable and operable content. MDN explains how browsers build this representation.
The optional browser.cdp API opens a direct Chrome DevTools Protocol connection for execution contexts, isolated worlds, and raw protocol methods.
Continue with Why pyagentbrowser? for the design rationale or Get started for the first complete session.