---
name: browser-use
description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, or extract information from web pages.
license: MIT
metadata:
  author: browser-use
  version: "1.1.0"
  domain: engineering
  subdomain: browser-automation
  triggers: browser-use, browser automation, web scraping, form filling, screenshot, cloud browser, playwright cdp, session replay, workspace files, profile sync
  role: engineer
  scope: implementation
---

# Browser Use

Use Browser Use Cloud SDK and API to run browser agents and raw browser sessions.

## When To Use

- Navigate websites and extract structured data
- Fill forms and execute multi-step workflows
- Stream live browser actions and agent messages
- Reuse sessions, profiles, and workspaces across tasks
- Connect Playwright/Puppeteer via CDP to cloud browsers

## Install

```bash
pip install browser-use-sdk
export BROWSER_USE_API_KEY=your_key
```

TypeScript:

```bash
npm install browser-use-sdk
```

## Quick Start (v3 SDK)

```python
from browser_use_sdk.v3 import AsyncBrowserUse

client = AsyncBrowserUse()
result = await client.run("List the top 20 posts on Hacker News today with their points")
print(result.output)
```

```typescript
import { BrowserUse } from "browser-use-sdk/v3";

const client = new BrowserUse();
const result = await client.run("List the top 20 posts on Hacker News today with their points");
console.log(result.output);
```

## Core Patterns

- `run()` for one-shot tasks: auto create + poll + return output.
- `sessions.create()` + `session_id` for follow-up tasks with shared browser state.
- `workspaces.*` for file upload/download workflows.
- `profiles.*` for login persistence and recurring automation.
- `browsers.create()` for raw CDP control (Playwright/Puppeteer).

### Follow-up task pattern

```python
session = await client.sessions.create()
await client.run("Go to amazon.com and open first laptop", session_id=session.id)
await client.run("Extract customer reviews", session_id=session.id)
await client.sessions.stop(session.id)
```

### Structured output

- Python: pass `output_schema` (Pydantic).
- TypeScript: pass `schema` (Zod v4 required).

### Stream messages

- Iterate over `client.run(...)` to receive live messages.
- `run.result` is valid only after iteration completes.

### Deterministic rerun (cache-script)

- Use `@{{...}}` placeholders in task plus `workspace_id`.
- First run builds script, next runs can execute without LLM.
- `cache_script`: `None` (auto), `True` (force), `False` (disable).

## Agent vs Browser

- Agent mode: `client.run(...)`, `client.sessions.*`.
- Browser mode: `client.browsers.create(...)` returns `cdp_url` + `live_url`.
- Use browser mode when you need custom CDP automation with Playwright/Puppeteer.

## Authentication and Persistence

- API key env: `BROWSER_USE_API_KEY`.
- Header for direct API calls: `X-Browser-Use-API-Key: <key>`.
- For user-specific state: create one profile per user and reuse `profile_id`.

## Operations Checklist

- Always stop sessions/browsers when done to avoid idle charges.
- Always stop profiled sessions to persist cookies/localStorage correctly.
- Sessions idle-timeout after 15 minutes; max duration is 4 hours.
- Recording links are presigned and expire quickly (about 1 hour).

## Common Gotchas

- If streaming loop is interrupted early, cancel with `sessions.stop(..., strategy="task")` before sending another task.
- TypeScript structured output fails with Zod v3; use Zod v4.
- Selenium remote CDP support is limited; prefer Playwright/Puppeteer for cloud CDP.
- Deleting a workspace is permanent.

## Reference

- Full LLM-optimized docs: `https://docs.browser-use.com/llms-full.txt`
- Quick index: `https://docs.browser-use.com/llms.txt`
- API key: `https://cloud.browser-use.com/settings?tab=api-keys&new=1`
