Skip to content

Latest commit

 

History

History
215 lines (138 loc) · 5.19 KB

async-browser.md

File metadata and controls

215 lines (138 loc) · 5.19 KB

AsyncBrowser API Reference

💡 Sync Version: This documentation covers the asynchronous API. For synchronous operations, see Browser.

⚡ Performance Advantage: Async API enables concurrent operations with 4-6x performance improvements for parallel tasks.

🌐 Related Tutorial

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

AsyncBrowser

class AsyncBrowser(AsyncBaseService)

Browser provides browser-related operations for the session.

init

def __init__(self, session: "AsyncSession")

initialize

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

Initialize the browser instance with the given options asynchronously. 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 = await agent_bay.create()
session = create_result.session
# Use default options
await session.browser.initialize()
# Or with specific options
browser_option = BrowserOption(use_stealth=True)
await session.browser.initialize(browser_option)
await session.delete()

init

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

Alias for initialize.

destroy

async def destroy()

Destroy the browser instance manually.

screenshot

async 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.

get_endpoint_url

async 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 = await agent_bay.create()
session = create_result.session
browser_option = BrowserOption()
await session.browser.initialize(browser_option)
endpoint_url = await session.browser.get_endpoint_url()
print(f"CDP Endpoint: {endpoint_url}")
await 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 = await agent_bay.create()
session = create_result.session
browser_option = BrowserOption(use_stealth=True)
await session.browser.initialize(browser_option)
current_options = session.browser.get_option()
print(f"Stealth mode: {current_options.use_stealth}")
await 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 = await agent_bay.create()
session = create_result.session
print(f"Initialized: {session.browser.is_initialized()}")
browser_option = BrowserOption()
await session.browser.initialize(browser_option)
print(f"Initialized: {session.browser.is_initialized()}")
await session.delete()

Best Practices

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

See Also

Related APIs:

Documentation generated automatically from source code using pydoc-markdown.