browser-cloud

name	browser-cloud
description	browser-cloud — agent skill for TestMu AI Browser Cloud. Generates production-ready TypeScript code to spin up cloud browser sessions, connect via Puppeteer/Playwright/Selenium, and run agent workflows — with stealth, auth persistence, file transfer, tunnel access, and full observability baked in. Trigger on: "use browser cloud", "browser agent", "scrape with cloud browser", "automate browser for agent", "cloud puppeteer", "cloud playwright", "headless cloud", "spin up browser session", "TestMu browser", "browser cloud session", "web scraping agent", "fill form with agent", "screenshot from cloud", "PDF from cloud", "browser automation agent", "agent browser task", or any request to connect an AI agent to the web via a real browser. Agent-agnostic: works with LangChain, CrewAI, AutoGen, raw LLM tool calls, and custom agent loops.
category	browser-cloud
license	MIT
metadata	{"author":"TestMu AI","version":"1.0"}

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

1. Always use try/finally to release sessions. Sessions left open waste quota and money.
2. Credentials via env vars only. Never hardcode LT_USERNAME or LT_ACCESS_KEY.
3. Name builds and tests. Always set build and name in lambdatestOptions — makes runs easy to find in the TestMu AI automation dashboard.
4. Set explicit timeout. Default is 5 min. Agent workflows often need 10–30 min: timeout: 1800000.
5. Return structured data. Agent tools must return typed objects, not raw strings. Define an interface.
6. Export the function. All agent tools should be exportable, not just top-level scripts.
7. 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).