Anti-Detection Playbook

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.

Resolving Bot Detection Issues

Bot detection is a common challenge for web agents. This guide provides strategies to bypass these detection mechanisms using Notte’s stealth configuration options. Common Bot Detection Challenges:

Accessing e-commerce sites with anti-bot measures
Scraping content from news or social media platforms
Interacting with banking or financial websites
Accessing sites with geographic restrictions

Stealth Configuration Strategies

1. Proxy Configuration

Proxies are one of the most effective ways to bypass bot detection. Different proxy configurations can help you appear as legitimate traffic from various locations.

Using Default Proxies

Notte’s built-in residential proxies are enabled by default (proxies=True), so every session already routes through them unless you set proxies=False:

from notte_sdk import NotteClient

client = NotteClient()

# Start a session with built-in proxies
with client.Session(proxies=True) as session:
    result = session.execute(type="goto", url="https://www.notte.cc/")
    observation = session.observe()

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

const session = client.Session({
  proxies: true,
});
await session.use(async () => {
  await session.execute({ type: 'goto', url: 'https://www.notte.cc/' });
  await session.observe();
});

Country-Specific Proxies

For sites with geographic restrictions, use proxies from specific countries:

from notte_sdk import NotteClient
from notte_sdk.types import NotteProxy, ProxySettings

client = NotteClient()

# Shorthand: pass a country code
session = client.Session(proxies="fr")

# Equivalent explicit form
proxies: list[ProxySettings] = [NotteProxy.from_country("fr")]
session = client.Session(proxies=proxies)

import { NotteClient, type NotteProxy } from 'notte-sdk';

const client = new NotteClient();

// Route the session through a French residential proxy
const proxies: NotteProxy[] = [{ type: 'notte', country: 'fr' }];
const session = client.Session({ proxies });

2. CAPTCHA Solving

Automatic CAPTCHA solving is enabled by default (solve_captchas=True) for sites that use these challenges:

solve_captchas.py

from notte_sdk import NotteClient

client = NotteClient()
with client.Session(solve_captchas=True, open_viewer=True) as session:
    # Navigate to a page with a CAPTCHA
    agent = client.Agent(session=session, max_steps=5)
    resp = agent.run(
        task=("Try to solve the CAPTCHA using internal tools. If you fail, try to solve it manually."),
        url="https://www.google.com/recaptcha/api2/demo",
    )

Not all CAPTCHA types are supported. Some complex CAPTCHAs may still require manual intervention.

3. Advanced Stealth

For sites with sophisticated bot detection, start the session with advanced_stealth=True to use Notte’s highest-fidelity browser environment. Advanced stealth is available to approved workspaces; contact us to request access.

Complete Stealth Configuration Example

Here’s a comprehensive example combining all stealth techniques:

from notte_sdk import NotteClient

client = NotteClient()

# Example stealth configuration
# this is just one possible configuration, with an obvious fingerprint
# rotating those values will raise your chances
with client.Session(
    solve_captchas=True,
    proxies="us",
    user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
    viewport_width=1920,
    viewport_height=1080,
) as session:
    session.execute(type="goto", url="https://example.com")
    result = session.observe()
    print("Success with fallback configuration")

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

const session = client.Session({
  solve_captchas: true,
  proxies: [{ type: 'notte', country: 'us' }],
  user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
  viewport_width: 1920,
  viewport_height: 1080,
});
await session.use(async () => {
  await session.execute({ type: 'goto', url: 'https://example.com' });
  const result = await session.observe();
  console.log('Success with fallback configuration');
});

Troubleshooting Tips

Start Simple. Begin with basic configurations and gradually add complexity:
- Keep the defaults first (proxies=True, solve_captchas=True)
- Pick a proxy country that matches the target site
- Add custom user_agent if still detected
- Try advanced_stealth=True if your workspace has access
Test Incrementally. Test each configuration change individually to identify what works:
Monitor for Patterns. Keep track of which configurations work for different types of sites:
- E-commerce sites often respond well to residential proxies
- Social media sites may require specific user agents
- Banking sites may need country-specific proxies

Best Practices

Rotate Configurations: Don’t rely on a single configuration: it makes it easier to track you
Monitor Success Rates: Verify which configurations work best for different site types
Respect Rate Limits: Implement delays between requests to avoid triggering rate limiting
Keep Configurations Updated: Bot detection methods evolve, so regularly test and update your configurations

Getting Started

Sessions

Authentication

Functions

Web API

Guides

Anti-Detection Playbook

Resolving Bot Detection Issues

Stealth Configuration Strategies

1. Proxy Configuration

Using Default Proxies

Country-Specific Proxies

2. CAPTCHA Solving

3. Advanced Stealth

Complete Stealth Configuration Example

Troubleshooting Tips

Best Practices

​Resolving Bot Detection Issues

​Stealth Configuration Strategies

​1. Proxy Configuration

​Using Default Proxies

​Country-Specific Proxies

​2. CAPTCHA Solving

​3. Advanced Stealth

​Complete Stealth Configuration Example

​Troubleshooting Tips

​Best Practices

Resolving Bot Detection Issues

Stealth Configuration Strategies

1. Proxy Configuration

Using Default Proxies

Country-Specific Proxies

2. CAPTCHA Solving

3. Advanced Stealth

Complete Stealth Configuration Example

Troubleshooting Tips

Best Practices