Browser Actor

Browser Actor is a web automation library built on CDP (Chrome DevTools Protocol) that provides low-level browser automation capabilities within the browser-use ecosystem.

Usage

Integrated with Browser (Recommended)

python

from browser_use import Browser  # Alias for BrowserSession

# Create and start browser session
browser = Browser()
await browser.start()

# Create new tabs and navigate
page = await browser.new_page("https://example.com")
pages = await browser.get_pages()
current_page = await browser.get_current_page()

Direct Page Access (Advanced)

python

from browser_use.actor import Page, Element, Mouse

# Create page with existing browser session
page = Page(browser_session, target_id, session_id)

Basic Operations

python

# Tab Management
page = await browser.new_page()  # Create blank tab
page = await browser.new_page("https://example.com")  # Create tab with URL
pages = await browser.get_pages()  # Get all existing tabs
await browser.close_page(page)  # Close specific tab

# Navigation
await page.goto("https://example.com")
await page.go_back()
await page.go_forward()
await page.reload()

Element Operations

python

# Find elements by CSS selector
elements = await page.get_elements_by_css_selector("input[type='text']")
buttons = await page.get_elements_by_css_selector("button.submit")

# Get element by backend node ID
element = await page.get_element(backend_node_id=12345)

# AI-powered element finding (requires LLM)
element = await page.get_element_by_prompt("search button", llm=your_llm)
element = await page.must_get_element_by_prompt("login form", llm=your_llm)

Note: get_elements_by_css_selector returns immediately without waiting for visibility.

Element Interactions

python

# Element actions
await element.click(button='left', click_count=1, modifiers=['Control'])
await element.fill("Hello World")  # Clears first, then types
await element.hover()
await element.focus()
await element.check()  # Toggle checkbox/radio
await element.select_option(["option1", "option2"])  # For dropdown/select
await element.drag_to(target_element)  # Drag and drop

# Element properties
value = await element.get_attribute("value")
box = await element.get_bounding_box()  # Returns BoundingBox or None
info = await element.get_basic_info()  # Comprehensive element info
screenshot_b64 = await element.screenshot(format='png')

# Execute JavaScript on element (this context is the element)
text = await element.evaluate("() => this.textContent")
await element.evaluate("(color) => this.style.backgroundColor = color", "yellow")
classes = await element.evaluate("() => Array.from(this.classList)")

Mouse Operations

python

# Mouse operations
mouse = await page.mouse
await mouse.click(x=100, y=200, button='left', click_count=1)
await mouse.move(x=300, y=400, steps=1)
await mouse.down(button='left')  # Press button
await mouse.up(button='left')    # Release button
await mouse.scroll(x=0, y=100, delta_x=0, delta_y=-500)  # Scroll at coordinates

Page Operations

python

# JavaScript evaluation
result = await page.evaluate('() => document.title')  # Must use arrow function format
result = await page.evaluate('(x, y) => x + y', 10, 20)  # With arguments

# Keyboard input
await page.press("Control+A")  # Key combinations supported
await page.press("Escape")     # Single keys

# Page controls
await page.set_viewport_size(width=1920, height=1080)
page_screenshot = await page.screenshot()  # PNG by default
page_png = await page.screenshot(format="png", quality=90)

# Page information
url = await page.get_url()
title = await page.get_title()

AI-Powered Features

python

# Content extraction using LLM
from pydantic import BaseModel

class ProductInfo(BaseModel):
    name: str
    price: float
    description: str

# Extract structured data from current page
products = await page.extract_content(
    "Find all products with their names, prices and descriptions",
    ProductInfo,
    llm=your_llm
)

Core Classes

BrowserSession (aliased as Browser): Main browser session manager with tab operations
Page: Represents a single browser tab or iframe for page-level operations
Element: Individual DOM element for interactions and property access
Mouse: Mouse operations within a page (click, move, scroll)

API Reference

BrowserSession Methods (Tab Management)

start() - Initialize and start the browser session
stop() - Stop the browser session (keeps browser alive)
kill() - Kill the browser process and reset all state
new_page(url=None) → Page - Create blank tab or navigate to URL
get_pages() → list[Page] - Get all available pages
get_current_page() → Page | None - Get the currently focused page
close_page(page: Page | str) - Close page by object or ID
Session management and CDP client operations

Page Methods (Page Operations)

get_elements_by_css_selector(selector: str) → list[Element] - Find elements by CSS selector
get_element(backend_node_id: int) → Element - Get element by backend node ID
get_element_by_prompt(prompt: str, llm) → Element | None - AI-powered element finding
must_get_element_by_prompt(prompt: str, llm) → Element - AI element finding (raises if not found)
extract_content(prompt: str, structured_output: type[T], llm) → T - Extract structured data using LLM
goto(url: str) - Navigate this page to URL
go_back(), go_forward() - Navigate history (with error handling)
reload() - Reload the current page
evaluate(page_function: str, *args) → str - Execute JavaScript (MUST use (...args) => format)
press(key: str) - Press key on page (supports "Control+A" format)
set_viewport_size(width: int, height: int) - Set viewport dimensions
screenshot(format='png', quality=None) → str - Take page screenshot, return base64
get_url() → str, get_title() → str - Get page information
mouse → Mouse - Get mouse interface for this page

Element Methods (DOM Interactions)

click(button='left', click_count=1, modifiers=None) - Click element with advanced fallbacks
fill(text: str, clear=True) - Fill input with text (clears first by default)
hover() - Hover over element
focus() - Focus the element
check() - Toggle checkbox/radio button (clicks to change state)
select_option(values: str | list[str]) - Select dropdown options
drag_to(target_element: Element | Position, source_position=None, target_position=None) - Drag to target element
evaluate(page_function: str, *args) → str - Execute JavaScript on element (this = element)
get_attribute(name: str) → str | None - Get attribute value
get_bounding_box() → BoundingBox | None - Get element position/size
screenshot(format='png', quality=None) → str - Take element screenshot, return base64
get_basic_info() → ElementInfo - Get comprehensive element information

Mouse Methods (Coordinate-Based Operations)

click(x: int, y: int, button='left', click_count=1) - Click at coordinates
move(x: int, y: int, steps=1) - Move to coordinates
down(button='left', click_count=1), up(button='left', click_count=1) - Press/release button
scroll(x=0, y=0, delta_x=None, delta_y=None) - Scroll page at coordinates

Type Definitions

Position

python

class Position(TypedDict):
    x: float
    y: float

BoundingBox

python

class BoundingBox(TypedDict):
    x: float
    y: float
    width: float
    height: float

ElementInfo

python

class ElementInfo(TypedDict):
    backendNodeId: int          # CDP backend node ID
    nodeId: int | None          # CDP node ID
    nodeName: str               # HTML tag name (e.g., "DIV", "INPUT")
    nodeType: int               # DOM node type
    nodeValue: str | None       # Text content for text nodes
    attributes: dict[str, str]  # HTML attributes
    boundingBox: BoundingBox | None  # Element position and size
    error: str | None           # Error message if info retrieval failed

Important Usage Notes

This is browser-use actor, NOT Playwright or Selenium. Only use the methods documented above.

Critical JavaScript Rules

page.evaluate() and element.evaluate() MUST use (...args) => {} arrow function format
Always returns string (objects are JSON-stringified automatically)
Use single quotes around the function: page.evaluate('() => document.title')
For complex selectors in JS: '() => document.querySelector("input[name=\\"email\\"]")'
element.evaluate(): this context is bound to the element automatically

Method Restrictions

get_elements_by_css_selector() returns immediately (no automatic waiting)
For dropdowns: use element.select_option(), NOT element.fill()
Form submission: click submit button or use page.press("Enter")
No methods like: element.submit(), element.dispatch_event(), element.get_property()

Error Prevention

Always verify page state changes with page.get_url(), page.get_title()
Use element.get_attribute() to check element properties
Validate CSS selectors before use
Handle navigation timing with appropriate asyncio.sleep() calls

AI Features

get_element_by_prompt() and extract_content() require an LLM instance
These methods use DOM analysis and structured output parsing
Best for complex page understanding and data extraction tasks