Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

docs: add CDP/Python reference for browser-use skill

ShawnPana04ca40c3af49
diff --git a/skills/browser-use/SKILL.md b/skills/browser-use/SKILL.md
index 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 sessions
The 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
```bash
diff --git a/skills/browser-use/references/cdp-python.md b/skills/browser-use/references/cdp-python.md
new file mode 100644
index 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.