Enable "Stealth Mode" for Headless Browser

Overview

This section explains what Stealth Mode is, why you might need it, and how to enable it with AgentQL.

Why do you need stealth mode?

Modern websites often deploy sophisticated bot detection systems that analyze browser behavior, properties, and interactions to distinguish human users from bots. Without Stealth Mode, several signals can reveal the use of automation, such as:

  • navigator.webdriver property: Indicates whether a browser is controlled by automation.
  • Headless mode detection: Certain differences in how headless browsers behave compared to regular browsers.
  • Missing or inconsistent browser APIs: Bots often miss certain APIs or provide inconsistent values (for example, WebGL, media codecs).

These detection methods can result in websites blocking automated sessions, presenting CAPTCHAs, or even banning IP addresses. AgentQL Stealth Mode helps to bypass such measures by minimizing the traces of automation and simulating real user browser environment.

Example usage

You can enable Stealth Mode in AgentQL by calling the enable_stealth_mode method of a page object.

stealth_mode.py
python
from playwright.sync_api import sync_playwright
import agentql

with sync_playwright() as playwright, playwright.chromium.launch(
    headless=False,
) as browser:
    page = agentql.wrap(browser.new_page())

    page.enable_stealth_mode()

    page.goto("https://bot.sannysoft.com/")
    page.wait_for_timeout(30000)

In this example, we enable Stealth Mode to the Playwright page before navigating to the website. This way, the browser will simulate a real user environment, making it harder for the website to detect automation.

For more advanced usages, you may want to customize some of the default values used by Stealth Mode. You can do this by passing the desired options to the enable_stealth_mode method. For example, you can set the nav_user_agent to a specific value or customize webgl properties.

stealth_mode.py
python
page.enable_stealth_mode(
        webgl_vendor="Intel Inc.",
        webgl_renderer="Intel Iris OpenGL Engine",
        nav_user_agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
    )
tip

To get more realistic values, you could pull the user agent and webgl vendor from a real browser and pass them to enable_stealth_mode method. To get those values, you can go to one of the browser fingerpriting websites such as bot.sannysoft.com and pixelscan.net get those values there.

Related content

To further lower the risk of being detected by an anti-bot system, check out Stealth Mode examples which demonstrate other techniques to apply in your scripts.