1. Why CDP Over Heavy Automation Frameworks
An agent that has to check a web app, fill a form or read a page needs a way to drive a real browser. The usual options, Selenium-style WebDriver stacks or cloud browser containers, add a driver binary, a version-matching problem between driver and browser, and often a large runtime on top.
The Chrome DevTools Protocol (CDP) is the interface Chrome already exposes to its own developer tools. It is a JSON message protocol over a WebSocket, so a client needs nothing more than a socket and a JSON parser. Proxima's agent uses it directly, which gives it:
- No driver to install: it talks to Google Chrome itself. Chrome must be installed; Proxima's diagnostics panel reports whether it was found.
- Browser-level input: clicks, key presses and text insertion are sent through CDP's
Inputdomain, which the page sees as real input events, so it works with React, Vue, Angular and plain HTML forms alike. - Events and responses on one connection: the same socket carries command replies and browser events such as console output.
2. Remote Debugging on Port 9222
Chrome only accepts CDP connections when it is started with a remote-debugging port. Proxima does not attach to the browser you use every day. It launches its own Chrome with a dedicated profile, so your bookmarks, logins and tabs are never touched:
chrome --remote-debugging-port=9222 \
--user-data-dir=~/.proxima-agent/chrome-profile \
--no-first-run --no-default-browser-check \
[--headless=new]
The port comes from PROXIMA_CDP_PORT (default 9222), and the profile folder
lives under ~/.proxima-agent/. The --headless=new flag is added only when
the agent is asked to run without a visible window. After launching, the agent waits up to about
fifteen seconds for the debugging endpoint to answer before giving up.
Chrome then serves a small HTTP discovery API on that port. The agent reads
http://127.0.0.1:9222/json/version to check that the browser is alive, and the tab list
to find a page target with a webSocketDebuggerUrl:
{
"Browser": "Chrome/<version>",
"Protocol-Version": "1.3",
"webSocketDebuggerUrl": "ws://127.0.0.1:9222/devtools/browser/<id>"
}
If a Proxima-owned Chrome is already running on the port, the agent reuses it. If something stale is there, the agent only terminates a process after confirming that its command line contains Proxima's own profile folder and debugging flag. It never kills a Chrome it cannot positively identify as its own. Checks that only verify a result open the connection in a connect-only mode that refuses to launch a browser, because a check that starts Chrome would itself be a side effect.
3. Core CDP Domains: Page, Input, DOM and Runtime
CDP groups its commands into domains. These are the ones the driver relies on:
| CDP Domain | Methods used | Purpose |
|---|---|---|
Page |
Page.navigate, Page.captureScreenshot |
Navigation and screenshots. A screenshot is saved to disk and queued so the model sees it on its next message. |
Input |
Input.insertText, mouse and key events |
Typing, clicking, scrolling and key presses at the browser-engine level. |
Runtime |
Runtime.evaluate |
Runs JavaScript in the page. Most element lookup and text extraction is done this way. |
DOM / targets |
tab list via the HTTP /json endpoints |
Opening a tab (/json/new), switching and closing tabs. |
4. Proxima's Python Browser Driver
The driver is one Python module, proxima_agent/tools/browser_cdp.py, of about two
thousand lines. It has no third-party dependencies for the protocol: a small built-in WebSocket client
(_WS) speaks to Chrome over a plain socket, and a ChromeBrowser class sits on
top of it. Every command carries an incrementing id, and the driver reads messages until it finds the
reply with that id. Messages that arrive in between, such as console events, are kept in a bounded
queue of 1,000 entries instead of being thrown away.
from proxima_agent.tools.browser_cdp import ChromeBrowser
b = ChromeBrowser() # launches or reuses the dedicated Chrome
b.goto("https://example.com/login")
b.write_text("Email", "me@example.com") # finds the field by label, placeholder or aria-label
b.write_text("Password", "...")
b.click_text("Sign in") # finds a clickable element by its visible text
b.wait_for("Dashboard", timeout=10) # raises if it does not appear in time
print(b.read_content()) # main page content as Markdown
b.screenshot("after-login.png")
The main calls are goto, click and click_text,
write_text and type_text, press and hotkey,
scroll, wait_for, read_text, read_content,
extract_records, run_js, screenshot, and tab control
(new_tab, tabs, close_tab).
write_text inserts text with CDP's Input.insertText and, by default, reads
the field back to confirm the value was set. goto is intentionally simple: it navigates and
then pauses briefly before returning the page title, so a script that needs a specific element should
follow it with wait_for.
5. Finding Elements: Semantics Before Selectors
Modern pages can contain thousands of nested elements, which wastes an LLM's context and makes CSS
selectors brittle. The driver therefore works from what a person would see and what the page
declares about itself. click_text and write_text go through one element
finder that tries several strategies in turn: visible text, placeholder, label, ARIA label, CSS
selector and XPath, including inside Shadow DOM and iframes, and it scrolls the match into view.
For a model that needs to look first, dump_interactive_elements() returns the visible,
interactive elements (inputs, buttons, links and elements with ARIA roles or click handlers) as JSON,
with their coordinates, roles, labels and selectors. For reading, two helpers keep the output small:
read_content()returns the main content as clean Markdown, dropping navigation, ads, cookie banners and footers with a readability-style heuristic that is not tied to any site.extract_records()detects the dominant repeated structure on a page (a table, a card grid, a result list) and returns it as a list of dictionaries with fields such as title, text, URL and image.
6. Timing in Single Page Apps
In a single page app the URL can change, or the content can update, without a page load, so "navigate and click immediately" often fails silently. Proxima handles this with explicit waiting rather than a hidden global gate:
- Waiting for elements:
click_textandwrite_textpoll for their target for up to five seconds by default (timeoutis a parameter), andwait_for(query, timeout)polls for up to ten seconds, raising an error that names the query if nothing appears. - Verifying the effect:
write_textchecks, by default, that the field really holds the value it just wrote, and that the element with focus is the one it targeted. A write that landed in the wrong place is reported as an error instead of being ignored. For clicks, follow up withwait_foron something that should appear, or take a screenshot. - Retry on transient failures: when a browser step fails with a known transient class such as a lost connection, the agent's retry policy invalidates its cached browser health and reconnects before the next attempt (see the Agent Guide).
A script that depends on a particular state should say so with wait_for. It is cheaper
than guessing a sleep time and it fails with a message that is useful to the model.
7. Diagnostic Failure Analysis
| Symptom | Likely cause | How to check | Fix |
|---|---|---|---|
| "Chrome started but CDP not responding on port 9222" | Chrome did not open its debugging port in time, often because the port is taken or another instance holds the profile. | Run netstat -ano | findstr 9222 (Windows) or lsof -i :9222 (macOS, Linux). |
Close the process using the port, or set PROXIMA_CDP_PORT to a free port and restart the agent. |
| Browser launch fails with "Chrome not found" | Google Chrome is not installed in a standard location. | Check the Diagnostics panel in the Proxima app. | Install Google Chrome. The agent looks in the usual install folders for your operating system. |
wait_for(...) or click_text(...) raises "element not found" |
The text differs from what you typed, the element is not rendered yet, or it is hidden. | Call screenshot() and dump_interactive_elements() to see what the page actually contains. |
Use the exact visible label, increase timeout, or target a CSS selector. |
| The connection drops mid-task | The tab or window was closed by hand. | Look for a connection error in the agent output. | Do not close the agent's Chrome window while a task runs. The retry policy reconnects on the next attempt. |
8. Architectural Takeaways
Driving Chrome directly over CDP keeps the dependency list short and gives the agent browser-level input and access to the page's own accessibility and ARIA metadata. The design choices that matter in practice are the dedicated profile (so the agent never touches your own browsing), conservative process ownership checks before killing anything, element lookup by meaning instead of brittle selectors, and explicit waits with verification instead of fixed delays.