> ## Documentation Index
> Fetch the complete documentation index at: https://notte-experiment-visibility-md-links.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 Python theme={null}
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 Python theme={null}
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](/integrations/kernel.md) guide for complete setup instructions and examples.
## BrowserBase Integration
BrowserBase provides managed browser infrastructure. Connect it to Notte:
```python Python theme={null}
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:
Use Notte's Agent to automate complex tasks with natural language
Execute high-level actions with automatic element detection
Extract data into structured formats with AI-powered scraping
Get AI-powered page understanding and element analysis
## Complete Example: Multi-Provider Setup
Run the same automation across different providers:
```python Python theme={null}
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 Python theme={null}
# 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:
{/* @sniptest testers/sessions/cdp/external_cdp_auth.py */}
```python external_cdp_auth.py theme={null}
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:
{/* @sniptest testers/sessions/cdp/external_cleanup.py */}
```python external_cleanup.py theme={null}
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:
{/* @sniptest testers/sessions/cdp/external_error_handling.py */}
```python external_error_handling.py theme={null}
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:
{/* @sniptest testers/sessions/cdp/external_monitor_costs.py */}
```python external_monitor_costs.py theme={null}
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
Complete Kernel.sh integration guide
Learn about session configuration options
Use Playwright directly with sessions
Manage session states