BrowserDo

Run several page actions on one tab in a row, all aimed with the numbers of one snapshot, then get a fresh snapshot back — one call instead of one per step. Use it for steps that do not depend on each other's result: tick two filters, fill three fields that are already on screen. Do not put a step in that aims at something an earlier step makes appear (a suggestion list, a menu): its number does not exist yet. Stops at the first failure; after a step the browser says changed the page, the later steps that aim by number are skipped. Worth using for a single action too: the snapshot comes back in the same call.

Click an element by its number (emsn) from the latest snapshot. The kernel asks the page where that element is right now and refuses if it has gone, moved out of reach, or is covered by something else — it does not pretend to succeed. Passing x/y instead skips all of that checking, so prefer emsn.

Answer the popup blocking a tab (permission bubbles, dialogs). browser_take_snapshot reports which popups are open and what each one accepts. When unsure use dismiss: it refuses without writing a decision into the browser profile, where it would outlive the task.

Close a tab.

Close a browser window and every tab in it. Other windows are unaffected. To close a single tab use browser_close_tab.

Press on something, carry it somewhere, let go. The one gesture a click cannot make, so this is for sliders, panning a canvas, split bars and lists that reorder. Give the destination exactly one way: toEmsn (with toX and toY for a spot inside it), or toX and toY, or dx and dy. **Both ends must already be on screen** — the far end is not scrolled into view, so scroll first.

List every browser window and its tabs, with the windowId and tabId of each. Use it to find out what is open; the other tools default to the frontmost window and tab, so you usually do not need to call this first.

Go back one step in this tab's history. browser_get_window_info reports whether a tab can go back; calling this when it cannot will fail.

Go forward one step in this tab's history.

Type text into an element by its number (emsn), or into whatever has focus when no emsn is given. Fails, typing nothing, when the field does not take focus. Also sets a dropdown (SELECT, or its label): text is the option exactly as listed in its options; and a date (YYYY-MM-DD), time (HH:MM), date and time (YYYY-MM-DDTHH:MM), month (YYYY-MM), week (YYYY-Www) or colour (#rrggbb) field, without opening a picker. Use this rather than clicking a SELECT: its list is not in snapshots. To edit a text field or editable area (a mail body, a rich-text editor) in the middle, give one of before / after / replace / at with its emsn. Copy the words from its snapshot value as they are written there: \n for a line break, ¤ escapes kept; ‸ (the caret) and ⟦⟧ (the selection) are ignored. Not found, or found in several places without occurrence: nothing is typed and the places are listed. The text is read back afterwards and the reply quotes the changed lines; if they differ (the editor reformatted it), it fails saying the text was typed. Without these, text goes in at the caret; the element is clicked first unless focus is already in it.

Minimize one of your windows (every tab in it yours), to keep it out of a person's way while you work in it. Pages in it keep running at full speed and snapshots keep working. browser_show brings it back.

Hover the pointer over an element, for a menu or a tooltip that only appears under it. Whatever appears is not numbered until you take a fresh snapshot, so hover first, then snapshot, then act. The reply says where the pointer ended up.

Open a URL in a tab. Element numbers from before the navigation are void afterwards.

Open a new tab. Returns the new tabId.

Open a new browser window. Returns the new windowId.

Press keys, in order, where focus is: Escape closes a dialog on the page, Tab moves to the next field, ArrowDown/Enter pick from a suggestion list, End or arrows move the caret before browser_input_text without emsn types there, Control+Z undoes. Not for typing text. Refused, nothing pressed: copy/cut/paste, and the browser's own shortcuts (use browser_close_tab, browser_reload and so on). Replies once the page has handled the last key; it does not say what the keys did, so snapshot to see. A list highlighted under the pointer counts arrows from that item, which a snapshot does not show: to pick a given item, click it.

Read web pages; use it instead of a built-in fetch tool (WebFetch): it returns the page's own text, not a summary, including pages built by scripts and sites the person is signed in to. Each URL opens in a background tab of an existing window, the whole page is read and the tab closed again, so nothing is left open. Returns each page's text with no element numbers — to act on a page, open it with browser_new_tab instead. Links are marked [^3], with the addresses after the text. Each page gives up to 15000 characters and says how to read on. One page failing does not fail the others. Not for search results URLs: engines often answer those with a captcha, so search by typing into the engine's own search box.

Reload the tab. Element numbers from before the reload are void afterwards.

Carry out a whole web task in a real browser and report what happened. This takes minutes, not seconds, and reports progress as it goes. Describe the task in plain language; it works out the steps itself. If it hits a login, a captcha or a payment screen it stops and hands the browser to the person, then picks up where it left off once they are done. Needs a vision model configured (EMBIODY_VLLM_*); for a small job you can drive the browser yourself with browser_take_snapshot / browser_click / browser_input_text instead, which needs no model.

Scroll. Give deltaY (how far; positive is down, as scrollTop counts) or toY (where to end up; 0 is the top, 999999 the bottom), not both; deltaX / toX are the horizontal ones. What scrolls is whatever is under the pointer: to scroll a pane that scrolls on its own (a mail list, a results panel), give its emsn; emsn -1 scrolls the whole page, only when the snapshot's page position line offers it. Replies once the scroll is at rest, saying when it moved less than asked (at the end, or the page took the wheel); coordinates are void after a scroll, so take a fresh snapshot to see where you are.

Select words in a text field or editable area (a mail body, a rich-text editor), as a person drags over them, so a toolbar button (bold, colour, link) acts on them next: a click on it can follow in the same batch. Nothing else changes, except that a click giving it focus stays. Give one of select, from with to, or all. Copy the words from the element's snapshot value as for browser_input_text's before/after. The reply quotes the lines the selection is on, marked ⟦…⟧. Refused, nothing selected: not found, or in several places without occurrence (the places are listed); an end inside a picture, a list number or an @mention; across table cells where the editor keeps a selection in one cell (select cell by cell); over a picture with its own editable caption (click the picture instead); a password, read-only or disabled field.

Bring a tab to the front of its window.

Mute or unmute a tab.

Bring a window on screen. Windows driven by an agent are often hidden or off screen, so show one before asking a person to look at it.

Hand the tab to a person so they can use the real keyboard and mouse on it. Required for anything only a person can do — a password, a code sent to them, a captcha, proving who they are — because while the agent drives the tab their physical input does not reach the page at all. The window is brought on screen. While the person has it, every command on that tab fails except browser_take_snapshot, which is how you tell when they are done. Call browser_stop_human_control to resume.

Say whether the browser is ready, without doing anything in it. On first use BrowserDo downloads and installs the Embiody browser, which takes a few minutes; until then every other tool replies with the progress instead of acting, and this one reports it.

Take the tab back and resume automating it. A handover the agent started can be ended freely; if the person took the tab over themselves, they are asked first and may refuse.

Stop the page loading in this tab, like the browser's stop button. This is about page loading only. To stop a running browser_run_task, use browser_stop_task.

Stop a running browser_run_task, by the ID that browser_run_task returned. The task stops at the end of its current step and does not resume. Optionally closes the tab or the whole browser window it was using; other windows are left alone. This is not the same as cancelling the task at the protocol level: that is advisory and may be ignored, and it cannot tidy up the browser. To stop a page loading rather than a task, use browser_stop_loading.

Look at a tab: returns one line per element, the page position, the tab's URL and title, any popups blocking it, and a snapshotId. Every actionable element carries a number (emsn) at the start of its line — act on the number, never on pixel coordinates. Take a fresh snapshot after anything that changes the page, to see what it became: elements that appear have no number until then. Says so when the page is a PDF, a browser error page or a crashed tab, each of which makes the obvious next move useless. Give tabIds to look at several tabs in one call; each comes back with its own snapshotId. Marks on a line: collapsed (in a closed section: open it first), modal (the page outside it takes no clicks), hover-only (may do nothing on a click), also dblclick / drag / ... (other listeners, perhaps only tracking; the list misses some: a list item without drag may still drag, a spreadsheet cell without right_click may still take one: try it and snapshot), options (a dropdown's choices), readonly (takes no typing; clicking it often opens the page's picker), aria-readonly (the page says not to type, typing still goes in).

Wait before looking again, for pages that are still settling. Clamped to 100–10000 ms.