browser-use--browser-harness
Gregor Žunič
128 行
4.2 KiB
Markdown
128 行
4.2 KiB
Markdown
---
|
|
name: browser-harness
|
|
description: Always use browser-harness for any web interaction: automation, scraping, testing, or site/app work.
|
|
---
|
|
|
|
# browser-harness
|
|
|
|
Direct browser control via CDP. For task-specific edits, use `agent-workspace/agent_helpers.py`. For setup, install, or connection problems, read `install.md`.
|
|
|
|
Domain skills are off by default. Set `BH_DOMAIN_SKILLS=1` to enable them; see the bottom section.
|
|
|
|
**If `BH_DOMAIN_SKILLS=1` and the task is site-specific, read every file in the matching `$BH_AGENT_WORKSPACE/domain-skills/<site>/` directory before inventing an approach.**
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
browser-harness <<'PY'
|
|
print(page_info())
|
|
PY
|
|
```
|
|
|
|
- Invoke as `browser-harness`. Use heredocs for multi-line commands.
|
|
- Helpers are pre-imported. `run.py` calls `ensure_daemon()` before `exec`.
|
|
- First navigation is `new_tab(url)`, not `goto_url(url)`.
|
|
- The normal local flow attaches to the running Chrome/Chromium CDP endpoint. No browser ids or local profile selection.
|
|
|
|
## Local Chrome
|
|
|
|
If the daemon cannot connect, run diagnostics:
|
|
|
|
```bash
|
|
browser-harness --doctor
|
|
```
|
|
|
|
If Chrome remote debugging is not enabled, the harness opens:
|
|
|
|
```text
|
|
chrome://inspect/#remote-debugging
|
|
```
|
|
|
|
Ask the user to tick "Allow remote debugging for this browser instance" and click Allow if Chrome shows a permission popup. Then retry the same `browser-harness` command.
|
|
|
|
## Remote Browsers
|
|
|
|
Use Browser Use cloud for headless servers, parallel sub-agents, or isolated work. Authenticate once:
|
|
|
|
```bash
|
|
browser-harness auth login
|
|
```
|
|
|
|
Or import a key safely:
|
|
|
|
```bash
|
|
browser-harness auth login --api-key-stdin
|
|
```
|
|
|
|
Pick a short made-up name; `r7k2` below is just a placeholder:
|
|
|
|
```bash
|
|
browser-harness <<'PY'
|
|
start_remote_daemon("r7k2")
|
|
PY
|
|
|
|
BU_NAME=r7k2 browser-harness <<'PY'
|
|
new_tab("https://example.com")
|
|
print(page_info())
|
|
PY
|
|
```
|
|
|
|
When the task is done and a cloud browser is still running, ask directly: "Should I close this browser now?" If yes, run `stop_remote_daemon(name)`. Remote daemons bill until they stop or time out.
|
|
|
|
Do not start a remote daemon and then keep using the default daemon. Use the same name for `BU_NAME`.
|
|
|
|
Cloud profiles for cookie sync live in `interaction-skills/profile-sync.md`.
|
|
|
|
## Page Workflow
|
|
|
|
- Screenshots first: use `capture_screenshot()` to understand visible state.
|
|
- Clicking: screenshot -> read pixel -> `click_at_xy(x, y)` -> screenshot again.
|
|
- After navigation, call `wait_for_load()`.
|
|
- If the current tab is stale or internal, call `ensure_real_tab()`.
|
|
- Use `js(...)` for DOM inspection or extraction when coordinates are the wrong tool.
|
|
- Login walls: stop and ask. Exception: use available SSO automatically when Chrome is already signed in; still stop for passwords, MFA, consent, or ambiguous account choice.
|
|
- Raw CDP is available with `cdp("Domain.method", ...)`.
|
|
|
|
## Interaction Skills
|
|
|
|
If you get stuck on a browser mechanic, check `interaction-skills/`:
|
|
|
|
- connection.md
|
|
- cookies.md
|
|
- cross-origin-iframes.md
|
|
- dialogs.md
|
|
- downloads.md
|
|
- drag-and-drop.md
|
|
- dropdowns.md
|
|
- iframes.md
|
|
- network-requests.md
|
|
- print-as-pdf.md
|
|
- profile-sync.md
|
|
- screenshots.md
|
|
- scrolling.md
|
|
- shadow-dom.md
|
|
- tabs.md
|
|
- uploads.md
|
|
- viewport.md
|
|
|
|
## Design Constraints
|
|
|
|
- Coordinate clicks default. CDP mouse events pass through iframes/shadow/cross-origin at the compositor level.
|
|
- Keep the connection model simple: use the default daemon, `BU_NAME`, `BU_CDP_URL`, `BU_CDP_WS`, or `start_remote_daemon(...)`.
|
|
- Core helpers stay short. Put task-specific helper additions in `$BH_AGENT_WORKSPACE/agent_helpers.py`.
|
|
|
|
## Gotchas
|
|
|
|
- `chrome://inspect/#remote-debugging` must be enabled for local Chrome control.
|
|
- Chrome may show an "Allow remote debugging?" popup; wait for the user to click Allow.
|
|
- Omnibox popups are not real work tabs.
|
|
- CDP target order is not Chrome's visible tab-strip order.
|
|
- `BU_CDP_URL` is an HTTP DevTools endpoint; the daemon resolves it to WebSocket.
|
|
- Ask before leaving cloud browsers running; stop them with `stop_remote_daemon(name)` or `PATCH /browsers/{id} {"action":"stop"}`.
|
|
|
|
## Domain Skills
|
|
|
|
Only applies when `BH_DOMAIN_SKILLS=1`. Otherwise ignore domain skills.
|
|
|
|
When enabled, search `$BH_AGENT_WORKSPACE/domain-skills/<host>/` before inventing an approach. `goto_url(...)` returns up to 10 skill filenames for the navigated host.
|