Skip to main content

Claude Agent SDK

The Claude Agent SDK lets you build autonomous AI agents powered by Claude. Unlike simple chat completions, agents execute tools autonomously, persist across multiple turns, and use MCP servers to extend capabilities. By connecting to Browserless, your agents can browse bot-protected websites with stealth mode, automatic CAPTCHA solving, and residential proxies. All without local browser infrastructure.

Prerequisites​

Quick start​

1. Set your API keys​

Go to your Browserless account dashboard and copy your API token. You will also need an Anthropic API key.

Set both as environment variables:

BROWSERLESS_API_KEY=your-browserless-token
ANTHROPIC_API_KEY=your-anthropic-key

2. Install dependencies​

Install the Claude Agent SDK alongside Playwright and Zod:

npm install @anthropic-ai/claude-agent-sdk playwright-core zod

3. Connect to Browserless​

The key change is connecting Playwright to Browserless via CDP instead of launching a local browser:

import { chromium } from "playwright-core";

// Browserless connection with stealth + CAPTCHA solving
const BROWSERLESS_URL = `wss://production-sfo.browserless.io/stealth?token=${process.env.BROWSERLESS_API_KEY}&solveCaptchas=true&timeout=300000`;

// Connect via CDP (instead of chromium.launch())
const browser = await chromium.connectOverCDP(BROWSERLESS_URL);
const context = browser.contexts()[0] || await browser.newContext();
const page = context.pages()[0] || await context.newPage();

4. Add system prompt guidance​

Claude doesn't know Browserless handles CAPTCHAs automatically. Add these rules to your system prompt:

systemPrompt: `You have access to a Browserless cloud browser via the execute_playwright MCP tool.
The browser has stealth mode and automatic CAPTCHA solving enabled at the infrastructure level.

IMPORTANT RULES:
1. ALWAYS use execute_playwright for web interactions. Do NOT use WebFetch or other tools.
2. The 'page' and 'browser' objects are ALREADY CONNECTED. Do NOT call connectOverCDP yourself.
3. If you encounter a CAPTCHA or challenge page, wait 15-30 seconds and check again — it will be solved automatically.
4. Return data from your code using: return yourData;
5. ALWAYS use a long timeout on page.goto() to allow time for CAPTCHA solving.
6. Complete ALL your work in a SINGLE execute_playwright call. Do NOT make multiple separate calls.`

5. Test it​

Run your script with a command and pass a prompt as the argument:

npx tsx your-agent.ts "Go to https://news.ycombinator.com and get the top 5 story titles"

Connection URL anatomy​

The Browserless WebSocket URL controls which features are active for the session:

wss://production-sfo.browserless.io/stealth?token=YOUR_API_TOKEN&solveCaptchas=true&timeout=300000&proxy=residential&blockAds=true
SegmentPurpose
production-sfo.browserless.ioRegional endpoint (US West). See Connection URLs for all regions
/stealthStealth route: hides automation signals, spoofs fingerprints
token=Your Browserless API token
solveCaptchas=trueAutomatically detects and solves CAPTCHAs (reCAPTCHA, Cloudflare Turnstile, DataDome, and more)
timeout=300000Session timeout in ms (5 minutes). Allows time for CAPTCHA solving
proxy=residentialRoute through residential IPs for better IP reputation
blockAds=trueBlock ads and trackers for cleaner page loads
Cloud browser without stealth or CAPTCHA solving

If you don't need anti-detection or automatic CAPTCHA solving and just want Browserless as managed cloud browser infrastructure, use the standard route and omit solveCaptchas:

wss://production-sfo.browserless.io?token=YOUR_API_TOKEN

You still get a fully managed, remote browser, just without the stealth fingerprinting and CAPTCHA solving layers.

How stealth mode works​

The /stealth route automatically applies anti-detection techniques before your agent interacts with any page:

  • Hides navigator.webdriver and other automation signals
  • Spoofs browser fingerprints (canvas, WebGL, fonts)
  • Randomizes user-agent strings
  • Mimics human-like behavior patterns

No code changes needed. The protections are applied at the browser level, transparently to Playwright and the Claude Agent SDK.

How automatic CAPTCHA solving works​

With solveCaptchas=true in your connection URL, Browserless monitors every page for CAPTCHA challenges and solves them in the background:

  1. Detects CAPTCHAs by monitoring network requests for known patterns (reCAPTCHA, Cloudflare Turnstile, DataDome, and more)
  2. Solves them programmatically using Browserless's solving engine
  3. Continues once solved. Your agent sees the unblocked page

Solving typically takes 15 to 60 seconds depending on complexity. The system prompt should instruct your agent to wait and retry if it encounters a challenge page.

note

Each CAPTCHA solve attempt costs 10 units. Using /stealth and residential proxies reduces how often CAPTCHAs appear in the first place.

Example use cases​

The integration works well for tasks that would normally trigger bot detection:

Scrape bot-protected review sites:

"Go to https://www.g2.com/products/browserless-io/reviews and get the reviews"

Extract product data from e-commerce:

"Navigate to https://www.amazon.com/dp/B09V3KXJPB and get the product title and price"

Research news sites:

"Go to https://news.ycombinator.com and get the top 5 story titles"

Multi-step workflows:

"Search Google for 'best headless browser 2026', click the first result, and summarize the page"

Troubleshooting​

Claude tries to solve CAPTCHAs manually​

Add clear instructions to your system prompt that CAPTCHAs solve automatically and to wait 15 to 30 seconds. See step 4 above.

Connection timeout on page.goto()​

Use a long timeout: page.goto(url, { timeout: 120000, waitUntil: 'domcontentloaded' })

The default 30-second timeout isn't enough when CAPTCHA solving is happening.

"Target page, context or browser has been closed"​

This means the Browserless session expired. Solutions:

  • Increase session timeout in URL: &timeout=300000 (5 minutes)
  • Instruct Claude to complete all work in a single tool call
  • The code automatically reconnects on the next tool call

Site still blocks the browser​

Layer your defenses:

  1. Use the /stealth route (anti-detection)
  2. Add proxy=residential (IP reputation)
  3. Add solveCaptchas=true (CAPTCHA challenges)

"WebSocket connection failed"​

Check that:

  • Your BROWSERLESS_API_KEY is set correctly
  • You have available units in your Browserless account
  • The regional endpoint is accessible from your network

Resources​