External Providers

Connect Notte to external browser infrastructure via Chrome DevTools Protocol

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:

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

Python

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:

Python

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:

Python

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:

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

When to Use Notte’s Browsers

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

1. Simplicity: One-line session creation without managing external services
2. Built-in Features: Anti-detection, captcha solving, proxies included
3. Integrated Management: Session replay, cookie management, file storage
4. 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:

Python

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:

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

Python

# 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:

1. Start Fresh: Create new browser instances for each session
2. Clean State: Clear cookies and cache between runs
3. Session Cleanup: Always close/delete external browser sessions
4. 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:[e-mail]: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