亿
亿牛云
登录免费注册
Blog/Practical Guide

CloakBrowser AI Agent Integration: A Practical Guide

Learn how to integrate CloakBrowser's stealth Chromium with Browser-Use, Crawl4AI, Scrapling, LangChain, Crawlee, Selenium, and other major AI agent and automation frameworks to achieve 0.9 reCAPTCHA v3 scores with undetected browser automation.

16Yun Engineering TeamJul 12, 20267 min read

Overview

AI agents are transforming how we interact with web pages—extending beyond simple content scraping to complex multi-step task execution, form filling, data extraction, and cross-site orchestration. However, the core bottleneck for AI agents is not LLM capability but browser anti-detection. When an agent drives a browser to visit sites protected by Cloudflare, reCAPTCHA, DataDome, and similar services, detection systems recognize the automation signals and block the requests.

CloakBrowser solves this problem with 66 C++ source-level patches. It not only eliminates automation signals like navigator.webdriver and CDP detection, but also achieves a 0.9 human-level reCAPTCHA v3 score and passes Cloudflare Turnstile challenges. More importantly, CloakBrowser provides direct integration capabilities with major AI agent and automation frameworks.

This article walks through 8 specific framework integrations, showing how to embed CloakBrowser's stealth capabilities into your agent workflows.

Integration Overview

CloakBrowser supports two integration modes:

ModeDescriptionApplicable Frameworks
CDP ConnectionCloakBrowser starts first with a remote debugging port; frameworks connect via CDPBrowser-Use, Crawl4AI, Scrapling, LangChain, Crawlee
Binary ReplacementFrameworks use CloakBrowser's Chromium binary directly instead of the default browserSelenium, undetected-chromedriver, agent-browser

Each mode suits different scenarios: CDP connection mode doesn't require modifying the framework's browser launch logic, making it ideal for frameworks with native CDP support. Binary replacement mode works best with WebDriver-based frameworks or when full control over browser launch parameters is needed.

Prerequisites

All integration examples require installing the CloakBrowser Python package:

pip install cloakbrowser

On first run, CloakBrowser automatically downloads the ~200MB stealth Chromium binary and caches it locally. For automatic timezone and locale detection from proxy IPs, install the geoip extras:

pip install cloakbrowser[geoip]

Browser-Use Integration

Browser-Use (70K Stars, GitHub repository browser-use/browser-use) is a Python framework that lets AI agents control browsers, supporting GPT-4o, Claude, and other LLMs. It controls the browser via Playwright or CDP, allowing the agent to see page screenshots and perform actions.

CloakBrowser integrates with Browser-Use using the CDP connection mode: CloakBrowser provides stealth browser capabilities, while Browser-Use handles the agent logic.

import asyncio
from browser_use import Agent, BrowserSession, ChatOpenAI
from cloakbrowser import launch_async
 
async def main():
    # 1. Launch CloakBrowser (handles binary, stealth args, and fingerprints)
    cb_browser = await launch_async(
        headless=True,
        args=["--remote-debugging-port=9242",
              "--remote-debugging-address=localhost"],
    )
 
    # 2. Connect Browser-Use to the stealth browser via CDP
    session = BrowserSession(cdp_url="http://localhost:9242")
 
    # 3. Run the AI agent — it browses through CloakBrowser
    agent = Agent(
        task="Go to https://httpbin.org/anything and get the page content",
        llm=ChatOpenAI(model="gpt-4o-mini"),
        browser_session=session,
    )
 
    result = await agent.run()
    print(result)
 
    await cb_browser.close()
 
if __name__ == "__main__":
    asyncio.run(main())

Integration Notes

  • CloakBrowser's stealth fingerprint patches take effect automatically at the CDP level, requiring no additional configuration
  • Browser-Use's agent operations (clicking, typing, scrolling) are forwarded to CloakBrowser via CDP
  • For sites that detect mouse behavior, enable the humanize=True parameter
cb_browser = await launch_async(
    headless=False,
    humanize=True,  # Bézier mouse curves, per-character typing, realistic scrolling
    args=["--remote-debugging-port=9242"],
)

Note: humanize=True is a wrapper-level feature. If connecting to CloakBrowser via CDP from an external script, import the humanization functions separately (see CloakBrowser README Human Behavior section).

Crawl4AI Integration

Crawl4AI (58K Stars, GitHub repository unclecode/crawl4ai) is a web crawler designed specifically for LLM use cases, automatically converting web page content to Markdown format for injection into LLM contexts.

import asyncio
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig
from cloakbrowser import launch_async
 
async def main():
    # 1. Launch CloakBrowser
    cb_browser = await launch_async(
        headless=True,
        args=["--remote-debugging-port=9243"],
    )
 
    # 2. Connect Crawl4AI to the stealth browser
    browser_config = BrowserConfig(
        browser_mode="cdp",
        cdp_url="http://localhost:9243"
    )
    run_config = CrawlerRunConfig()
 
    async with AsyncWebCrawler(config=browser_config) as crawler:
        result = await crawler.arun(
            "https://httpbin.org/anything",
            config=run_config,
        )
        print(f"Extracted {len(result.markdown)} chars of markdown")
        print(result.markdown[:500])
 
    await cb_browser.close()
 
if __name__ == "__main__":
    asyncio.run(main())

Use Cases

The Crawl4AI + CloakBrowser combination is particularly well-suited for:

  • LLM training data collection: Automatically scrape anti-bot-protected sites and convert content to structured Markdown for RAG or fine-tuning
  • Competitive intelligence monitoring: Periodically scrape competitor key pages and extract structured information
  • Content aggregation: Build data pipelines that bypass Cloudflare and reCAPTCHA

Scrapling Integration

Scrapling (21K Stars, GitHub repository D4Vinci/Scrapling) is an adaptive web scraping library with smart element tracking and automatic handling of page structure changes.

import asyncio
import json
from urllib.request import urlopen
from scrapling.fetchers import StealthyFetcher
from cloakbrowser import launch_async
 
async def main():
    # Launch CloakBrowser
    cb_browser = await launch_async(
        headless=True,
        args=["--remote-debugging-port=9245"],
    )
 
    # Get the WebSocket URL (Scrapling requires ws:// scheme)
    info = json.loads(
        urlopen("http://localhost:9245/json/version").read()
    )
    ws_url = info["webSocketDebuggerUrl"]
 
    # Connect Scrapling to the stealth browser via CDP
    page = await StealthyFetcher.async_fetch(
        "https://httpbin.org/anything",
        cdp_url=ws_url,
    )
 
    print(f"Title: {page.css('title::text').get()}")
    print(f"Paragraphs: {page.css('p::text').getall()}")
 
    await cb_browser.close()
 
if __name__ == "__main__":
    asyncio.run(main())

Scrapling's StealthyFetcher has built-in stealth connection support—passing CloakBrowser's CDP WebSocket URL gives you C++-level fingerprint protection automatically.

LangChain Integration

LangChain (100K+ Stars, GitHub repository langchain-ai/langchain) is one of the most popular LLM application development frameworks. Its PlaywrightURLLoader and similar tools use Playwright to launch browsers by default, but cannot directly specify a custom binary.

Using CloakBrowser's CDP connection mode, you can build a stealth document loader that returns LangChain Document objects:

import asyncio
from langchain_core.documents import Document
from cloakbrowser import launch_async
 
async def load_urls_stealth(urls, **launch_kwargs):
    """Load URLs using CloakBrowser stealth browser, return LangChain Documents."""
    browser = await launch_async(headless=True, **launch_kwargs)
    page = await browser.new_page()
    docs = []
 
    for url in urls:
        await page.goto(url, wait_until="domcontentloaded")
        text = await page.evaluate("document.body.innerText")
        title = await page.title()
        docs.append(Document(
            page_content=text,
            metadata={"source": url, "title": title},
        ))
 
    await browser.close()
    return docs
 
async def main():
    urls = [
        "https://httpbin.org/html",
        "https://httpbin.org/anything",
    ]
    docs = await load_urls_stealth(urls)
 
    for doc in docs:
        print(f"--- {doc.metadata['title']} ({doc.metadata['source']}) ---")
        print(doc.page_content[:300])
        print()
 
if __name__ == "__main__":
    asyncio.run(main())

The key advantage of this approach: CloakBrowser's 66 C++ patches are completely transparent to LangChain—LangChain interacts with the browser through the standard Playwright API, while the low-level fingerprint modifications are handled automatically by CloakBrowser.

Crawlee Integration

Crawlee (8.6K Stars, GitHub repository apify/crawlee-python) is Apify's Python crawler framework supporting Playwright, BeautifulSoup, and other scraping engines.

Integration with Crawlee requires creating a custom BrowserPlugin that replaces the default Chromium with CloakBrowser's patched binary:

import asyncio
from typing_extensions import override
from cloakbrowser.config import IGNORE_DEFAULT_ARGS, get_default_stealth_args
from cloakbrowser.download import ensure_binary
from crawlee.browsers import (
    BrowserPool,
    PlaywrightBrowserController,
    PlaywrightBrowserPlugin,
)
from crawlee.crawlers import PlaywrightCrawler, PlaywrightCrawlingContext
 
class CloakBrowserPlugin(PlaywrightBrowserPlugin):
    """Browser plugin that replaces default Chromium with CloakBrowser."""
 
    @override
    async def new_browser(self):
        if not self._playwright:
            raise RuntimeError("Playwright browser plugin is not initialized.")
 
        binary_path = ensure_binary()
        stealth_args = get_default_stealth_args()
 
        launch_options = dict(self._browser_launch_options)
        launch_options.pop("executable_path", None)
        launch_options.pop("chromium_sandbox", None)
        existing_args = list(launch_options.pop("args", []))
        launch_options["args"] = [*existing_args, *stealth_args]
 
        return PlaywrightBrowserController(
            browser=await self._playwright.chromium.launch(
                executable_path=binary_path,
                ignore_default_args=IGNORE_DEFAULT_ARGS,
                **launch_options,
            ),
            max_open_pages_per_browser=1,
            header_generator=None,
        )
 
async def main():
    crawler = PlaywrightCrawler(
        max_requests_per_crawl=10,
        browser_pool=BrowserPool(plugins=[CloakBrowserPlugin()]),
    )
 
    @crawler.router.default_handler
    async def request_handler(context: PlaywrightCrawlingContext):
        context.log.info(f"Processing {context.request.url} ...")
        title = await context.page.title()
        await context.push_data({
            "url": context.request.url,
            "title": title,
        })
        await context.enqueue_links()
 
    await crawler.run(["https://httpbin.org/anything"])
 
if __name__ == "__main__":
    asyncio.run(main())

Integration Notes

  • IGNORE_DEFAULT_ARGS removes Playwright's default automation arguments
  • get_default_stealth_args() returns all CloakBrowser stealth arguments
  • ensure_binary() automatically downloads and caches the stealth Chromium binary

Selenium Integration

Selenium (GitHub repository SeleniumHQ/selenium) is the most traditional browser automation framework, controlling browsers through the WebDriver protocol.

from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from cloakbrowser.config import get_default_stealth_args
from cloakbrowser.download import ensure_binary
 
binary_path = ensure_binary()
stealth_args = get_default_stealth_args()
 
options = Options()
options.binary_location = binary_path
options.add_argument("--headless")
for arg in stealth_args:
    options.add_argument(arg)
 
driver = webdriver.Chrome(options=options)
driver.get("https://httpbin.org/anything")
print(f"Selenium + CloakBrowser: {driver.title}")
 
# Verify stealth
result = driver.execute_script("""
    return {
        webdriver: navigator.webdriver,
        plugins: navigator.plugins.length,
        platform: navigator.platform,
    }
""")
print(f"Stealth checks: {result}")
 
driver.quit()

Important Note

Selenium integration requires ChromeDriver version matching CloakBrowser's Chromium version (currently Chromium 145). Use chromedriver-autoinstaller for automatic version matching:

pip install chromedriver-autoinstaller

undetected-chromedriver Integration

undetected-chromedriver (12K Stars, GitHub repository ultrafunkamsterdam/undetected-chromedriver) achieves stealth by patching ChromeDriver detection signals. Combined with CloakBrowser's C++-level patches, this creates a dual-layer defense:

import undetected_chromedriver as uc
from cloakbrowser.config import get_chromium_version, get_default_stealth_args
from cloakbrowser.download import ensure_binary
 
binary_path = ensure_binary()
stealth_args = get_default_stealth_args()
chromium_major = int(get_chromium_version().split(".")[0])
 
options = uc.ChromeOptions()
options.binary_location = binary_path
options.add_argument("--headless")
for arg in stealth_args:
    options.add_argument(arg)
 
driver = uc.Chrome(options=options, version_main=chromium_major)
driver.get("https://httpbin.org/anything")
print(f"undetected-chromedriver + CloakBrowser: {driver.title}")
 
result = driver.execute_script("""
    return {
        webdriver: navigator.webdriver,
        plugins: navigator.plugins.length,
        platform: navigator.platform,
        hardwareConcurrency: navigator.hardwareConcurrency,
    }
""")
print(f"Stealth checks: {result}")
 
driver.quit()

The advantage of this combination: undetected-chromedriver handles ChromeDriver-level detection (such as navigator.webdriver exposure at the WebDriver protocol level), while CloakBrowser handles deeper fingerprint detection at the browser engine level.

agent-browser Integration

agent-browser (GitHub repository nichochar/agent-browser) is a Node.js CLI tool that provides AI agent browser automation capabilities similar to Browser-Use.

#!/bin/bash
# Get CloakBrowser binary path (auto-downloads if needed)
BINARY_PATH=$(python3 -c \
  "from cloakbrowser.download import ensure_binary; print(ensure_binary())")
 
# Get stealth args (comma-separated for agent-browser)
STEALTH_ARGS=$(python3 -c \
  "from cloakbrowser.config import get_default_stealth_args; \
   print(','.join(get_default_stealth_args()))")
 
# Point agent-browser at CloakBrowser
export AGENT_BROWSER_EXECUTABLE_PATH="$BINARY_PATH"
export AGENT_BROWSER_ARGS="$STEALTH_ARGS"
 
# Open a page
agent-browser --session stealth-test open "https://httpbin.org/anything"
 
# Get page title
agent-browser --session stealth-test eval "document.title"
 
# Verify stealth
agent-browser --session stealth-test eval \
  "JSON.stringify({webdriver: navigator.webdriver, \
   plugins: navigator.plugins.length, \
   platform: navigator.platform})"

Deployment Integration: AWS Lambda

For production serverless deployments, CloakBrowser provides complete AWS Lambda container image support. The Lambda integration uses Xvfb to run a headed browser in a headless server environment, with an event-driven request handling model for on-demand scraping.

See the examples/integrations/aws_lambda/ directory in the CloakBrowser repository for:

  • lambda_handler.py: Complete event-driven handler supporting proxy configuration, humanized behavior, smart waiting, and automatic retries
  • Dockerfile: Container image built on a Chromium-compatible runtime
  • lambda-entrypoint.sh: Xvfb display server and browser process management

Integration Mode Comparison

FrameworkModeCode Changeshumanize SupportBest For
Browser-UseCDP Connection10 linesRequires extra setupAI agent multi-step tasks
Crawl4AICDP Connection10 linesRequires extra setupLLM data collection
ScraplingCDP Connection10 linesRequires extra setupAdaptive web scraping
LangChainCDP Connection15 linesRequires extra setupRAG / LLM document loading
CrawleeBinary Replacement30 linesAutomaticLarge-scale crawler deployment
SeleniumBinary Replacement10 linesRequires extra setupTraditional WebDriver projects
undetected-chromedriverBinary Replacement10 linesRequires extra setupDual-layer stealth
agent-browserBinary Replacement5 linesRequires extra setupNode.js AI agent CLI
AWS LambdaCDP + BinarySee examplesRequires extra setupServerless on-demand scraping

Best Practices

1. Prefer CDP Connection Mode

Unless you have specific requirements, use CDP connection mode. This mode doesn't require modifying the framework's browser launch logic—CloakBrowser handles all stealth parameters and binary management automatically.

2. Enable humanize Selectively

Only enable humanize=True when target sites actively detect mouse movement patterns, keyboard typing rhythm, or scrolling behavior. For most data scraping scenarios, the 66 C++ patches are sufficient to pass detection.

3. Combine with Proxies and GeoIP

For high-security targets (such as reCAPTCHA v3 Enterprise), configure proxies together with GeoIP:

browser = await launch_async(
    headless=False,
    proxy="http://user:pass@proxy.16yun.cn:8888",
    geoip=True,       # auto-match timezone and locale to proxy IP location
    humanize=True,    # human-like behavior simulation
)

4. Use Persistent Contexts to Avoid Incognito Detection

For scenarios requiring persistent login sessions, use launch_persistent_context() instead of regular launch() to keep cookies and localStorage across sessions (see Issue #320).

5. Note the CDP humanize Limitation

Stealth fingerprint patches take effect automatically at the CDP level, but humanize=True is a wrapper-level feature. If connecting to CloakBrowser via CDP from an external script, import the humanization functions separately:

import { patchBrowser, resolveConfig } from 'cloakbrowser/human';
patchBrowser(browser, resolveConfig('default'));

Conclusion

CloakBrowser's 66 C++ source-level patches provide the foundational infrastructure for browser stealth in AI agent and automation frameworks. Through integration with tools like Browser-Use, Crawl4AI, Scrapling, LangChain, Crawlee, Selenium, and more, developers can embed undetectable browsing capabilities into their agent workflows without needing to understand the underlying C++ patch details.

For production environments, choose the appropriate integration mode based on your target site's protection level, and combine proxies, GeoIP, and humanized behavior to build a complete stealth solution.

This article is based on CloakBrowser v0.4.10 (July 2026). Integration examples are sourced from the official CloakBrowser repository's examples/integrations directory.

Need an enterprise proxy plan?

We can tailor architecture to your target domains, concurrency, and reliability goals.

Book a consultationView pricing