browser
browser.add_init_script
browser.add_init_script
Register JavaScript that runs BEFORE the page's own code, at document start, on every page opened afterwards in this identity's context. Use when browser.evaluate is too late — most often to hook window.fetch/XMLHttpRequest and capture a SPA's request bodies, which network_requests cannot show. Does NOT affect already-open pages: add the script first, then browser.open. Cannot be removed once added; it lives until the context is evicted or browser.close is called.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
identity_name | string | no | default _anon |
script | string | yes |
browser.attach_identity
browser.attach_identity
Switch the page's identity by loading saved cookies + storage. Use only when switching identity mid-page; for first navigation, pass identity_name to browser.open instead.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
identity_name | string | yes | |
page_id | string | yes |
browser.attach_meet
browser.attach_meet
Attach to THIS meet's bot browser and return a page_id for its live Google Meet tab. Then use the normal browser.* tools (browser.snapshot to see the page, browser.click to press a control, browser.take_screenshot, browser.evaluate, browser.console_messages, browser.network_requests) with that page_id to inspect why the bot isn't visibly joining (lobby/blocked/admitted) and to recover a stalled join. Call with no arguments from inside a meet.
Arguments
No arguments.
browser.click
browser.click
Click an element. ref is either an aria-ref token from browser.snapshot ('e7') OR a CSS selector ('button.submit'). Prefer the aria-ref token.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
page_id | string | yes | |
ref | string | yes |
browser.close
browser.close
Close a page opened by browser.open.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
page_id | string | yes |
browser.console_messages
browser.console_messages
Return console.log/warn/error events captured since the last drain. Filter by level ('log'|'info'|'warning'|'error'|'debug') and/or pattern (regex). Buffer caps at 500 entries; oldest are dropped first. Set clear=false to peek without draining.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
clear | boolean | no | default True |
level | string | null | no | default None |
page_id | string | yes | |
pattern | string | null | no | default None |
browser.create_identity
Create a browser identity and get the sign-in link
Effects: write
Create a browser identity for a website the person must sign in to (or sign up on) themselves, and get back a link to give them. Opening the link shows a live browser on the site; when they have signed in they press 'I'm logged in, save session' and the identity becomes active, after which browser.open / browser.attach_identity work with it. Use browser.handoff instead for an identity that already exists and is active. For a plain username + password sign-in form WITHOUT captcha or 2FA, pass username, password and confirm_sign_in_stored=true and the platform signs in itself (admin or owner only): the answer is status 'active' on success, or the reason plus the human link when the site wanted more (a captcha, a code). When the site refuses the username or password, an identity created by this call is deleted again (status 'deleted'); one that already existed is left as it was. The password is kept encrypted in the workspace's secret store and used to sign in again when the session expires.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
confirm_sign_in_stored | boolean | no | Required true with username and password: the an admin or the owner of the workspace confirms that the platform stores this sign-in encrypted, types it into the site's login form in its own browser and keeps the session (the disclosure a person accepts in the sign-in window). Journalled. OMIT when not signing in. |
name | string | yes | Name for the identity, unique in the workspace (e.g. 'stripe_main'). A pending identity of the same name is resumed. |
origin | string | yes | The site the identity is for, an https address (e.g. https://dashboard.example.com). |
password | string | no | The site's own password for username. Stored encrypted, never returned or logged. |
url | string | no | The first page the person lands on, e.g. a signup page. Must be on the same domain as origin. Omit to start on the origin. |
username | string | no | The site's own login (email or username). With password, the platform signs the identity in itself instead of waiting for a person. Admin or owner only. |
browser.delete_identity
Delete a browser identity
Effects: delete
Delete a browser identity of this workspace. Give EXACTLY ONE of identity_id (the id) or name (the identity's name); the older identity (name or id) is still accepted. The saved session, the stored sign-in (if any) and a sign-in window still open for it are removed, and it disappears from /connections. Only the identity's creator or a workspace admin/owner may delete it. Cannot be undone: the person has to sign in again to get it back. Use it to clean up a pending identity that was never completed, or one that is no longer needed.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
identity | string | no | Deprecated: the old single parameter, a name or an id. Use identity_id or name instead. A number is an id only when no identity has that exact name. |
identity_id | integer | no | The id of the browser identity to delete. Give this or name. |
name | string | no | The name of the browser identity to delete (unique in the workspace). Give this or identity_id. |
browser.drag
browser.drag
Drag one element onto another. source_ref is the element to grab; target_ref is where to drop. Both are CSS selectors. Used for slider captchas, kanban, drag-and-drop uploads.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
page_id | string | yes | |
source_ref | string | yes | |
target_ref | string | yes |
browser.evaluate
browser.evaluate
Run JavaScript in the page context and return the result. Use for state not in the a11y tree, captcha iframe inspection, DOM events. Expression is either a plain JS value ('document.title') or a zero-arg IIFE ('(() => { … })()'). Inline any runtime values into the expression itself. Result is JSON-serialized; non-serializable values become strings. 256KB cap on output.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
expression | string | yes | |
page_id | string | yes |
browser.file_upload
browser.file_upload
Attach files to an <input type=file>. Pass either local_paths (absolute host paths) or data (list of {name, mime, base64} blobs written to /tmp). 25MB cap per file.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
data | array | null | no | default None |
local_paths | array | null | no | default None |
page_id | string | yes | |
ref | string | yes |
browser.fill
browser.fill
Fill an input or textarea with the given value. ref is either an aria-ref token from browser.snapshot ('e7') OR a CSS selector ('input[name=email]'). Prefer the aria-ref token — it's stable and matches exactly what snapshot returned.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
page_id | string | yes | |
ref | string | yes | |
value | string | yes |
browser.fill_form
browser.fill_form
Fill multiple form fields in one call. fields is a list of {ref, value} dicts. ref is a CSS selector; value is a string (text) or boolean (checkbox). Saves N round-trips vs calling browser.fill repeatedly.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
fields | array | yes | |
page_id | string | yes |
browser.handle_dialog
browser.handle_dialog
Respond to a pending JS dialog (alert/confirm/prompt). Pass accept=true for OK or false for Cancel. For prompt() dialogs also pass prompt_text. Dialogs are queued at page-open time; returns {pending: false} if none is waiting.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
accept | boolean | yes | |
page_id | string | yes | |
prompt_text | string | null | no | default None |
browser.handoff
Handoff a browser identity to the person for verification
Effects: external_api
When a site asks for verification (2FA, captcha, identity check, re-login) that only the person can do, call this tool with the browser identity name and the URL that needs them. Returns a link to give the person — clicking it opens their browser identity already on that page. When they finish they press Done, and you can continue. For several pages in a row, navigate the SAME prepared window rather than preparing a new one: the person keeps watching one window.
With prepare=True (optional): start the identity's browser server-side on the URL, attach it for form-filling, and return a page_id. Use the page_id with browser.fill / browser.click to fill the form in the live browser before giving the person the link — they will see it already filled and only need to review and complete verification steps that only they can do (CAPTCHA, consent, 2FA code). The window stays open for 30 minutes; if you do not send the link within that time, the window closes and the person must start over.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
close | boolean | no | If true (optional, default false): close the identity's prepared window that nobody has opened yet. Use this when you no longer need the window you prepared with prepare=true; a window the person has opened is left to them. Returns whether a window was closed. Requires EDIT role (same as prepare). The window only closes if it belongs to this workspace. OMIT for a normal handoff. |
identity | string | yes | The browser identity, by name or id (as browser.open takes it). Must be an active identity in this workspace. |
prepare | boolean | no | If true (optional, default false): start the identity's browser server-side on the URL and attach it so you can fill the form with browser.fill / browser.click before giving the person the link. Returns a page_id you can drive with the generic browser tools, plus the handoff link. False or omitted: just build and return the link — the browser starts when the person opens it. |
reason | string | no | Why the person is needed (optional, for context). E.g. '2FA code entry', 'identity verification', 'security check'. |
url | string | no | The URL that needs the person's attention. Must be https or http, and on the same domain as the identity's origin (e.g. https://dashboard.stripe.com/auth/verify). Subdomains are allowed. |
browser.hover
browser.hover
Hover the mouse over an element (reveals tooltips + hover menus). ref is a CSS selector.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
page_id | string | yes | |
ref | string | yes |
browser.navigate_back
browser.navigate_back
Navigate back in the page's history (browser back button). Returns the new URL + title.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
page_id | string | yes |
browser.network_requests
browser.network_requests
List HTTP requests the page made since open or last drain. Optional filters: method (GET/POST/...), url_pattern (regex), status_min (e.g. 400 for errors). Captures up to 200 most recent requests per page.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
clear | boolean | no | default False |
method | string | null | no | default None |
page_id | string | yes | |
status_min | integer | null | no | default None |
url_pattern | string | null | no | default None |
browser.open
browser.open
Open a URL in a remote browser. Saved login cookies are auto-attached when the URL domain matches a claimed browser identity. Pass identity_name to override auto-matching or force a specific identity.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
identity_name | string | null | no | default None |
url | string | yes |
browser.press_key
browser.press_key
Press a keyboard key (e.g., 'Enter', 'Tab', 'Escape', 'ArrowDown') or a single character. Optional ref focuses an element first — aria-ref token from browser.snapshot ('e7') or a CSS selector.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
key | string | yes | |
page_id | string | yes | |
ref | string | null | no | default None |
browser.resize
browser.resize
Resize the page viewport. Useful when a site serves different HTML based on viewport width (mobile vs desktop) or when an anti-bot scores risk by viewport dimensions.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
height | integer | yes | |
page_id | string | yes | |
width | integer | yes |
browser.save_session
Save a page's sign-in to its browser identity
Effects: write
Save the sign-in of an OPEN page into the browser identity the page was opened with (browser.open with identity), the same as a person's "I'm logged in, save session" button. Without it a sign-in made in a browser.open page is lost when the page closes, and everything that reads the identity (channels.reconnect, integrations) keeps the old session. Call it ONLY after checking the page shows the signed-in state (a logged-out page would replace a working session), before closing it. Refused when the page was opened without an identity, when the identity is not active or expired, or when the page is not signed in to the identity's own site. Nothing secret is returned. Needs the member, admin or owner role.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
page_id | string | yes | page_id of the open, signed-in page (from browser.open with identity). |
browser.select_option
browser.select_option
Pick option(s) in a native <select> dropdown. Pass value (matches the option's value attr) OR label (matches its visible text). Lists allowed for multi-select.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
label | string | array | null | no | default None |
page_id | string | yes | |
ref | string | yes | |
value | string | array | null | no | default None |
browser.snapshot
browser.snapshot
Return a YAML aria_snapshot of the page DOM. Each interactive node is tagged with [ref=eN] (e.g. [ref=e7]). Pass that exact token as the ref arg to browser.click / browser.fill / browser.type / browser.press_key. Do NOT pass the role name ('combobox', 'button') as ref — only the eN token. Truncated at 32KB.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
page_id | string | yes |
browser.tabs
browser.tabs
Manage tabs within the same BrowserContext as page_id. action ∈ {list, switch, close, new}. For list, returns all open tab metadata; for new, returns the new tab's page_id.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
action | string | yes | |
page_id | string | yes | |
tab_id | string | null | no | default None |
url | string | null | no | default None |
browser.take_screenshot
browser.take_screenshot
Capture a PNG screenshot of the page or a specific element. Returns base64-encoded image bytes AND a file_id (persisted in DialogBrain files storage). Pass file_id straight to messages.send(attachment_file_ids=[file_id]) — do NOT call files.upload again. Use sparingly — favor browser.snapshot for structured DOM understanding.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
full_page | boolean | no | default False |
inline_bytes | boolean | no | default False |
page_id | string | yes | |
ref | string | null | no | default None |
browser.type
browser.type
Type text into an element with per-keystroke delay (organic). Each character dispatches keydown/keypress/keyup, unlike browser.fill which replaces .value instantly. Use when the page listens to keystroke events or for typing-speed fingerprint checks. ref is an aria-ref token from browser.snapshot ('e7') or a CSS selector. delay_ms defaults to 50. The element is emptied first unless clear is false, which appends at its end.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
clear | boolean | null | no | default True |
delay_ms | integer | null | no | default 50 |
page_id | string | yes | |
ref | string | yes | |
text | string | yes |
browser.wait_for
browser.wait_for
Wait for a selector to appear OR a navigation URL to match a glob pattern. Provide ref (selector) OR url_pattern (glob).
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
page_id | string | yes | |
ref | string | null | no | default None |
timeout_ms | integer | no | default 10000 |
url_pattern | string | null | no | default None |