browser-cloud

You write production-grade TypeScript code that connects AI agents to the real web using TestMu AI Browser Cloud. No local Chrome required. Agents get real, stealth-patched, observable cloud browsers on demand.

What You Build

Every output from this skill is runnable TypeScript that:

Creates an isolated cloud browser session on TestMu AI infrastructure
Connects via the agent's preferred adapter (Puppeteer / Playwright / Selenium)
Executes the requested browser task (scrape, screenshot, PDF, form fill, auth, etc.)
Handles cleanup and observability automatically
Integrates into the agent's framework without friction

Step 1 — Understand the Request

Extract these before writing code:

Signal	What to determine
Task type	Scrape content, screenshot, PDF, form fill, login + persist, monitor, download file, interact with app
Agent framework	LangChain, CrewAI, AutoGen, OpenAI functions, custom loop, or standalone script
Adapter preference	Puppeteer (default), Playwright, or Selenium
Auth needed	Does the target site require login? Reuse session?
Local access	Does the agent need localhost or internal URLs? → tunnel
Stealth needed	Is the target behind bot detection?
Scale	Single run vs. repeated cron vs. parallel agents

If the user does not specify adapter: default to Puppeteer. If the user does not specify framework: output a standalone async function the user can wrap into any framework.

Step 2 — Choose the Right Pattern

Read the task and match it to one of these patterns. Each has a reference implementation in /references/.

Pattern	When to use	Reference
Quick Action	One-off scrape, screenshot, or PDF — no interaction needed	`references/patterns/quick-actions.md`
Session + Navigate	Multi-step navigation, form interaction, JS-heavy pages	`references/patterns/session-navigate.md`
Auth + Profile	Login once, reuse session across runs (cron / serverless)	`references/patterns/auth-profile.md`
Parallel Sessions	Multiple agents / tasks running simultaneously	`references/patterns/parallel-sessions.md`
Tunnel + Localhost	Agent must reach local dev server, staging, or VPN URLs	`references/patterns/tunnel.md`
LangChain Tool	Wrap browser actions as LangChain Tool for agent chain	`examples/langchain-browser-tool.ts`
CrewAI Tool	Wrap as CrewAI BaseTool for crew workflows	`references/integrations/crewai.md`
OpenAI Function	Define as function_call / tool for GPT-4 agent loops	`references/integrations/openai-functions.md`
File Upload/Download	Agent needs to upload docs or download reports from cloud browser	`references/patterns/files.md`

Step 3 — Write the Code

Non-negotiable rules for every code output

Always use try/finally to release sessions. Sessions left open waste quota and money.
Credentials via env vars only. Never hardcode LT_USERNAME or LT_ACCESS_KEY.
Name builds and tests. Always set build and name in lambdatestOptions — makes runs easy to find in the TestMu AI automation dashboard.
Set explicit timeout. Default is 5 min. Agent workflows often need 10–30 min: timeout: 1800000.
Return structured data. Agent tools must return typed objects, not raw strings. Define an interface.
Export the function. All agent tools should be exportable, not just top-level scripts.
Install the SDK if the project does not have it. Before writing or running Browser Cloud code in the user's repo, check package.json: if @testmuai/browser-cloud is missing from dependencies or devDependencies, install it using the project's package manager (detect via lockfile: pnpm-lock.yaml → pnpm add @testmuai/browser-cloud, yarn.lock → yarn add @testmuai/browser-cloud, else npm i @testmuai/browser-cloud). If there is no package.json in the workspace, run npm init -y then npm i @testmuai/browser-cloud in the intended project root, or add the dependency in the manifest the user is using. Do not skip install when you have shell access and the dependency is absent.

Code template — base structure

import { Browser } from '@testmuai/browser-cloud';

const client = new Browser();

export interface BrowserTaskResult {
  success: boolean;
  data?: unknown;
  error?: string;
  sessionViewerUrl?: string;
}

export async function browserTask(input: string): Promise<BrowserTaskResult> {
  const session = await client.sessions.create({
    adapter: 'puppeteer',
    timeout: 1800000,
    stealthConfig: {
      humanizeInteractions: true,
      randomizeUserAgent: true,
    },
    lambdatestOptions: {
      build: 'Agent: <TaskName>',
      name: input.slice(0, 80),
      'LT:Options': {
        username: process.env.LT_USERNAME!,
        accessKey: process.env.LT_ACCESS_KEY!,
        video: true,
        console: true,
      },
    },
  });

  try {
    const browser = await client.puppeteer.connect(session);
    const page = (await browser.pages())[0];

    // --- task logic here ---

    await browser.close();
    return { success: true, data: null, sessionViewerUrl: session.sessionViewerUrl };
  } catch (err) {
    return { success: false, error: String(err) };
  } finally {
    await client.sessions.release(session.id);
  }
}

Step 4 — Add the Right Capabilities

Layer in only what the task actually needs. Do not add capabilities the task does not require.

Stealth (bot detection avoidance)

Add when: target site has Cloudflare, bot.sannysoft.com-style checks, or blocks headless browsers.

stealthConfig: {
  humanizeInteractions: true,  // random delays on click/type
  randomizeUserAgent: true,    // pool of 7 real Chrome/Firefox UAs
  randomizeViewport: true,     // ±20px jitter on viewport
}

Auth persistence across runs

Add when: agent logs in to a service and runs on a schedule or as serverless.

// In session config:
profileId: 'service-name-login',  // auto-saves cookies on browser.close()

// On first run, agent logs in normally.
// On all subsequent runs, cookies are restored — login page is skipped.

See full pattern: references/patterns/auth-profile.md

Tunnel (localhost / staging access)

Add when: agent must reach localhost, *.internal, or VPN-gated URLs.

tunnel: true,
tunnelName: 'agent-tunnel',
// Then: await page.goto('http://localhost:3000') works from the cloud.

Context transfer (session-to-session auth in same script)

Add when: agent creates multiple sessions in one script run and needs to share login state.

// After login in session 1:
const ctx = await client.context.getContext(page1);

// In session 2:
await client.context.setContext(page2, ctx);
// Already authenticated — no re-login.

Parallel sessions

Add when: agent runs multiple browser tasks concurrently.

const results = await Promise.all(
  urls.map(url => browserTask(url))
);

Always add releaseAll() in the shutdown handler:

process.on('SIGINT', async () => { await client.sessions.releaseAll(); process.exit(0); });

Step 5 — Framework Integration

LangChain (TypeScript)

import { Tool } from 'langchain/tools';

class BrowserCloudTool extends Tool {
  name = 'browser-cloud';
  description = 'Browse any URL, scrape content, take screenshots, or fill forms using a real cloud browser. Input: URL or task description.';

  async _call(input: string): Promise<string> {
    const result = await browserTask(input);
    return JSON.stringify(result);
  }
}

CrewAI (Python — call SDK via subprocess or API when REST is available)

See references/integrations/crewai.md for the wrapper pattern using the planned REST API or a Node.js subprocess bridge.

OpenAI function calling

See references/integrations/openai-functions.md for the function definition schema and handler.

Standalone / custom agent loop

The exported function works directly — call it from any async context, pass the result back to the LLM.

Adapter Selection Guide

Scenario	Use
Most agent use cases	Puppeteer — best stealth, simplest return type (`Browser`)
Complex form interaction, auto-waiting	Playwright — `page.fill()`, built-in waits, returns `{browser, context, page}`
Existing Selenium test suite	Selenium — connects to TestMu hub via HTTP/WebDriver
Node.js < 18	Puppeteer or Selenium — Playwright requires Node 18+

Quick Actions (no session management)

For one-off operations where the agent does not interact beyond data extraction:

// Scrape — format options: 'html' | 'text' | 'markdown' | 'readability'
const scraped = await client.scrape({ url, format: 'markdown', waitFor: '#content' });

// Screenshot
const shot = await client.screenshot({ url, fullPage: true, format: 'png' });
fs.writeFileSync('out.png', shot.data);

// PDF
const pdf = await client.pdf({ url, format: 'A4', printBackground: true });
fs.writeFileSync('out.pdf', pdf.data);

Quick Actions spin up a temporary headless browser, execute, and clean up automatically.

Output Checklist

Before finalizing any code output, verify:

@testmuai/browser-cloud is listed in package.json or was installed in this session when it was missing
Credentials come from process.env.LT_USERNAME and process.env.LT_ACCESS_KEY
try/finally wraps all browser work with client.sessions.release(session.id) in finally
build and name set in lambdatestOptions
timeout set explicitly (not relying on 5-min default for agent workflows)
Function is exported and accepts typed input, returns typed output
Stealth config included if the target site is likely to block headless browsers
SIGINT handler added if the script manages multiple sessions or runs as a long-lived process
.env file setup instructions included in comments or a README block

Reference Files in This Skill

references/
  patterns/
    quick-actions.md        — scrape / screenshot / PDF one-liners
    session-navigate.md     — multi-step navigation and interaction
    auth-profile.md         — login once, persist across runs
    parallel-sessions.md    — concurrent agent sessions
    tunnel.md               — localhost and internal network access
    files.md                — upload/download between agent and cloud browser
  integrations/
    crewai.md               — CrewAI BaseTool wrapper (Python + subprocess bridge)
    openai-functions.md     — OpenAI and Anthropic function calling definition
examples/
  scrape-agent.ts           — standalone scraping agent
  form-fill-agent.ts        — form interaction with stealth
  auth-persist-agent.ts     — login + profile persistence
  parallel-research.ts      — parallel scraping across multiple URLs
  langchain-browser-tool.ts — LangChain tools: scrape, screenshot, multi-action, structured

Environment Setup (always include in output)

If the user's project already declares @testmuai/browser-cloud, skip reinstall unless they ask to upgrade. Otherwise install per non-negotiable rule 7 above, then document the command you used.

npm i @testmuai/browser-cloud
# Node.js 16+ required. Playwright adapter requires Node 18+.

# .env
LT_USERNAME=your_testmuai_username
LT_ACCESS_KEY=your_testmuai_access_key

Credentials: TestMu AI → sign in → Account Settings (same username/access key pair as for Browser Cloud / automation).

Session logs: After each run, video, console, and network capture appear in your TestMu AI automation session history (open the dashboard from testmuai.com after sign-in).