Interact with the page: click (left/right/middle, single or double), hover, type, press, or scroll. Address elements with a [ref=eN] handle from browser::snapshot (or a pick), or raw viewport coordinates.
actionstring*required
`click`, `hover`, `type`, `press`, or `scroll`.
buttonstring
Mouse button for `click`: `left` (default), `right`, or `middle`.
click_countinteger· uint32min 0
Clicks in the gesture: 2 double-clicks (`click` only, default 1).
delta_ynumber· double
Scroll distance in pixels; positive scrolls down (`scroll`).
keystring
Key name for `press`: Enter, Tab, Escape, Backspace, Delete, ArrowUp/Down/Left/Right, Home, End, PageUp, PageDown.
refstring
Element ref from `browser::snapshot` (`e3`) or `browser::picked` (`p1`). Refs die on navigation; re-snapshot after.
session_idstring*required
textstring
Text to insert (`type`).
xnumber· double
Viewport x, when acting by coordinates instead of ref.
ynumber· double
Viewport y, when acting by coordinates instead of ref.
detailstring*required
What was done, for the transcript.
browser::console::read
functionRead the session's captured console: console.* calls, uncaught exceptions, and browser-level log entries. Filter with pattern/level and page with since_seq instead of dumping everything.
levelstring
Only entries at this level: `log`, `info`, `warning`, `error`, `debug`, `exception`. `error` also matches `exception`.
limitinteger· uint64min 0
Maximum entries returned, newest kept (default 100).
patternstring
Regex applied to entry text. Use it: dumping an unfiltered console wastes the caller's context.
session_idstring*required
since_seqinteger· uint64min 0
Only entries with `seq` greater than this; resume from the cursor returned as `last_seq`.
droppedinteger· uint64*requiredmin 0
Entries evicted from the ring buffer since session start.
entriesobject[]*required
levelstring*required
`log`, `info`, `warning`, `error`, `debug`, or `exception`.
seqinteger· uint64*requiredmin 0
Monotonic per-session cursor; pass back as `since_seq`.
sourcestring
`url:line` of the emitting frame, when known.
timestampinteger· int64*required
last_seqinteger· uint64*requiredmin 0
Cursor for the next `since_seq`.
BFS-crawl from start_urls (follow same-domain links), extract per page, stream items.
allowed_domainsstring[]
only follow links on these hosts
css_selectorstring
scope the render to this CSS subtree (e.g. a page's content div)
download_delaynumber
seconds to wait between crawl rounds
fetcherstringenum: http, stealthy, dynamic
formatstringenum: markdown, text
render page body to this format
main_content_onlyboolean
strip nav/scripts/hidden before rendering
same_domainboolean
follow only same-host links (default true)
selectorsobject[]
allboolean
return every match as a list
attrstring
extract this attribute instead of text
htmlboolean
extract inner HTML instead of text
stream_namestring
stream to emit items on (default browser::crawl)
urlstring
single start URL (alternative to start_urls)
itemsobject[]
a small sample of streamed items
streamobject
read the full item stream via stream::on with this name + group_id
One CSS query over HTML; first-or-all; `attr` pulls an attribute else text.
adaptiveboolean
relocate elements after a site change via saved identities
adaptive_domainstring
page URL/domain that keys saved identities
auto_saveboolean
save matched identities (defaults on when adaptive)
identifierstring
stable key for the saved element
browser::describe
functionDescribe the first css/xpath match: attrs, generated selectors, class list, DOM context.
kindstringenum: css, xpath
Read-only environment diagnostics: which Chromium the worker would launch, its version, session capacity, and any degraded capability with how to enable it. Never starts a browser.
active_sessionsinteger· uint64*requiredmin 0
allowed_schemesstring[]*required
attach_enabledboolean*required
Whether attach mode is enabled (allow_attach).
headless_defaultboolean*required
issuesobject[]*required
enable_howstring*required
max_sessionsinteger· uint64*requiredmin 0
okboolean*required
True when sessions can start right now.
recording_availableboolean*required
Whether ffmpeg is on PATH, which browser::recording requires.
browser::dom::read
functionRead the DOM as a tree of tags with id/class and refs. Structure-oriented complement to browser::snapshot; read deep subtrees by passing a ref.
depthinteger· uint32min 0
Levels of children to include (default 3).
refstring
Subtree root from an earlier ref (`e3`/`p1`) or dom node. Omit for the document root.
session_idstring*required
rootobject*required
One DOM node in the outline. `ref` resolves in `browser::act`, `browser::styles::read`, and `browser::styles::write`.
child_countinteger· uint32*requiredmin 0
Total children in the document, which may exceed `children` returned at this depth.
tagstring*required
Lowercase tag (`div`, `button`) or node name (`#text`).
textstring
Trimmed text content for text nodes.
truncatedboolean*required
True when the node cap cut the tree short; read a subtree via `ref`.
browser::dynamic-fetch
functionPlaywright/Chromium fetch: JS render, waits, XHR capture, CDP; extraction + bulk.
css_selectorstring
scope the render to this CSS subtree (e.g. a page's content div)
formatstringenum: markdown, text
render page body to this format
main_content_onlyboolean
strip nav/scripts/hidden before rendering
selectorsobject[]
allboolean
return every match as a list
attrstring
extract this attribute instead of text
htmlboolean
extract inner HTML instead of text
timeoutnumber
milliseconds (browser fetcher)
waitnumber
extra ms to wait after load
wait_selector_statestringenum: attached, detached, visible, hidden
contentstring
markdown/text render when `format` requested
browser::evaluate
functionEvaluate a JavaScript expression in the page and return its completion value. Use for reads the snapshot can't express; prefer browser::act for interactions.
expressionstring*required
JavaScript expression evaluated in the page. The completion value is returned by value; wrap statements in an IIFE.
session_idstring*required
timeout_msinteger· uint64min 0
Upper bound on evaluation; clamped to `max_timeout_ms`.
errorstring
Exception text when not `ok`.
valueunknown
JSON completion value when `ok`.
Run a multi-step async JavaScript script in the page: top-level await and return work, with log(...), sleep(ms), waitFor(selector), and a state object that persists across execute calls for the session. One call replaces a chain of act/evaluate round-trips; returns { result, logs, state }.
codestring*required
Async JavaScript body run in the page. Top-level `await` and `return` work. In scope: `state` (JSON object persisted across execute calls for the session), `log(...)` (collected into the response), `sleep(ms)`, and `waitFor(selector, { timeout })`. Return plain JSON.
session_idstring*required
timeout_msinteger· uint64min 0
Upper bound on the run; clamped to `max_timeout_ms`.
errorstring
Exception text when not `ok`. A "context destroyed" error usually means the script navigated; split the script at the navigation.
logsstring[]*required
`log(...)` output collected during the run, in order.
resultunknown
The script's return value when `ok`.
stateunknown*required
Session state after the run; the next execute call sees this as `state`.
Fast HTTP fetch, TLS impersonation: get/post/put/delete, inline extraction, bulk `urls`.
css_selectorstring
scope the render to this CSS subtree (e.g. a page's content div)
formatstringenum: markdown, text
render page body to this format
impersonatestring
TLS/UA fingerprint, e.g. 'chrome'
main_content_onlyboolean
strip nav/scripts/hidden before rendering
methodstringenum: get, post, put, delete
proxiesobject
per-scheme proxies, e.g. {"https": "http://..."}
proxy_authstring[]
[user, password]
selectorsobject[]
allboolean
return every match as a list
attrstring
extract this attribute instead of text
htmlboolean
extract inner HTML instead of text
timeoutnumber
seconds (HTTP fetcher)
contentstring
markdown/text render when `format` requested
Find elements by tag/attribute filters (+ optional text regex); BeautifulSoup-style.
attrsobject
attribute filters, e.g. {"class": "card"}
tagstring
tag name or list of tag names
text_regexstring
keep only elements whose text matches this regex
browser::find-by-regex
functionFind elements whose visible text matches a regex pattern.
browser::find-by-text
functionFind elements whose visible text matches a string (exact or `partial`).
clean_matchboolean
ignore surrounding/collapsing whitespace
partialboolean
match elements that contain the text
browser::find-similar
functionStructural auto-match: given one example element, return it plus similar elements.
anchorstring*required
CSS selector to one example element
selectorsobject[]
allboolean
return every match as a list
attrstring
extract this attribute instead of text
htmlboolean
extract inner HTML instead of text
similarity_thresholdnumber
Internal: newest screencast frame, or nothing when since_frame is still current. No capture round-trip; poll fast. Not an agent function.
session_idstring*required
since_frameinteger· uint64min 0
Frame cursor from the previous read; when the newest frame still has this seq the response omits `frame` (nothing changed, nothing to redraw).
activeboolean*required
False when no screencast is running (call screencast::start first).
framestring
Base64 JPEG of the newest frame; absent when `since_frame` is still current or no frame has arrived yet.
frame_seqinteger· uint64*requiredmin 0
heightinteger· uint32*requiredmin 0
Page-viewport height the frame maps to.
timestampinteger· int64*required
widthinteger· uint32*requiredmin 0
Page-viewport width the frame maps to (input coordinate space).
Pause a session for a step only a human can do (CAPTCHA, 2FA, payment): show an in-page continue banner and block until the human clicks it, a browser::handoff::confirm call resolves it, or the timeout elapses. Human acknowledgment is not proof — verify the expected page state after it returns.
instructionsstring*required
What the human must do before the call continues. Shown in the in-page banner and the handoff-requested event.
session_idstring*required
timeout_msinteger· uint64min 0
Give up after this long and return with `via: "timeout"`. Defaults to the config default; clamped to `max_timeout_ms`. Set generously; a human is slow.
confirmedboolean*required
True when a human confirmed; false when the wait timed out.
handoff_idstring*required
urlstring*required
The page URL when the wait ended, so the caller can verify the step actually landed (human acknowledgment is not proof).
viastring*required
How the confirmation arrived: `in_page`, `confirm_call`, or `timeout`.
Resolve a paused browser::handoff by handoff_id, or the one pending handoff for a session_id. The console calls this when the human confirms outside the page.
handoff_idstring
Confirm a specific handoff by id. Omit to confirm the one pending handoff for `session_id`.
okboolean*required
True when a pending handoff matched and was resolved.
Go back, go forward, or reload the session's page. Back/forward at the history edge is a no-op with moved=false.
actionstring*required
`back`, `forward`, or `reload`.
session_idstring*required
movedboolean*required
False when back/forward had no entry to move to.
urlstring*required
URL after the action. `back`/`forward` at the history edge is a no-op with ok=true.
browser::inject-guidance
functionInternal: appends browser::* scraping and HTML parsing guidance to the agent system prompt.
browser::navigate
functionNavigate a session to a URL and wait for the page to load. Element refs from earlier snapshots are invalidated by navigation.
session_idstring*required
timeout_msinteger· uint64min 0
Upper bound on the navigation wait; clamped to `max_timeout_ms`.
urlstring*required
Absolute URL; scheme must be on the configured allowlist.
timed_outboolean*required
True when the load event did not fire inside the timeout; the page may still be usable; snapshot to check.
urlstring*required
URL after redirects.
browser::network::read
functionRead the session's captured network requests (method, URL, status, failures). failed_only=true is the fast path for 'what broke'.
failed_onlyboolean
Only failed requests (network error or status >= 400).
limitinteger· uint64min 0
Maximum entries returned, newest kept (default 100).
patternstring
Regex applied to the request URL.
session_idstring*required
since_seqinteger· uint64min 0
Only entries with `seq` greater than this.
droppedinteger· uint64*requiredmin 0
Entries evicted from the ring buffer since session start.
entriesobject[]*required
seqinteger· uint64*requiredmin 0
Monotonic per-session cursor; pass back as `since_seq`.
timestampinteger· int64*required
last_seqinteger· uint64*requiredmin 0
Cursor for the next `since_seq`.
Internal: reload browser settings from the authoritative configuration on change.
browser::pick::hint
functionInternal: element preview at a viewport point (tag, id, classes, bounds) so the console UI can draw a hover highlight in pick mode. Not an agent function.
session_idstring*required
xnumber· double*required
Viewport x of the cursor.
ynumber· double*required
Viewport y of the cursor.
boundsany of
Viewport-space box to draw the highlight over.
any of (2)
variant 1
heightnumber· double*required
widthnumber· double*required
hitboolean*required
False when no element sits at the point.
tagstring
Lowercase tag name.
browser::pick::resolve
functionInternal: resolve the element at a clicked viewport point and emit browser::picked. The console calls this on a pick-mode click. Not an agent function.
session_idstring*required
xnumber· double*required
Viewport x of the click.
ynumber· double*required
Viewport y of the click.
browser::pick::start
functionInternal: enter pick mode so the human can select an element in the console UI. Not an agent function.
session_idstring*required
browser::pick::stop
functionInternal: leave DevTools inspect mode without picking. Idempotent. Not an agent function.
session_idstring*required
Cancelling pick mode on an unknown session succeeds.
Record a session's live viewport to a video file (webm or mp4) by piping the screencast through ffmpeg. Turns screencast on if needed. Requires ffmpeg on PATH; browser::doctor reports whether it is available.
formatstring
`webm` (VP9) or `mp4` (H.264). Defaults to webm.
pathstring*required
Output file path. The extension should match `format`.
session_idstring*required
browser::recording::stop
functionStop a session's recording, finalize the file, and return its path, duration, and frame count. Idempotent: stopping when nothing is recording returns ok=false.
session_idstring*required
duration_msinteger· int64*required
Wall-clock duration captured, milliseconds.
framesinteger· uint64*requiredmin 0
Frames written to the encoder.
okboolean*required
False when no recording was running.
Run a regex over the visible text of provided HTML; `first` returns the first match, else all.
Internal: start pushing live viewport frames for browser::frame. Console-UI plumbing; agents use browser::screenshot. Not an agent function.
session_idstring*required
Internal: stop the live frame push. Idempotent. Not an agent function.
session_idstring*required
Stopping the screencast on an unknown session succeeds.
browser::screenshot
functionCapture the session viewport as a viewable JPEG. Use browser::snapshot for machine-readable structure; screenshot when layout or rendering matters.
full_pageboolean
Capture the full scrollable page instead of the viewport.
session_idstring*required
detailsobject*required
heightinteger· uint32*requiredmin 0
session_idstring*required
widthinteger· uint32*requiredmin 0
browser::screenshot-url
functionCapture a page screenshot as image content blocks via a browser fetcher (dynamic or stealthy).
fetcherstringenum: dynamic, stealthy
formatstringenum: png, jpeg
contentobject[]
image blocks (one per tile, width<=1024/height<=1536) + a text caption
datastring
base64 image bytes (image blocks)
typestring*requiredenum: image, text
browser::session-close
functionClose a session and free its browser/connection.
session_idstring*required
browser::session-fetch
functionFetch a URL on an open session (reuses its cookies/browser); same page/extraction output.
css_selectorstring
scope the render to this CSS subtree (e.g. a page's content div)
formatstringenum: markdown, text
render page body to this format
main_content_onlyboolean
strip nav/scripts/hidden before rendering
methodstringenum: get, post, put, delete
selectorsobject[]
allboolean
return every match as a list
attrstring
extract this attribute instead of text
htmlboolean
extract inner HTML instead of text
session_idstring*required
contentstring
markdown/text render when `format` requested
browser::session-list
functionList open sessions with their type and idle time.
typestringenum: http, dynamic, stealthy
filter by type
browser::session-open
functionOpen a persistent HTTP/browser session; returns a session_id that reuses cookies + state.
capture_xhrstring
regex; capture matching XHRs (browser sessions)
typestringenum: http, dynamic, stealthy
session engine
Attach a session to an already-running browser over CDP (start Chrome with --remote-debugging-port). Opens a fresh tab the session owns, or adopts an existing user tab by URL substring and releases it untouched on stop. Reaches the real profile with its logins; disabled unless allow_attach is set in config.
adopt_url_substringstring
Adopt the existing tab whose URL contains this substring, exclusively, and release it untouched on stop. Omit to open a fresh tab the session owns and closes on stop. Must match exactly one open tab.
cdp_urlstring*required
CDP endpoint of the running browser: `http://127.0.0.1:9222` (the worker resolves the WebSocket URL from `/json/version`) or a `ws://` debugger URL directly. Start Chrome with `--remote-debugging-port=9222` to expose one.
read_onlyboolean
Inspection-only session; see browser::sessions::start.
urlstring
URL to open in the fresh tab (ignored when adopting). Omit for about:blank.
adoptedboolean*required
True when the session adopted an existing user tab (released, not closed, on stop); false when it opened a fresh tab it owns.
read_onlyboolean*required
session_idstring*required
browser::sessions::list
functionList live browser sessions with their current URL and activity.
sessionsobject[]*required
console_entriesinteger· uint64*requiredmin 0
created_msinteger· int64*required
last_used_msinteger· int64*required
read_onlyboolean*required
session_idstring*required
browser::sessions::start
functionStart an interactive Chromium session and return its session_id. Sessions keep console and network history; stop them with browser::sessions::stop when done.
headfulboolean
Force a visible window for this session, overriding the configured `headless` default.
read_onlyboolean
Inspection-only session: act, evaluate, execute, and styles::write are rejected while navigation, snapshots, reads, and screenshots work. Immutable for the session's lifetime.
urlstring
URL to open immediately. Omit to start on about:blank.
read_onlyboolean*required
session_idstring*required
Pass this to every other browser function.
browser::sessions::stop
functionStop a browser session and its Chromium process. Idempotent: stopping an unknown or already-stopped session succeeds with was_running=false.
session_idstring*required
Session to stop. Stopping an unknown or already-stopped id succeeds.
was_runningboolean*required
False when the session was already gone.
browser::snapshot
functionRead the page as an accessibility-tree outline. Lines carry [ref=eN] handles that browser::act accepts; refs stay valid until the next navigation. Prefer this over browser::screenshot; it is cheaper and machine-readable.
diffboolean
Return only what changed since this session's previous snapshot instead of the full outline. Falls back to a full snapshot when there is no baseline (first snapshot, or first after a navigation).
session_idstring*required
diffany of
Present when the caller asked for `diff: true` and a baseline existed. Covers only the emitted nodes of both snapshots; check `truncated` before trusting it as a complete change set.
any of (2)
variant 1
unchangedinteger· uint64*requiredmin 0
generationinteger· uint64*requiredmin 0
Document generation the refs belong to; navigation advances it and kills every ref from earlier generations.
treestring*required
Indented outline; lines carry `[ref=eN]` handles for `browser::act`. Empty when `diff` is populated.
truncatedboolean*required
True when the tree hit `max_snapshot_nodes` and was cut short. Also the signal that a `diff` may be incomplete: the diff is computed over emitted nodes only, so when either snapshot was truncated a node that was emitted before and capped out now can show up in `removed` even though it still exists (and vice versa for `added`).
browser::stealthy-fetch
functionCamoufox stealth browser: solves Cloudflare, hardens WebRTC/canvas; extraction + bulk.
css_selectorstring
scope the render to this CSS subtree (e.g. a page's content div)
formatstringenum: markdown, text
render page body to this format
main_content_onlyboolean
strip nav/scripts/hidden before rendering
selectorsobject[]
allboolean
return every match as a list
attrstring
extract this attribute instead of text
htmlboolean
extract inner HTML instead of text
timeoutnumber
milliseconds (browser fetcher)
waitnumber
extra ms to wait after load
wait_selector_statestringenum: attached, detached, visible, hidden
contentstring
markdown/text render when `format` requested
browser::styles::read
functionRead an element's computed styles (curated design set by default, or named properties) plus its inline style attribute.
propertiesstring[]
Computed property names to return. Omit for a curated design-panel set; pass `["*"]` for every computed property.
refstring*required
Element ref from `browser::snapshot`, `browser::dom::read`, or a pick.
session_idstring*required
inline_stylestring
The element's inline `style` attribute, when present.
propertiesobject[]*required
browser::styles::write
functionSet one inline CSS property on an element, live in the page. Visual experiment only: the page's source files are untouched, and the edit dies with the next navigation.
importantboolean
Apply with `!important`.
propertystring*required
CSS property name (`background-color`).
refstring*required
Element ref to edit.
session_idstring*required
valuestring*required
CSS value (`#101418`). Empty string removes the inline property.
inline_stylestring*required
The element's inline `style` attribute after the edit.
browser::tabs::list
functionList the open tabs of a running browser reachable at a CDP endpoint (url, title, and whether a session already adopted each). Read-only; adopt one with browser::sessions::attach.
cdp_urlstring*required
CDP endpoint of the running browser, as in browser::sessions::attach.
tabsobject[]*required
adoptedboolean*required
True when a session already adopted this tab; it cannot be adopted again until that session stops.
browser::to-markdown
functionConvert HTML to compact Markdown (or text/html); optional CSS scope + main-content clean.
css_selectorstring
convert only the subtree matching this CSS selector
formatstringenum: markdown, text, html
main_content_onlyboolean
strip nav/scripts/hidden nodes first
browser::ui-content
functionServe the browser worker's injected console UI assets (content function for its console:script / console:style triggers).
pathstring*required
The asset path from the trigger config (e.g. `state/page.js`).
contentstring*required
The asset source, verbatim.
content_typestring*required
MIME type the console should serve the asset with.
One XPath query over HTML; first-or-all; `attr` pulls an attribute else text.
adaptiveboolean
relocate elements after a site change via saved identities
adaptive_domainstring
page URL/domain that keys saved identities
auto_saveboolean
save matched identities (defaults on when adaptive)
identifierstring
stable key for the saved element
