External Providers

AI agent instructions

STOP. Do not read past this section until you have read and followed /quickstart.md.Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live observe() call, CLI notte page observe output, or generated workflow code. Guessed browser targets fail on real pages.Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with notte sessions workflow-code before using SDK docs or SDK code.SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.

Notte can connect to any browser that exposes a Chrome DevTools Protocol (CDP) endpoint. This allows you to use Notte’s features (Agents, Actions, Scraping) with browser infrastructure from providers like Kernel.sh or BrowserBase.

How It Works

Instead of starting a browser in Notte’s cloud, you can:

Create a browser session with an external provider
Get the CDP WebSocket URL from that provider
Pass the CDP URL to Notte when creating a session
Use Notte’s features on the external browser

from notte_sdk import NotteClient

client = NotteClient()

# CDP URL from any external provider
cdp_url = "ws://external-provider.com:9222/devtools/browser/abc123"

# Connect Notte to the external browser
with client.Session(cdp_url=cdp_url) as session:
    # Use Notte's features on the external browser
    page = session.page
    page.goto("https://example.com")

    # Use Notte's Agent
    agent = client.Agent(session=session, max_steps=10)
    result = agent.run(task="Extract all product names")

Kernel.sh Integration

Kernel.sh is a browser infrastructure platform optimized for AI agents. Here’s how to use it with Notte:

from notte_sdk import NotteClient
from kernel import Kernel

# Initialize clients
client = NotteClient()
kernel = Kernel()

# Create browser on Kernel
kernel_browser = kernel.browsers.create()

try:
    # Connect Notte to Kernel's browser
    with client.Session(cdp_url=kernel_browser.cdp_ws_url) as session:
        # Use Notte's features
        page = session.page
        page.goto("https://example.com")

        # Run an Agent
        agent = client.Agent(session=session, max_steps=10)
        result = agent.run(task="Find the contact email")

        print(f"Result: {result.answer}")

finally:
    # Clean up Kernel browser
    kernel.browsers.delete_by_id(kernel_browser.session_id)

See the Kernel.sh Integration guide for complete setup instructions and examples.

BrowserBase Integration

BrowserBase provides managed browser infrastructure. Connect it to Notte:

from notte_sdk import NotteClient
import requests

client = NotteClient()

# Create session on BrowserBase (using their API)
browserbase_response = requests.post(
    "https://api.browserbase.com/v1/sessions",
    headers={"Authorization": f"Bearer {BROWSERBASE_API_KEY}"},
    json={"projectId": "your-project-id"}
)

session_data = browserbase_response.json()
cdp_url = session_data["cdpUrl"]

try:
    # Connect Notte to BrowserBase
    with client.Session(cdp_url=cdp_url) as session:
        page = session.page
        page.goto("https://example.com")

        # Use Notte's scraping
        result = session.scrape(
            instruction="Get all article titles",
            schema={"titles": ["string"]}
        )

        print(result)

finally:
    # Clean up BrowserBase session
    requests.delete(
        f"https://api.browserbase.com/v1/sessions/{session_data['id']}",
        headers={"Authorization": f"Bearer {BROWSERBASE_API_KEY}"}
    )

Benefits of External Providers

When to Use External Providers

Use external browser providers when you need:

Specialized Infrastructure: Provider-specific optimizations or features
Existing Setup: You already use a browser provider and want to add Notte’s features
Compliance: Browsers must run in specific regions or under specific conditions
Custom Configuration: Complex browser setups or extensions
Cost Optimization: Leverage existing browser infrastructure contracts

When to Use Notte’s Browsers

Use Notte’s built-in browsers when you want:

Simplicity: One-line session creation without managing external services
Built-in Features: Anti-detection, captcha solving, proxies included
Integrated Management: Session replay, cookie management, file storage
Fast Setup: No additional configuration or API keys needed

What Notte Adds to External Browsers

When you connect Notte to an external browser, you get:

AI Agents

Use Notte’s Agent to automate complex tasks with natural language

Smart Actions

Execute high-level actions with automatic element detection

Structured Scraping

Extract data into structured formats with AI-powered scraping

Observation API

Get AI-powered page understanding and element analysis

Complete Example: Multi-Provider Setup

Run the same automation across different providers:

from notte_sdk import NotteClient
from kernel import Kernel
from typing import Literal

client = NotteClient()

def run_automation(provider: Literal["notte", "kernel"], task: str):
    """Run automation on different browser providers"""

    if provider == "notte":
        # Use Notte's browser
        with client.Session() as session:
            agent = client.Agent(session=session)
            result = agent.run(task=task)
            return result

    elif provider == "kernel":
        # Use Kernel's browser
        kernel = Kernel()
        kernel_browser = kernel.browsers.create()

        try:
            with client.Session(cdp_url=kernel_browser.cdp_ws_url) as session:
                agent = client.Agent(session=session)
                result = agent.run(task=task)
                return result
        finally:
            kernel.browsers.delete_by_id(kernel_browser.session_id)

# Run on Notte's infrastructure
result1 = run_automation("notte", "Get the latest news from example.com")
print(f"Notte result: {result1.answer}")

# Run on Kernel's infrastructure
result2 = run_automation("kernel", "Get the latest news from example.com")
print(f"Kernel result: {result2.answer}")

Supported CDP Features

When using external browsers, Notte supports: ✅ Supported:

Page navigation and interaction via Playwright
Agent-based automation
Structured scraping with scrape()
Action execution with execute()
Page observation with observe()
Screenshot capture
JavaScript execution
Cookie management
Session replay recording
Live viewer

❌ Not Available:

Notte’s built-in anti-detection (use provider’s features instead)
Notte’s captcha solving (use provider’s features instead)
Notte’s proxy management (use provider’s proxies)

Troubleshooting

CDP Connection Failures

If connection fails, verify:

URL Format: Ensure the CDP URL is correct (ws:// or wss:// prefix)
Network Access: Check firewalls and network policies
Browser Availability: Verify the browser is running and accessible
Timeout: Increase session timeout for slow connections

# Add timeout and error handling
try:
    with client.Session(
        cdp_url=cdp_url,
        timeout_minutes=15  # Longer timeout
    ) as session:
        page = session.page
        page.goto("https://example.com")
except Exception as e:
    print(f"CDP connection failed: {e}")
    # Handle error or retry

Browser State Issues

When using external browsers:

Start Fresh: Create new browser instances for each session
Clean State: Clear cookies and cache between runs
Session Cleanup: Always close/delete external browser sessions
Resource Limits: Monitor memory and CPU usage

Authentication

Some providers require authentication in the CDP URL:

external_cdp_auth.py

from notte_sdk import NotteClient

client = NotteClient()

# CDP URL with authentication
cdp_url = "wss://user:password@provider.com:9222/devtools/browser/abc123"

with client.Session(cdp_url=cdp_url) as session:
    # Your automation
    pass

Provider Comparison

Feature	Notte Built-in	Kernel.sh + Notte	BrowserBase + Notte
Setup Complexity	Simple	Simple	Medium
Anti-detection	✅ Built-in	✅ Built-in	✅ Built-in
Captcha Solving	✅ Optional	❌	❌
Residential Proxies	✅ Optional	✅	✅
Session Replay	✅ Yes	✅ Via Notte	✅ Via Notte
Live Viewer	✅ Yes	✅ Yes	✅ Yes
Pricing	Per session	Per session	Per session

Best Practices

1. Clean Up Resources

Always clean up external browser sessions:

external_cleanup.py

        pass


provider = Provider()
client = NotteClient()

try:
    # Create external browser
    external_browser = provider.create()

    # Use with Notte
    with client.Session(cdp_url=external_browser.cdp_url) as session:
        # Your automation

2. Handle Errors Gracefully

CDP connections can fail. Always use try-except:

external_error_handling.py

from notte_sdk import NotteClient

client = NotteClient()

cdp_url = "wss://provider.com:9222/devtools/browser/abc123"

try:
    with client.Session(cdp_url=cdp_url) as session:
        # Your automation
        pass
except Exception as e:
    print(f"Automation failed: {e}")
    # Implement retry logic or fallback

3. Choose the Right Provider

High Volume: Use managed providers (Kernel, BrowserBase)
Simplicity: Use Notte’s built-in browsers
Existing Infrastructure: Connect to your current provider setup

4. Monitor Costs

External providers typically charge per session or minute. Monitor usage:

external_monitor_costs.py

import time

from notte_sdk import NotteClient

client = NotteClient()

cdp_url = "wss://provider.com:9222/devtools/browser/abc123"

start = time.time()

with client.Session(cdp_url=cdp_url) as session:
    # Your automation
    pass

duration = time.time() - start
print(f"Session duration: {duration:.2f} seconds")

Next Steps

Kernel.sh Integration

Complete Kernel.sh integration guide

Session Configuration

Learn about session configuration options

Connect with Playwright

Use Playwright directly with sessions

Session Lifecycle

Manage session states

Getting Started

Sessions

Agents

Functions

Agent Tools

Scraping

Guides

Integrations

External Providers

How It Works

Kernel.sh Integration

BrowserBase Integration

Benefits of External Providers

When to Use External Providers

When to Use Notte’s Browsers

What Notte Adds to External Browsers

AI Agents

Smart Actions

Structured Scraping

Observation API

Complete Example: Multi-Provider Setup

Supported CDP Features

Troubleshooting

CDP Connection Failures

Browser State Issues

Authentication

Provider Comparison

Best Practices

1. Clean Up Resources

2. Handle Errors Gracefully

3. Choose the Right Provider

4. Monitor Costs

Next Steps

Kernel.sh Integration

Session Configuration

Connect with Playwright

Session Lifecycle

​How It Works

​Kernel.sh Integration

​BrowserBase Integration

​Benefits of External Providers

​When to Use External Providers

​When to Use Notte’s Browsers

​What Notte Adds to External Browsers

AI Agents

Smart Actions

Structured Scraping

Observation API

​Complete Example: Multi-Provider Setup

​Supported CDP Features

​Troubleshooting

​CDP Connection Failures

​Browser State Issues

​Authentication

​Provider Comparison

​Best Practices

​1. Clean Up Resources

​2. Handle Errors Gracefully

​3. Choose the Right Provider

​4. Monitor Costs

​Next Steps

Kernel.sh Integration

Session Configuration

Connect with Playwright

Session Lifecycle

How It Works

Kernel.sh Integration

BrowserBase Integration

Benefits of External Providers

When to Use External Providers

When to Use Notte’s Browsers

What Notte Adds to External Browsers

Complete Example: Multi-Provider Setup

Supported CDP Features

Troubleshooting

CDP Connection Failures

Browser State Issues

Authentication

Provider Comparison

Best Practices

1. Clean Up Resources

2. Handle Errors Gracefully

3. Choose the Right Provider

4. Monitor Costs

Next Steps