Browser API Reference

April 2, 2026 · View on GitHub

💡 Async Version: This documentation covers the synchronous API. For async/await support, see AsyncBrowser which provides the same functionality with async methods.

Browser Use Guide - Complete guide to browser automation

Overview

The Browser module provides comprehensive browser automation capabilities including navigation, element interaction,screenshot capture, and content extraction. It enables automated testing and web scraping workflows.

Requirements

Requires browser_latest image for browser automation features

Browser

class Browser(BaseService)

Browser provides browser-related operations for the session.

init

def __init__(self, session: "Session")

agent

@property
def agent()

Deprecated: Use operator instead. This property will be removed in a future version.

Example:

# Old way (deprecated):
# session.browser.operator.navigate(url)

# New way (recommended):
session.browser.operator.navigate(url)

initialize

def initialize(option: Optional["BrowserOption"] = None) -> bool

Initialize the browser instance with the given options synchronously. Returns True if successful, False otherwise.

Arguments:

option BrowserOption, optional - Browser configuration options. If None, default options are used.

Returns:

bool: True if initialization was successful, False otherwise.

Example:

create_result = agent_bay.create()
session = create_result.session
# Use default options
session.browser.initialize()
# Or with specific options
browser_option = BrowserOption(use_stealth=True)
session.browser.initialize(browser_option)
session.delete()

init

def init(option: Optional["BrowserOption"] = None) -> bool

Alias for initialize.

destroy

def destroy()

Destroy the browser instance manually.

screenshot

def screenshot(page, full_page: bool = False, **options) -> bytes

Takes a screenshot of the specified page with enhanced options and error handling.

Arguments:

page Page - The Playwright Page object to take a screenshot of. This is a required parameter.
full_page bool - Whether to capture the full scrollable page. Defaults to False. **options: Additional screenshot options that will override defaults. Common options include:
- type (str): Image type, either 'png' or 'jpeg' (default: 'png')
- quality (int): Quality of the image, between 0-100 (jpeg only)
- timeout (int): Maximum time in milliseconds (default: 60000)
- animations (str): How to handle animations (default: 'disabled')
- caret (str): How to handle the caret (default: 'hide')
- scale (str): Scale setting (default: 'css')

Returns:

bytes: Screenshot data as bytes.

Raises:

BrowserError: If browser is not initialized.
RuntimeError: If screenshot capture fails.

register_callback

def register_callback(callback: BrowserCallback) -> bool

Arguments:

callback Callable[[BrowserNotifyMessage], None] - Callback function that receives a BrowserNotifyMessage object containing notification details such as type, code, message, action, and extra_params.

Returns:

bool: True if the callback was successfully registered.

Example:

def on_browser_callback(notify_msg: BrowserNotifyMessage):
  print(f"Type: {notify_msg.type}")
  print(f"Code: {notify_msg.code}")
  print(f"Message: {notify_msg.message}")
  print(f"Action: {notify_msg.action}")
  print(f"Extra params: {notify_msg.extra_params}")

create_result = agent_bay.create()
session = create_result.session

# Initialize browser
session.browser.initialize()

# Register callback
success = session.browser.register_callback(on_browser_callback)

# ... do work ...

# Unregister when done
session.browser.unregister_callback()
session.delete()

unregister_callback

def unregister_callback() -> None

Unregister the previously registered callback function.

Example:

def on_browser_callback(notify_msg: BrowserNotifyMessage):
  print(f"Notification - Type: {notify_msg.type}, Message: {notify_msg.message}")

create_result = agent_bay.create()
session = create_result.session

session.browser.initialize()

session.browser.register_callback(on_browser_callback)

# ... do work ...

# Unregister callback
session.browser.unregister_callback()

session.delete()

send_notify_message

def send_notify_message(notify_message: BrowserNotifyMessage) -> bool

Send a BrowserNotifyMessage to sandbox.

Arguments:

notify_message BrowserNotifyMessage - The notify message to send.

Returns:

bool: True if the notify message was successfully sent, False otherwise.

Example:

def on_browser_callback(notify_msg: BrowserNotifyMessage):
  print(f"Type: {notify_msg.type}")
  print(f"Code: {notify_msg.code}")
  print(f"Message: {notify_msg.message}")
  print(f"Action: {notify_msg.action}")
  print(f"Extra params: {notify_msg.extra_params}")

create_result = agent_bay.create()
session = create_result.session

# Initialize browser
session.browser.initialize()

# Register callback
success = session.browser.register_callback(on_browser_callback)

# ... do work ...

# Send notify message
notify_message = BrowserNotifyMessage(
  type="call-for-user",
  id=3,
  code=199,
  message="user handle done",
  action="takeoverdone",
  extra_params={}
)
session.browser.send_notify_message(notify_message)

# Unregister when done
session.browser.unregister_callback()
session.delete()

send_takeover_done

def send_takeover_done(notify_id: int) -> bool

Send a takeoverdone notify message to sandbox.

Arguments:

notify_id int - The notification ID associated with the takeover request message.

Returns:

bool: True if the takeoverdone notify message was successfully sent, False otherwise.

Example:

def on_browser_callback(notify_msg: BrowserNotifyMessage):
  # receive call-for-user "takeover" action
  if notify_msg.action == "takeover":
      takeover_notify_id = notify_msg.id

      ## ... do work in other thread...
      # send takeoverdone notify message
      session.browser.send_takeover_done(takeover_notify_id)
      ## ... end...

create_result = agent_bay.create()
session = create_result.session

# Initialize browser
session.browser.initialize()

# Register callback
success = session.browser.register_callback(on_browser_callback)

# ... do work ...

# Unregister when done
session.browser.unregister_callback()
session.delete()

get_endpoint_url

def get_endpoint_url() -> str

Returns the endpoint URL if the browser is initialized, otherwise raises an exception. When initialized, always fetches the latest CDP url from session.get_link().

Returns:

str: The browser CDP endpoint URL.

Raises:

BrowserError: If browser is not initialized or endpoint URL cannot be retrieved.

Example:

create_result = agent_bay.create()
session = create_result.session
browser_option = BrowserOption()
session.browser.initialize(browser_option)
endpoint_url = session.browser.get_endpoint_url()
print(f"CDP Endpoint: {endpoint_url}")
session.delete()

get_option

def get_option() -> Optional["BrowserOption"]

Returns the current BrowserOption used to initialize the browser, or None if not set.

Returns:

Optional[BrowserOption]: The browser options if initialized, None otherwise.

Example:

create_result = agent_bay.create()
session = create_result.session
browser_option = BrowserOption(use_stealth=True)
session.browser.initialize(browser_option)
current_options = session.browser.get_option()
print(f"Stealth mode: {current_options.use_stealth}")
session.delete()

is_initialized

def is_initialized() -> bool

Returns True if the browser was initialized, False otherwise.

Returns:

bool: True if browser is initialized, False otherwise.

Example:

create_result = agent_bay.create()
session = create_result.session
print(f"Initialized: {session.browser.is_initialized()}")
browser_option = BrowserOption()
session.browser.initialize(browser_option)
print(f"Initialized: {session.browser.is_initialized()}")
session.delete()

Best Practices

Wait for page load completion before interacting with elements
Use appropriate selectors (CSS, XPath) for reliable element identification
Handle navigation timeouts and errors gracefully
Take screenshots for debugging and verification
Clean up browser resources after automation tasks