How to evaluate a browser API for AI agents.

Browser infrastructure looks simple from application code. An agent requests a browser. It performs browser work. Then the application releases resources.

That sequence hides two independent contracts. The lifecycle contract provisions and terminates compute. The browser contract carries automation commands. These contracts often use different protocols.

REST commonly controls lifecycle resources. WebSockets commonly carry browser commands. CDP is one browser-control protocol. Playwright also defines its own protocol.

A returned URL proves only documented access. It does not prove automation compatibility. The URL scheme and semantics matter. Authentication requirements also matter.

Legba labels its API documentation a proposed public preview. No concrete public host or key-issuer URL is published. No concrete public callable endpoint is published.

The preview models REST instance creation, listing, and termination. Those shapes are illustrative, not a live integration contract.

Illustrative responses include an access_url. The preview does not define an automation protocol. That omission remains a real boundary.

Current docs never promise Playwright compatibility. They never publish a Playwright WebSocket. They never publish a CDP endpoint. They never publish a Puppeteer WebSocket.

Most browser failures occur between obvious steps. Creation can succeed before readiness. Connection can succeed before navigation. Work can finish before cleanup.

A reliable contract defines every transition. Each transition needs success evidence. Each transition also needs failure evidence. Ownership must remain unambiguous.

The matrix separates lifecycle stages. It avoids vendor-specific endpoint assumptions. Apply it to every shortlisted provider. Record unknowns instead of guessing.

A polished demonstration proves one happy path. Production requires a stable written contract. That contract spans more than browser commands. It includes ownership, limits, and cleanup.

The matrix turns vague platform claims into questions. Every answer needs published evidence. A sales answer can guide testing. It should not replace documentation.

Use the matrix before implementation starts. Missing mandatory answers should block migration. Optional unknowns can remain tracked. Their uncertainty should remain priced.

A browser API may expose several interfaces. REST can manage infrastructure resources. Playwright protocol carries Playwright commands. CDP carries Chromium debugging commands.

Puppeteer commonly connects through a browser WebSocket. Its ConnectOptions define supported connection inputs. A browserWSEndpoint identifies the existing browser. Browser ownership remains a separate concern.

Playwright's native connection has version constraints. Client and server major versions must match. Minor versions must match too. Patch versions can differ safely.

Playwright CDP connections are Chromium-only. Official docs call them lower fidelity. Advanced Playwright features may work differently. Native Playwright protocol remains the preferred path.

Browser state includes cookies and local storage. It may also include authentication headers. Reusing that state can reduce repeated logins. It also expands credential exposure.

Playwright contexts isolate independent browser sessions. Closing a context closes its pages. Puppeteer contexts also isolate cookies and storage. Their exact APIs still differ.

Provider-side state adds another layer. A provider may persist profiles across instances. It may scope them to organizations. Those behaviors need explicit documentation.

Legba proposes REST API-key authentication. No public key-issuer URL is documented. The browser-channel authentication contract remains undocumented. Never infer it from the preview.

Agents encounter partial failures constantly. Infrastructure can exist before browser readiness. Browser commands can timeout during active instances. Client processes can stop before cleanup.

A strong API distinguishes these failures. It exposes structured error codes. It records the affected resource identifier. It makes retry safety understandable.

Legba proposes structured REST errors and common HTTP statuses. These illustrate lifecycle recovery. Browser-protocol failures remain outside current documentation.

Observation must survive the failing client. Ask where logs and artifacts live. Ask when they become available. Ask how long they remain accessible.

Start with one representative agent task. Include normal authentication and state. Include normal artifacts and failure paths. Avoid a polished toy demonstration.

Write acceptance criteria before connecting anything. Name the required browser protocol. Name the required lifecycle operations. Name the required cleanup evidence.

Legba's preview docs support contract review today. They do not support a public self-serve integration. They do not support Playwright or Puppeteer compatibility claims. Wait for a concrete host and published protocol.

Review canonical documentation before implementation. Preview contracts can change. Keep version and host assumptions configurable internally. Do not publish guessed endpoints.