Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
docs: add CDP/Python reference for browser-use skill
ShawnPana04ca40c3af49
diff --git a/skills/browser-use/SKILL.md b/skills/browser-use/SKILL.mdindex c97042864..8bc5c7112 100644--- a/skills/browser-use/SKILL.md+++ b/skills/browser-use/SKILL.md@@ -110,6 +110,16 @@ browser-use close --all # Close all sessionsThe Python `browser` object provides: `browser.url`, `browser.title`, `browser.html`, `browser.goto(url)`, `browser.back()`, `browser.click(index)`, `browser.type(text)`, `browser.input(index, text)`, `browser.keys(keys)`, `browser.upload(index, path)`, `browser.screenshot(path)`, `browser.scroll(direction, amount)`, `browser.wait(seconds)`.+### Raw CDP / Python session++The CLI commands handle most browser interactions. Use `browser-use python` with raw CDP access when you need to:+- Control which tab the user sees in Chrome (activate/focus a tab)+- Manipulate page internals the CLI doesn't expose (network, DOM, device emulation)+- Work with Chrome target IDs instead of element indices+- Chain multiple async browser operations in one call++Read `references/cdp-python.md` for the `browser._run()` pattern and copy-pasteable CDP recipes.+## Cloud API```bashdiff --git a/skills/browser-use/references/cdp-python.md b/skills/browser-use/references/cdp-python.mdnew file mode 100644index 000000000..46522647f--- /dev/null+++ b/skills/browser-use/references/cdp-python.md@@ -0,0 +1,76 @@+# Raw CDP & Python Session Reference++The CLI commands handle most browser interactions. Use `browser-use python` with raw CDP when you need browser-level control the CLI doesn't expose — activating a tab so the user sees it, intercepting network requests, emulating devices, or working with Chrome target IDs directly.++## How the Python session works++`browser-use python "statement"` executes one Python statement per call. Variables persist across calls — set a value in one call, use it in the next.++A `browser` object is pre-injected with sync wrappers for common operations (`browser.goto()`, `browser.click()`, etc.). For anything beyond those, two internals give you full access:++- `browser._run(coroutine)` — run any async coroutine synchronously (60s timeout)+- `browser._session` — the raw `BrowserSession` with full CDP client access++## Getting a CDP client++```bash+browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"+```++After this, `cdp` persists across calls. Use `cdp.cdp_client.send.<Domain>.<method>()` for any CDP command and `cdp.session_id` for the session parameter.++## Recipes++### Activate a tab (make it visible to the user)++The CLI's `tab switch` only changes the agent's internal focus — Chrome's visible tab doesn't change. To actually show the user a specific tab:++```bash+# Get all targets to find the target ID+browser-use python "targets = browser._session.session_manager.get_all_page_targets()"+browser-use python "print([(i, t.url) for i, t in enumerate(targets)])"++# Activate target at index 1 so the user sees it+browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session(target_id=None, focus=False))"+browser-use python "browser._run(cdp.cdp_client.send.Target.activateTarget(params={'targetId': targets[1].target_id}))"+```++### List all tabs with target IDs++```bash+browser-use python "targets = browser._session.session_manager.get_all_page_targets()"+browser-use python "+for i, t in enumerate(targets):+ print(f'{i}: {t.target_id[:12]}... {t.url}')+"+```++### Run JavaScript and get the result++```bash+browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"+browser-use python "result = browser._run(cdp.cdp_client.send.Runtime.evaluate(params={'expression': 'document.title', 'returnByValue': True}, session_id=cdp.session_id))"+browser-use python "print(result['result']['value'])"+```++### Emulate a mobile device++```bash+browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"+browser-use python "browser._run(cdp.cdp_client.send.Emulation.setDeviceMetricsOverride(params={'width': 375, 'height': 812, 'deviceScaleFactor': 3, 'mobile': True}, session_id=cdp.session_id))"+```++### Get cookies via CDP++```bash+browser-use python "cdp = browser._run(browser._session.get_or_create_cdp_session())"+browser-use python "cookies = browser._run(cdp.cdp_client.send.Network.getCookies(params={}, session_id=cdp.session_id))"+browser-use python "print(cookies)"+```++## Tips++- Each `browser-use python` call is one statement. Multi-line strings work for `for` loops and `if` blocks, but you can't mix statements and expressions. Use multiple calls.+- Variables persist: set `cdp = ...` in one call, use `cdp` in the next.+- The `browser._run()` bridge has a 60-second timeout. For long operations, increase it or use the async internals directly.+- All CDP domains are available via `cdp.cdp_client.send.<Domain>.<method>()`. See the [Chrome DevTools Protocol docs](https://chromedevtools.github.io/devtools-protocol/) for the full API.