> ## Documentation Index
> Fetch the complete documentation index at: https://piyushvyas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Protocol Overview

> BAP uses JSON-RPC 2.0 over WebSocket to give AI agents structured browser control.

BAP (Browser Agent Protocol) is an open standard for AI agents to interact with web browsers. It defines 55 methods across 13 categories, all transported as JSON-RPC 2.0 messages over WebSocket.

## Design Principles

<CardGroup cols={2}>
  <Card title="JSON-RPC 2.0" icon="brackets-curly">
    Every request and response follows the JSON-RPC 2.0 specification. Clients send `{ jsonrpc: "2.0", method, params, id }` and receive `{ jsonrpc: "2.0", result, id }` or `{ jsonrpc: "2.0", error, id }`.
  </Card>

  <Card title="WebSocket Transport" icon="plug">
    Persistent bidirectional connection. The server can push notifications (console errors, network failures, dialog events) without polling.
  </Card>

  <Card title="Semantic Selectors" icon="crosshairs">
    10 selector types (role, text, label, testId, ref, css, xpath, placeholder, semantic, coordinates) let agents target elements by meaning, not DOM structure.
  </Card>

  <Card title="Fusion Operations" icon="bolt">
    6 optimizations that batch multiple operations into single requests, cutting roundtrips by up to 55% in complex workflows.
  </Card>
</CardGroup>

## Architecture

BAP uses a two-process architecture that separates the protocol layer from the browser automation engine:

```
MCP Client / Shell Agent
    |
    | JSON-RPC 2.0 over WebSocket
    v
BAP Server (Playwright engine)
    |
    | CDP / Playwright
    v
Browser (Chromium / Firefox / WebKit)
```

This separation enables:

* **Session persistence** -- the browser survives client restarts
* **Multi-client access** -- CLI and MCP can control the same browser simultaneously
* **Shared state** -- observations, element refs, and cookies persist across interfaces

## Connection Lifecycle

<Steps>
  <Step title="Open WebSocket">Client connects to `ws://localhost:9222` (default endpoint).</Step>

  <Step title="Initialize">
    Client sends `initialize` with client capabilities and optional `sessionId`. Server responds
    with server capabilities and protocol version.
  </Step>

  <Step title="Confirm Ready">
    Client sends `notifications/initialized` notification (no response expected).
  </Step>

  <Step title="Operate">
    Client sends method requests (`browser/launch`, `page/navigate`, `agent/act`, etc.). Server
    responds to each request and may push notifications for events.
  </Step>

  <Step title="Shutdown">
    Client sends `shutdown` or simply disconnects. If the client provided a `sessionId`, the server
    parks the browser state for later reconnection.
  </Step>
</Steps>

## Session Persistence

Clients can include a `sessionId` in the `initialize` request. When a client with a session ID disconnects, the server parks the browser state (pages, contexts, cookies) in a dormant store instead of destroying it.

Reconnecting with the same `sessionId` restores the full session. Dormant sessions expire after `dormantSessionTtl` (default: 300 seconds).

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "sessionId": "my-agent-session",
    "clientInfo": { "name": "my-agent", "version": "1.0.0" }
  },
  "id": 1
}
```

## Protocol Versioning

BAP follows semantic versioning:

| Level             | What changes                                               |
| ----------------- | ---------------------------------------------------------- |
| **Patch** (0.8.x) | Bug fixes, performance improvements                        |
| **Minor** (0.x.0) | New optional fields, new methods, new selector types       |
| **Major** (x.0.0) | Breaking changes to existing method signatures or behavior |

All fields added in minor versions are optional. Old clients and servers ignore unknown fields -- zero breaking changes for additive updates.

## Method Categories

BAP defines 55 methods organized into 13 categories:

| Category            | Methods | Purpose                                                                   |
| ------------------- | :-----: | ------------------------------------------------------------------------- |
| Lifecycle           |    3    | Initialize, confirm ready, shutdown                                       |
| Browser             |    2    | Launch and close browser                                                  |
| Page                |    8    | Create, navigate, reload, back/forward, close, list, activate             |
| Actions             |    13   | Click, fill, type, press, hover, scroll, select, check, upload, drag      |
| Observations        |    7    | Screenshot, accessibility tree, DOM, element, PDF, content, ARIA snapshot |
| Storage             |    5    | Get/set cookies and localStorage                                          |
| Emulation           |    4    | Viewport, user agent, geolocation, offline mode                           |
| Dialog/Trace/Events |    4    | Handle dialogs, start/stop traces, subscribe to events                    |
| Context             |    3    | Create, list, destroy browser contexts                                    |
| Frame               |    3    | List, switch, return to main frame                                        |
| Stream/Approval     |    2    | Cancel streams, respond to approval requests                              |
| Discovery           |    1    | Discover WebMCP tools on page                                             |
| Agent               |    3    | Composite act, observe, extract                                           |

See [Methods](/protocol/methods) for the full reference.