Set up Hyperbrowser with an AI agent

name: Hyperbrowser
description: Use when automating browser tasks at scale, scraping websites,
  running AI agents for web automation, or controlling cloud browsers with
  Playwright/Puppeteer. Reach for this skill for tasks requiring bot detection
  evasion, CAPTCHA solving, proxy rotation, multi-page workflows, or AI-powered
  browser automation.
metadata:
  mintlify-proj: hyperbrowser
  version: "1.0"

Hyperbrowser Skill

Product Summary

Hyperbrowser is a cloud browser platform for running automated browser sessions at scale. Control Chrome browsers in the cloud using Playwright, Puppeteer, or the Hyperbrowser SDK—no infrastructure management required. Use it to scrape websites, run AI agents (HyperAgent, Claude Computer Use, BrowserUse, Gemini, etc.), extract structured data, and automate complex web workflows. Key files: SDKs available for Node.js (@hyperbrowser/sdk) and Python (hyperbrowser). Primary docs: https://hyperbrowser.ai/docs

When to Use

Reach for Hyperbrowser when you need to:

• Automate browser tasks at scale — Create and manage hundreds of cloud browser sessions without managing infrastructure
• Scrape websites — Extract data from pages using the Scrape, Crawl, or Extract APIs
• Run AI agents — Execute HyperAgent, Claude Computer Use, BrowserUse, Gemini, or other AI agents on cloud browsers
• Evade bot detection — Use stealth mode, proxies, and CAPTCHA solving for sites with anti-bot protections
• Persist browser state — Save and reuse profiles with cookies and authentication across sessions
• Handle complex workflows — Manage multi-page navigation, form filling, and data extraction in a single task
• Monitor automation — Watch sessions live, record activity, and debug failures with video playback

Quick Reference

Session Creation (SDK)

Language	Command
Node.js	const session = await client.sessions.create({ useStealth: true, useProxy: true })
Python	session = client.sessions.create({"use_stealth": True, "use_proxy": True})
cURL	POST /api/session with JSON body

Common Session Options

Option	Type	Purpose
useStealth	boolean	Enable standard bot detection evasion
useUltraStealth	boolean	Maximum evasion (enterprise only)
useProxy	boolean	Route traffic through proxy
proxyCountry	string	Proxy location (e.g., "US", "GB")
solveCaptchas	boolean	Auto-solve CAPTCHA challenges
acceptCookies	boolean	Auto-accept cookie consent
screen	object	Viewport size: {width: 1280, height: 720}
timeoutMinutes	number	Session timeout (1-720 min)
profile.id	string	Reuse saved profile with cookies

Web Scraping APIs

API	Use Case
client.scrape.startAndWait()	Single page scrape (markdown, HTML, links)
client.scrape.batch.startAndWait()	Batch scrape up to 1,000 URLs
client.web.crawl.startAndWait()	Multi-page crawl with schema extraction
client.web.extract.startAndWait()	Extract structured data with Zod/Pydantic

AI Agent Methods

Agent	SDK Path	Best For
HyperAgent	client.agents.hyperAgent.startAndWait()	Playwright-based, cost-effective, extensible
BrowserUse	client.agents.browserUse.startAndWait()	Fast, open-source, DOM-focused
Claude Computer Use	client.agents.claudeComputerUse.startAndWait()	Robust, reliable, multi-step workflows
OpenAI CUA	client.agents.cua.startAndWait()	Accurate, slower, complex reasoning
Gemini Computer Use	client.agents.geminiComputerUse.startAndWait()	Fast, broad tool set
Meta Computer Use	client.agents.metaComputerUse.startAndWait()	Configurable reasoning effort
Grok Computer Use	client.agents.grokComputerUse.startAndWait()	Stateless reasoning replay

HyperAgent Core Methods

Method	Purpose
page.ai(prompt)	Multi-step task with AI decision-making
page.perform(action)	Single deterministic action
page.extract(prompt, schema)	Extract structured data with Zod schema

Decision Guidance

When to Use Stealth vs Ultra Stealth

Scenario	Use useStealth	Use useUltraStealth
Basic sites without bot detection	✗	✗
Sites with moderate bot detection	✓	✗
Highly protected sites (LinkedIn, etc.)	✓	✓
Enterprise requirement	✗	✓

When to Use Each Scraping API

Need	Use This
Single page, raw content	scrape.startAndWait()
Multiple URLs, same format	scrape.batch.startAndWait()
Follow links across site	web.crawl.startAndWait()
Structured data with schema	web.extract.startAndWait()

When to Use Each Agent

Requirement	Agent
Cost-effective, Playwright-compatible	HyperAgent
Fast, open-source, DOM-based	BrowserUse
Reliable, multi-step, reasoning	Claude Computer Use
Complex reasoning, accuracy over speed	OpenAI CUA
Speed, broad actions	Gemini Computer Use
Reusable sessions, profiles	HyperAgent + profiles

Playwright vs Puppeteer vs HyperAgent

Use Case	Playwright	Puppeteer	HyperAgent
Deterministic selectors	✓	✓	✗
Natural language commands	✗	✗	✓
Complex workflows	✓	✓	✓
AI-powered actions	✗	✗	✓
Cost per action	Low	Low	Medium

Workflow

1. Create and Connect to a Session

// Create session with stealth + proxy
const session = await client.sessions.create({
  useStealth: true,
  useProxy: true,
  proxyCountry: "US",
  screen: { width: 1280, height: 720 },
});

// Connect Playwright
const browser = await chromium.connectOverCDP(session.wsEndpoint);
const page = browser.contexts()[0].pages()[0];

2. Automate with Playwright or HyperAgent

Option A: Playwright (deterministic)

await page.goto("https://example.com");
await page.fill("input[name='search']", "query");
await page.click("button[type='submit']");

Option B: HyperAgent (AI-powered)

const agent = new HyperAgent();
const page = await agent.newPage();
await page.goto("https://example.com");
await page.ai("search for 'query' and click the first result");

3. Extract Data

// With HyperAgent
const data = await page.extract(
  "get product name, price, and rating",
  z.object({
    name: z.string(),
    price: z.number(),
    rating: z.number(),
  })
);

// With Scrape API
const result = await client.scrape.startAndWait({
  url: "https://example.com",
  scrapeOptions: { formats: ["markdown", "html"] },
});

4. Run AI Agent Task

const result = await client.agents.hyperAgent.startAndWait({
  task: "Go to example.com, search for 'laptop', and extract the top 3 results",
  maxSteps: 20,
  sessionOptions: { useStealth: true },
});

console.log(result.data?.finalResult);

5. Clean Up

// Stop session
await client.sessions.stop(session.id);

// Or close HyperAgent
await agent.closeAgent();

Common Gotchas

• Sessions timeout silently — Always use try-finally to stop sessions, even on error. Sessions auto-close after timeout (default varies by plan).
• Stealth + Proxy required together — Always enable useStealth or useUltraStealth when using proxies. Proxy alone is easily detected.
• CAPTCHA solving is slow — Only enable solveCaptchas: true when necessary. It adds 5-10 seconds per page.
• Profiles take time to save — After closing a session with profile.persistChanges: true, wait a few seconds before reusing the profile ID.
• Screen size affects AI agents — Keep default 1280x720 for AI agents. Larger screens degrade model performance.
• Batch scrape limited to 1,000 URLs — Split larger jobs into multiple batch requests.
• WebSocket endpoint expires — Reconnect if the session is idle for too long; check session status first.
• Proxy + CAPTCHA solving requires paid plan — Free tier cannot use these features together.
• HyperAgent needs LLM API keys — Set OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_API_KEY environment variables.
• Agent tasks are async by default — Use startAndWait() for blocking behavior, or poll status manually with getStatus().
• Credentials must be attached at session creation — Cannot add credentials to an active session; create a new one.
• Profile IDs are UUIDs — Save profile IDs from the response; they're not human-readable.

Verification Checklist

Before submitting work with Hyperbrowser:

• Session is stopped in finally block (no resource leaks)
• Stealth mode enabled if target site has bot detection
• Proxy enabled if stealth mode is on
• Screen size is 1280x720 for AI agents (or justified otherwise)
• CAPTCHA solving only enabled when necessary
• Credentials attached at session creation, not after
• Profile ID saved if persistence needed
• Agent task has clear, specific prompt (not vague)
• maxSteps set appropriately (10-20 for simple, 50+ for complex)
• Error handling includes session cleanup
• API key has correct scopes (browser.sessions.create, etc.)
• Timeout is reasonable for task complexity
• Batch scrape URLs ≤ 1,000 per request
• Recording enabled for debugging if task fails
• Results validated before returning to user

Resources

Comprehensive navigation: https://hyperbrowser.ai/docs/llms.txt

Critical documentation pages:

• Sessions & Configuration — Create and configure cloud browser sessions
• HyperAgent Overview — AI-powered browser automation with natural language
• Web Scraping APIs — Scrape, crawl, and extract structured data
• AI Agents Overview — Run Claude, BrowserUse, Gemini, and other agents
• API Reference — Complete REST API documentation

---

For additional documentation and navigation, see: https://hyperbrowser.ai/docs/llms.txt