tools.headless_browser module

Headless Firefox browser automation via Playwright.

Provides navigation, interaction, content extraction, waiting, screenshots, JavaScript execution, cookie management, network interception, session persistence, download handling, and console/dialog tools – all exposed through the v3 multi-tool format.

class tools.headless_browser.HeadlessBrowserManager[source]

Bases: object

HeadlessBrowserManager.

default_context_id

The default context id.

is_initialized

The is initialized.

last_used

The last used.

usage_count

The usage count.

error_count

The error count.

max_errors_before_restart

The max errors before restart.

idle_timeout

The idle timeout.

_lock

The lock.

default_viewport

The default viewport.

default_user_agent

The default user agent.

__init__()[source]

Initialize the instance.

async initialize()[source]

Initialize.

Returns:

True on success, False otherwise.

Return type:

bool

async ensure_ready()[source]

Ensure ready.

Returns:

True on success, False otherwise.

Return type:

bool

async restart()[source]

Restart.

Returns:

True on success, False otherwise.

Return type:

bool

async cleanup()[source]

Cleanup.

async get_page(context_id=None)[source]

Retrieve the page.

Parameters:

context_id (str) – The context id value.

async get_context(context_id=None)[source]

Retrieve the context.

Parameters:

context_id (str) – The context id value.

async create_new_context(context_id=None, **options)[source]

Create a new new context.

Parameters:

  • context_id (str) – The context id value.

  • **options – Additional keyword arguments.

Returns:

Result string.

Return type:

str

async close_context(context_id)[source]

Close context.

Parameters:

context_id (str) – The context id value.

record_error()[source]

Record error.

async tools.headless_browser.browser_navigate(url, wait_until='load', timeout=30000, context_id=None)[source]

Browser navigate.

Parameters:

  • url (str) – URL string.

  • wait_until (str) – The wait until value.

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_go_back(timeout=30000, context_id=None)[source]

Browser go back.

Parameters:

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_go_forward(timeout=30000, context_id=None)[source]

Browser go forward.

Parameters:

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_reload(wait_until='load', timeout=30000, context_id=None)[source]

Browser reload.

Parameters:

  • wait_until (str) – The wait until value.

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_close_context(context_id)[source]

Browser close context.

Parameters:

context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_click(selector, button='left', click_count=1, timeout=30000, context_id=None)[source]

Browser click.

Parameters:

  • selector (str) – The selector value.

  • button (str) – The button value.

  • click_count (int) – The click count value.

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_type(selector, text, delay=0, clear_first=False, timeout=30000, context_id=None)[source]

Browser type.

Parameters:

  • selector (str) – The selector value.

  • text (str) – Text content.

  • delay (int) – The delay value.

  • clear_first (bool) – The clear first value.

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_fill(selector, value, timeout=30000, context_id=None)[source]

Browser fill.

Parameters:

  • selector (str) – The selector value.

  • value (str) – Value to set.

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_fill_form(fields, timeout=30000, context_id=None)[source]

Browser fill form.

Parameters:

  • fields (str) – The fields value.

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_select_option(selector, value=None, label=None, index=None, timeout=30000, context_id=None)[source]

Browser select option.

Parameters:

  • selector (str) – The selector value.

  • value (str) – Value to set.

  • label (str) – The label value.

  • index (int) – The index value.

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_press_key(key, selector=None, timeout=30000, context_id=None)[source]

Browser press key.

Parameters:

  • key (str) – Dictionary or cache key.

  • selector (str) – The selector value.

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_hover(selector, timeout=30000, context_id=None)[source]

Browser hover.

Parameters:

  • selector (str) – The selector value.

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_scroll(direction='down', amount=500, selector=None, context_id=None)[source]

Browser scroll.

Parameters:

  • direction (str) – The direction value.

  • amount (int) – The amount value.

  • selector (str) – The selector value.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_get_content(format='text', selector=None, context_id=None)[source]

Browser get content.

Parameters:

  • format (str) – The format value.

  • selector (str) – The selector value.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_get_text(selector, timeout=30000, context_id=None)[source]

Browser get text.

Parameters:

  • selector (str) – The selector value.

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_get_attribute(selector, attribute, timeout=30000, context_id=None)[source]

Browser get attribute.

Parameters:

  • selector (str) – The selector value.

  • attribute (str) – The attribute value.

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_get_page_info(context_id=None)[source]

Browser get page info.

Parameters:

context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_query_selector_all(selector, attributes=None, timeout=30000, context_id=None)[source]

Browser query selector all.

Parameters:

  • selector (str) – The selector value.

  • attributes (str) – The attributes value.

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_wait_for_selector(selector, state='visible', timeout=30000, context_id=None)[source]

Browser wait for selector.

Parameters:

  • selector (str) – The selector value.

  • state (str) – The state value.

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_wait_for_load_state(state='load', timeout=30000, context_id=None)[source]

Browser wait for load state.

Parameters:

  • state (str) – The state value.

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_wait_for_url(url_pattern, timeout=30000, context_id=None)[source]

Browser wait for url.

Parameters:

  • url_pattern (str) – The url pattern value.

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_wait(milliseconds, context_id=None)[source]

Browser wait.

Parameters:

  • milliseconds (int) – The milliseconds value.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_screenshot(full_page=True, selector=None, filename=None, context_id=None)[source]

Browser screenshot.

Parameters:

  • full_page (bool) – The full page value.

  • selector (str) – The selector value.

  • filename (str) – The filename value.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_pdf(filename=None, format='A4', landscape=False, print_background=True, context_id=None)[source]

Browser pdf.

Parameters:

  • filename (str) – The filename value.

  • format (str) – The format value.

  • landscape (bool) – The landscape value.

  • print_background (bool) – The print background value.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_evaluate(expression, context_id=None)[source]

Browser evaluate.

Parameters:

  • expression (str) – The expression value.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_execute(script, context_id=None)[source]

Browser execute.

Parameters:

  • script (str) – The script value.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_get_cookies(urls=None, context_id=None)[source]

Browser get cookies.

Parameters:

  • urls (str) – The urls value.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_set_cookies(cookies, context_id=None)[source]

Browser set cookies.

Parameters:

  • cookies (str) – The cookies value.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_clear_cookies(context_id=None)[source]

Browser clear cookies.

Parameters:

context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_emulate_device(device_name, context_id=None)[source]

Browser emulate device.

Parameters:

  • device_name (str) – The device name value.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_set_geolocation(latitude, longitude, accuracy=100, context_id=None)[source]

Browser set geolocation.

Parameters:

  • latitude (float) – The latitude value.

  • longitude (float) – The longitude value.

  • accuracy (float) – The accuracy value.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_set_viewport(width, height, context_id=None)[source]

Browser set viewport.

Parameters:

  • width (int) – The width value.

  • height (int) – The height value.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_block_resources(resource_types, context_id=None)[source]

Browser block resources.

Parameters:

  • resource_types (str) – The resource types value.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_get_status()[source]

Browser get status.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_restart()[source]

Browser restart.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_new_context(context_id=None, incognito=True)[source]

Browser new context.

Parameters:

  • context_id (str) – The context id value.

  • incognito (bool) – The incognito value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_enable_response_interception(url_patterns, context_id=None)[source]

Browser enable response interception.

Parameters:

  • url_patterns (str) – The url patterns value.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_wait_for_response(url_pattern, timeout=30000, context_id=None)[source]

Browser wait for response.

Parameters:

  • url_pattern (str) – The url pattern value.

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_get_intercepted_responses(context_id=None, url_filter=None)[source]

Browser get intercepted responses.

Parameters:

  • context_id (str) – The context id value.

  • url_filter (str) – The url filter value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_get_response_body(response_id)[source]

Browser get response body.

Parameters:

response_id (str) – The response id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_clear_intercepted_responses(context_id=None)[source]

Browser clear intercepted responses.

Parameters:

context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_create_persistent_context(session_name, context_id=None)[source]

Browser create persistent context.

Parameters:

  • session_name (str) – The session name value.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_list_sessions()[source]

Browser list sessions.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_delete_session(session_name)[source]

Browser delete session.

Parameters:

session_name (str) – The session name value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_wait_for_download(timeout=30000, context_id=None)[source]

Browser wait for download.

Parameters:

  • timeout (int) – Maximum wait time in seconds.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_get_downloads(context_id=None, state=None)[source]

Browser get downloads.

Parameters:

  • context_id (str) – The context id value.

  • state (str) – The state value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_save_download(download_id, filename=None)[source]

Browser save download.

Parameters:

  • download_id (str) – The download id value.

  • filename (str) – The filename value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_get_console_logs(context_id=None, level=None, limit=100)[source]

Browser get console logs.

Parameters:

  • context_id (str) – The context id value.

  • level (str) – The level value.

  • limit (int) – Maximum number of items.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_clear_console_logs(context_id=None)[source]

Browser clear console logs.

Parameters:

context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_handle_dialog(action, prompt_text=None, context_id=None)[source]

Browser handle dialog.

Parameters:

  • action (str) – The action value.

  • prompt_text (str) – The prompt text value.

  • context_id (str) – The context id value.

Returns:

Result string.

Return type:

str

async tools.headless_browser.browser_get_pending_dialog(context_id=None)[source]

Browser get pending dialog.

Parameters:

context_id (str) – The context id value.

Returns:

Result string.

Return type:

str