Tools

Reference for the six browser tools agents call.

Every tool returns the same envelope: { ok: true, ...payload } on success, or { ok: false, error } for model-fixable failures (unknown session ID, thrown Playwright code). Errors include a next step when possible. Host misconfiguration (missing API keys) and domain policy violations throw instead of returning { ok: false }.

browser_open

Open a new browser session through the configured provider. Optionally navigates to url after opening. Returns a sessionId for later tools.

path urlstring

Optional URL to open after the session starts. Use a full https:// URL, or omit url and navigate with browser_exec via await page.goto(...).

Success: { ok: true, sessionId }.

If navigation fails, the session is closed and the tool returns { ok: false, error } so the agent can open again.

browser_connect

Attach to an already-running browser via its CDP websocket URL. Returns a session ID like browser_open, but browser_close detaches without killing the externally managed browser.

path cdpUrlstringrequired

CDP websocket URL, for example ws://127.0.0.1:9222/devtools/browser/....

Success: { ok: true, sessionId }.

Use this for Electron apps or any Chromium already started with remote debugging. See CDP attach.

browser_exec

Run Playwright code against an open session. The code runs as the body of a fresh async function — use return to produce a result.

Nothing persists between calls (no variables, no imports). The browser is the only state. In scope: page, context, browser. TypeScript is fine (stripped with Sucrase). console.log / console.error are captured as stdout / stderr.

Results are JSON-serialized when possible; values that cannot be serialized become strings.

path sessionIdstringrequired

Session ID from browser_open or browser_connect.

path codestringrequired

Playwright/TypeScript body to run. Example: return await page.title().

path pageIdstring

Optional page ID from browser_status. Defaults to the most recently opened tab.

Success:

1234567{
  ok: true,
  result: unknown,
  stdout: string,
  stderr: string,
  snapshotDiff: string, // a11y-tree diff since the previous exec; empty when unchanged
}

Code-level failures return { ok: false, error, stdout?, stderr? } — fix the code and retry.

Snapshot vs snapshotDiff

Call browser_snapshot to orient on a full accessibility tree before interacting, or to verify state after a change.
Successful browser_exec calls already return snapshotDiff for what changed since the previous exec on that session. Prefer reading that before taking another full snapshot.

browser_snapshot

Capture the current page as a compact text accessibility tree. Nodes include ref handles (for example l7) so the agent can refer to structure while writing Playwright locators in browser_exec.

path sessionIdstringrequired

Session ID from browser_open or browser_connect.

path screenshotboolean

When true, also return a PNG as { base64, mimeType: "image/png" }. Framework adapters (AI SDK, Pi) can surface that image to the model.

path pageIdstring

Optional page ID from browser_status. Defaults to the most recently opened tab.

Success: { ok: true, tree, screenshot? }.

browser_status

Inspect open sessions and pages. Start here when the agent is unsure which tab to target.

Args	Returns
(none)	`{ ok: true, sessions }` — each session lists `sessionId`, `provider`, and `pages`
`sessionId`	`{ ok: true, pages }` for that session
`sessionId` + `pageId`	Page detail: `url`, `title`, `viewport`, `active`, `readyState`

path sessionIdstring

Session ID from browser_open or browser_connect.

path pageIdstring

Page ID from a prior browser_status call. Requires sessionId.

browser_close

Close a session by ID. For provider-owned sessions this releases the remote browser. For browser_connect sessions it detaches without killing the external browser.

path sessionIdstringrequired

Session ID to close.

Success: { ok: true }.

Calling dispose() on the toolkit closes every session that toolkit still owns.

Ask AI about this page