CDP Use

The library is structured around three main components that compose the client interface:

1. CDPClient: The entry point. It holds the WebSocket connection and provides two main interfaces: .send for commands and .register for events.
2. CDPLibrary: Accessed via client.send. It is a collection of domain-specific clients (e.g., DOMClient, NetworkClient, RuntimeClient). Each domain client provides methods to send CDP commands.
3. CDPRegistrationLibrary: Accessed via client.register. It provides domain-specific registration interfaces (e.g., PageRegistration, RuntimeRegistration) to attach event handlers.

This separation ensures that command execution and event subscription are logically organized by CDP domain.

Use CDPClient as an asynchronous context manager to connect to a Chrome DevTools WebSocket URL. You can send commands via the .send attribute, which provides access to various CDP domains (e.g., Target, Page).

Example of connecting and navigating:

import asyncio
from cdp_use.client import CDPClient

async def main():
    # Connect to Chrome DevTools
    async with CDPClient("ws://localhost:9222/devtools/browser/...") as cdp:
        # Get all browser targets
        targets = await cdp.send.Target.getTargets()
        print(f"Found {len(targets['targetInfos'])} targets")

        # Navigate to a page
        await cdp.send.Page.navigate({"url": "https://example.com"})

asyncio.run(main())

To use cdp-use, you must first clone the repository, install dependencies using uv or pip, and then run the generator to create the type-safe Python bindings from the official Chrome DevTools Protocol specifications.

1. Clone and install dependencies:

git clone https://github.com/browser-use/cdp-use
cd cdp-use
uv sync  # or pip install -r requirements.txt

2. Generate the CDP client library:

python -m cdp_use.generator

If you need to update the library to use a different version of the Chrome DevTools Protocol, you can regenerate the bindings.

To use the latest version from the master branch, run:

python -m cdp_use.generator

To pin a specific version, edit cdp_use/generator/constants.py and set the CDP_VERSION variable to a specific commit hash from the official devtools-protocol repository.

Example pinning:

# In cdp_use/generator/constants.py
CDP_VERSION = "4b0c3f2e8c5d6a7b9e1f2a3c4d5e6f7a8b9c0d1e"

The client.send attribute provides access to the CDPLibrary, which contains type-safe wrappers for Chrome DevTools Protocol commands. Instead of sending raw JSON, you use these methods to ensure parameters and return types are correctly handled.

While send_raw is available for arbitrary method calls, it is recommended to use the send library for full type safety and IDE autocompletion.

# Using the type-safe library (example pattern)
# Note: Actual method names depend on the CDPLibrary implementation
result = await client.send.Page.navigate({"url": "https://example.com"})

If you need to call a CDP method that is not yet covered by the type-safe CDPLibrary, use send_raw. This method sends a JSON-RPC request and waits for the response.

• method: The string name of the CDP method (e.g., Runtime.evaluate).
• params: A dictionary of arguments for the method.
• session_id: (Optional) The ID of the specific browser target session to use.

# Sending a raw command
result = await client.send_raw(
    method="Runtime.evaluate",
    params={"expression": "1 + 1"}
)

To react to asynchronous browser events (like Page.loadEventFired), use the client.register attribute, which provides access to the CDPRegistrationLibrary. This allows you to attach handlers to specific CDP methods that the browser emits.

Events are managed by an internal EventRegistry that routes incoming messages to your registered callbacks based on the method name.

# Example pattern for registering an event handler
@client.register.Page.loadEventFired
async def on_page_load(params):
    print(f"Page loaded: {params}")

The CDPClient class is the primary entrypoint for interacting with Chrome DevTools Protocol (CDP) via the cdp-use library. It provides high-level, type-safe methods for browser automation, including connecting to existing Chrome instances, navigating pages, and managing browser targets.

from cdp_use import CDPClient

# Example initialization (actual connection logic depends on CDPClient implementation)
client = CDPClient(...)

The CDPClient is the primary entry point for interacting with Chrome DevTools via the WebSocket protocol. It provides a type-safe interface for sending commands and handling browser events. You can manage the client lifecycle using an async context manager, which automatically handles connection startup and teardown.

Key Configuration Options

• url: The WebSocket endpoint (e.g., ws://localhost:9222/devtools/browser/...).
• additional_headers: An optional dictionary of HTTP headers to include in the WebSocket handshake.
• max_ws_frame_size: The maximum allowed size for a single WebSocket frame (defaults to 100MB).

from cdp_use.client import CDPClient

async def main():
    url = "ws://localhost:9222/devtools/browser/your-id"
    async with CDPClient(url=url) as client:
        # Your CDP logic here
        pass

import asyncio
asyncio.run(main())

The emit_event method allows you to manually trigger events through the client's internal EventRegistry. This is particularly useful for custom domains or application-level events that are not part of the standard Chrome DevTools Protocol but need to be processed by the same event-handling logic used by the browser.

# Manually trigger an event that registered handlers will catch
await client.emit_event("MyCustomDomain.event", {"data": "value"})