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 public preview. The endpoint reference is still firming up. The organization-specific host is also finalizing. Production assumptions should reflect that status.

Current documentation covers REST instance lifecycle. Teams can create isolated browser instances. They can list running instances. They can destroy completed instances.

Documented instance responses include an access_url. The docs describe browser access through that field. They do not define its 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 currently documents REST API-key authentication. Keys belong outside client-side code. The browser-channel authentication contract remains undocumented. Never infer it from REST authentication.

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 documents REST error response structure. It also documents common HTTP statuses. That helps 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 lifecycle evaluation today. They do not support Playwright compatibility claims. They do not support Puppeteer compatibility claims. Wait for published protocol details.

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