Connect with Playwright

AI agent instructions

Read the Notte skill and follow its setup instructions when setting up Notte or building browser automation. This is the shared source for CLI setup, authentication, and the browser-to-code workflow.

Notte sessions expose a Chrome DevTools Protocol (CDP) endpoint that you can connect to with Playwright. This allows you to use Playwright’s API directly while still benefiting from Notte’s cloud infrastructure, anti-detection features, and session management.

Connection URLs and recordings

URL	Purpose	Client
`cdp_url`	Control the live browser over Chrome DevTools Protocol	Playwright `chromium.connect_over_cdp()` (Python), `chromium.connectOverCDP()` (Node), or Puppeteer
`playwright_url`	Control the live browser over Playwright protocol, when the server supports it	Playwright `chromium.connect()`
`viewer_url`	Open the live browser viewer; interaction depends on the link’s permissions	Your web browser
Replay `mp4_url`	Watch a recording after the session; does not control a browser	A video player

playwright_url is optional and defaults to None in Python. In a server response it can be absent or null. The field prepares the SDK contract for servers that offer Playwright-protocol access; it does not enable that endpoint. When your server supplies a URL, use the Playwright client version supported by that server. The CDP examples below and the SDK’s page helper continue to use CDP. With CDP, Playwright runs the browser-action logic on your machine and exchanges CDP commands with the remote browser. With Playwright protocol, that logic runs beside the browser, which can reduce network round trips for actions such as clicks and fills. The benefit depends on your network latency and workload; website loading and data transfer still take time. Use the Sessions API or the SDK’s session context manager to stop the session when your automation finishes.

Prerequisites

Install Playwright alongside the Notte SDK:

pip install notte-sdk playwright

Connect Playwright to Notte Session

Get the CDP URL from a Notte session and connect Playwright to it:

from notte_sdk import NotteClient
from playwright.sync_api import sync_playwright

client = NotteClient()

# Start a Notte session
with client.Session() as session:
    # Get CDP WebSocket URL
    cdp_url = session.cdp_url()
    print(f"CDP URL: {cdp_url}")

    # Connect Playwright to the Notte session
    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(cdp_url)

        # Access the page (Notte sessions have one context with one page)
        context = browser.contexts[0]
        page = context.pages[0]

        # Use Playwright API directly
        page.goto("https://example.com")
        print(f"Title: {page.title()}")

        # Take a screenshot
        page.screenshot(path="screenshot.png")

Notte sessions automatically create a browser context with one page. Access it via browser.contexts[0].pages[0].

Use Both Notte and Playwright APIs

You can use both the Notte session API and Playwright simultaneously:

from notte_sdk import NotteClient
from playwright.sync_api import sync_playwright

client = NotteClient()

with client.Session() as session:
    # Use Notte's built-in page
    notte_page = session.page
    notte_page.goto("https://example.com")

    # Also connect Playwright for advanced features
    cdp_url = session.cdp_url()

    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(cdp_url)
        playwright_page = browser.contexts[0].pages[0]

        # Use Playwright's advanced features
        playwright_page.route("**/*.{png,jpg,jpeg}", lambda route: route.abort())

        # Navigate with route interception active
        playwright_page.goto("https://example.com/gallery")

        # Use Playwright's network monitoring
        with playwright_page.expect_response("**/api/data") as response_info:
            playwright_page.click("button#load-data")
        response = response_info.value
        print(f"API Response: {response.status()}")

Async Playwright Support

Notte works with both sync and async Playwright:

import asyncio

from notte_sdk import NotteClient
from playwright.async_api import async_playwright


async def main():
    client = NotteClient()

    with client.Session() as session:
        cdp_url = session.cdp_url()

        async with async_playwright() as p:
            browser = await p.chromium.connect_over_cdp(cdp_url)
            context = browser.contexts[0]
            page = context.pages[0]

            await page.goto("https://example.com")
            title = await page.title()
            print(f"Title: {title}")

            await page.screenshot(path="screenshot.png")


asyncio.run(main())

Advanced: Multiple Pages

Open additional pages in the session’s existing browser context:

from notte_sdk import NotteClient
from playwright.sync_api import sync_playwright

client = NotteClient()

with client.Session() as session:
    cdp_url = session.cdp_url()

    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(cdp_url)

        # Reuse the session's existing browser context
        context = browser.contexts[0]

        # Open additional pages (tabs) in that context
        page1 = context.new_page()
        page2 = context.new_page()

        page1.goto("https://example.com")
        page2.goto("https://google.com")

        print(f"Page 1: {page1.title()}")
        print(f"Page 2: {page2.title()}")

Each Notte session runs a single browser context. Creating new contexts with browser.new_context() is not supported over the CDP connection; use browser.contexts[0] and open pages in it. To run with different settings (viewport, user agent), start a separate session with those options.

Network Interception

Use Playwright’s powerful network interception with Notte sessions:

from notte_sdk import NotteClient
from playwright.sync_api import sync_playwright

client = NotteClient()

with client.Session() as session:
    cdp_url = session.cdp_url()

    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(cdp_url)
        page = browser.contexts[0].pages[0]

        # Block images and stylesheets for faster loading
        page.route("**/*.{png,jpg,jpeg,css}", lambda route: route.abort())

        # Modify API responses
        def handle_route(route):
            if "api/config" in route.request.url:
                route.fulfill(json={"feature_enabled": True})
            else:
                route.continue_()

        page.route("**/api/**", handle_route)

        page.goto("https://example.com")

Browser Events and Monitoring

Listen to browser events using Playwright:

from notte_sdk import NotteClient
from playwright.sync_api import sync_playwright

client = NotteClient()

with client.Session() as session:
    cdp_url = session.cdp_url()

    with sync_playwright() as p:
        browser = p.chromium.connect_over_cdp(cdp_url)
        page = browser.contexts[0].pages[0]

        # Listen to console messages
        page.on("console", lambda msg: print(f"Console: {msg.text}"))

        # Listen to page errors
        page.on("pageerror", lambda err: print(f"Error: {err}"))

        # Listen to requests
        page.on("request", lambda req: print(f"Request: {req.url}"))

        # Listen to responses
        page.on("response", lambda res: print(f"Response: {res.url} - {res.status}"))

        page.goto("https://example.com")

import { NotteClient } from 'notte-sdk';
import { chromium } from 'playwright-core';

const client = new NotteClient();

const status = await client.Session().use(async session => {
  const status = await session.status();
  const browser = await chromium.connectOverCDP(status.cdp_url!);
  try {
    const page = browser.contexts()[0].pages()[0];
    // Listen to console messages
    page.on('console', msg => console.log(`Console: ${msg.text()}`));

    // Listen to page errors
    page.on('pageerror', err => console.log(`Error: ${err}`));

    // Listen to requests
    page.on('request', req => console.log(`Request: ${req.url()}`));

    // Listen to responses
    page.on('response', res => console.log(`Response: ${res.url()} - ${res.status()}`));

    await page.goto('https://example.com');
  } finally {
    await browser.close();
  }
  return status;
});

Best Practices

1. Use Context Managers

Always use context managers for both Notte and Playwright to ensure proper cleanup:

from notte_sdk import NotteClient
from playwright.sync_api import sync_playwright  # type: ignore[import-not-found]

client = NotteClient()

with client.Session() as session:
    with sync_playwright() as p:
        # Your code here
        pass

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

const status = await client.Session().use(async session => {
  // Your code here

  return await session.status();
});

2. Prefer Notte’s Built-in Page

For simple automation, use session.page directly. Only connect Playwright when you need advanced features like network interception or event monitoring.

3. Session Timeout

Remember that Notte sessions have a timeout. For long-running Playwright operations, increase the timeout:

from notte_sdk import NotteClient

client = NotteClient()

with client.Session(idle_timeout_minutes=20, max_duration_minutes=20) as session:
    # Long Playwright automation
    pass

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

const status = await client.Session({ idle_timeout_minutes: 20, max_duration_minutes: 20 }).use(async session => {
  // Long Playwright automation
  return session.status();
});

4. Handle CDP Disconnections

CDP connections can be interrupted. Wrap operations in try-except blocks:

from notte_sdk import NotteClient
from playwright.sync_api import sync_playwright  # type: ignore[import-not-found]

client = NotteClient()

with client.Session() as session:
    cdp_url = session.cdp_url()
    with sync_playwright() as p:
        try:
            browser = p.chromium.connect_over_cdp(cdp_url)
            # ... operations
        except Exception as e:
            print(f"CDP connection failed: {e}")

import { NotteClient } from 'notte-sdk';
import { chromium } from 'playwright-core';

const client = new NotteClient();

const status = await client.Session().use(async session => {
  const status = await session.status();
  const cdpUrl = status.cdp_url!;
  try {
    const browser = await chromium.connectOverCDP(cdpUrl);
    try {
      // ... operations
      return status;
    } finally {
      await browser.close();
    }
  } catch (error) {
    console.log(`CDP connection failed: ${error}`);
  }
});

When to Use Playwright with Notte

Use Playwright directly when you need:

Network interception: Block resources, modify requests/responses
Advanced event monitoring: Console logs, network events, page errors
Multiple pages: Drive several tabs of the same session in parallel
Playwright’s testing utilities: Screenshots with full-page scrolling, PDF generation, etc.

For most automation tasks, session.page (which is already Playwright-compatible) is sufficient.

Migrating from Selenium

Notte sessions are driven over CDP, so Playwright (or session.page, which is already a Playwright page) is the recommended way to port existing Selenium scripts. Here is a quick comparison:

Selenium	Playwright (Notte)
`driver.get(url)`	`page.goto(url)`
`driver.find_element(By.CSS_SELECTOR, "button")`	`page.locator("button")`
`element.click()`	`page.click("button")`
`element.send_keys("text")`	`page.fill("input", "text")`
`driver.execute_script("...")`	`page.evaluate("...")`
`WebDriverWait(driver, 10).until(...)`	`page.wait_for_selector("...")`
`driver.save_screenshot("path")`	`page.screenshot(path="path")`

Next Steps

Connect with Puppeteer

Use Puppeteer with Notte sessions

External Browser Providers

Connect Notte to Kernel.sh and other providers

Session Configuration

Configure session settings and features

Getting Started

Sessions

Authentication

Functions

Web API

Guides

Connect with Playwright

Connection URLs and recordings

Prerequisites

Connect Playwright to Notte Session

Use Both Notte and Playwright APIs

Async Playwright Support

Advanced: Multiple Pages

Network Interception

Browser Events and Monitoring

Best Practices

1. Use Context Managers

2. Prefer Notte’s Built-in Page

3. Session Timeout

4. Handle CDP Disconnections

When to Use Playwright with Notte

Migrating from Selenium

Next Steps

Connect with Puppeteer

External Browser Providers

Session Configuration

​Connection URLs and recordings

​Prerequisites

​Connect Playwright to Notte Session

​Use Both Notte and Playwright APIs

​Async Playwright Support

​Advanced: Multiple Pages

​Network Interception

​Browser Events and Monitoring

​Best Practices

​1. Use Context Managers

​2. Prefer Notte’s Built-in Page

​3. Session Timeout

​4. Handle CDP Disconnections

​When to Use Playwright with Notte

​Migrating from Selenium

​Next Steps

Connect with Puppeteer

External Browser Providers

Session Configuration

Connection URLs and recordings

Prerequisites

Connect Playwright to Notte Session

Use Both Notte and Playwright APIs

Async Playwright Support

Advanced: Multiple Pages

Network Interception

Browser Events and Monitoring

Best Practices

1. Use Context Managers

2. Prefer Notte’s Built-in Page

3. Session Timeout

4. Handle CDP Disconnections

When to Use Playwright with Notte

Migrating from Selenium

Next Steps