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 Input domain, 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:

What the agent runs (simplified)
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:

JSON // GET http://127.0.0.1:9222/json/version (abridged)
{
  "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 DomainMethods usedPurpose
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.

Python // what an agent script looks like
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_text and write_text poll for their target for up to five seconds by default (timeout is a parameter), and wait_for(query, timeout) polls for up to ten seconds, raising an error that names the query if nothing appears.
  • Verifying the effect: write_text checks, 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 with wait_for on 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

SymptomLikely causeHow to checkFix
"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.