browser-cloud

# 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](https://testmuai.com/) 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 ```typescript 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. ```typescript 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. ```typescript // 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. ```typescript 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. ```typescript // 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. ```typescript const results = await Promise.all( urls.map(url => browserTask(url)) ); ``` Always add `releaseAll()` in the shutdown handler: ```typescript process.on('SIGINT', async () => { await client.sessions.releaseAll(); process.exit(0); }); ``` --- ## Step 5 — Framework Integration ### LangChain (TypeScript) ```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: ```typescript // 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. ```bash 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](https://testmuai.com/) → 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](https://testmuai.com/) after sign-in).