Browser automation tools

SoAI drives a real Chromium browser through Playwright. Twenty-four tools cover navigating, clicking, typing, reading the page, and debugging what went wrong. Two more fill in credentials without returning the plaintext in their own arguments or results, and those live on the Secrets vault page.

Reach for these when web_fetch comes back thin: a page that renders client-side, a login wall, a form to submit, or anything that needs a second click before the content appears.

In the SoAI WebUI, make these tools available by selecting Chat configuration in the chat header, then Tools. Turn on Tools enabled, choose the required tools under Chat mode, Plan mode, or Execute mode, and select Save. The account needs MCP usage (MCP_USE), the selected model must support tool calling, and both TOOLS.MCP.ENABLED and TOOLS.MCP.BROWSER.ENABLED must be on. Chromium must also be installed or available for automatic installation while SoAI is online.

Page representation

In the standard reference-based workflow, browser_snapshot returns an accessibility tree rather than raw HTML: the elements a screen reader would announce, each with a role, a name, and a short reference string. The structured action tools use those references instead of CSS selectors, which survives class name churn and minified markup. browser_eval is the exception. When enabled, it runs JavaScript in the page and can query or change the DOM directly.

References go stale as soon as the page changes. After a click that navigates or re-renders, the old references point at elements that no longer exist. Most action tools accept include_snapshot so the agent gets a fresh tree back in the same call rather than spending a round trip on it. SoAI caps snapshots at TOOLS.MCP.BROWSER.SNAPSHOT_MAX_CHARS, 20,000 characters by default, and start_char pages through a longer one.

The tools

browser_eval runs JavaScript in the page and covers tasks the structured tools cannot express. SoAI caps scripts at 10,000 characters and 15 seconds. You can switch it off on its own with TOOLS.MCP.BROWSER.JS_EVAL_ENABLED while leaving the rest of the browser working.

JavaScript evaluation can read values from the page DOM, including a password that an autofill tool has placed in a field. Disable it and leave browser_eval out of the selected tools when using protected credentials. See Passwords and credential tools for the full boundary.

The tool catalog classifies browser_persistence_reset as destructive because it wipes a profile's saved cookies and storage. It needs confirm: true, and Plan mode refuses it. Ordinary clicks, typing, uploads, and JavaScript evaluation are not classified as destructive even when the target site gives them lasting effects.

Browser failures

Three tools provide the evidence a stuck agent needs. browser_console replays console messages with a severity filter, which catches the JavaScript error behind a button that does nothing. browser_network lists requests with status filters and can include response bodies up to 64 KiB, which catches the API call returning 403. browser_dialog handles a native alert, confirm, or prompt that has blocked the page: without it, a modal dialog leaves the agent waiting on a page that will never respond.

Both log buffers keep TOOLS.MCP.BROWSER.LOG_MAX_ENTRIES entries, 500 by default, and both accept a since marker so an agent reads only what happened after its last action.

Sessions and profiles

A browser session is a running Chromium instance with its own cookies and tabs. TOOLS.MCP.BROWSER.SESSION_SCOPE decides how widely one is shared, and defaults to conversation, so each chat gets its own browser and two conversations cannot see each other's logins.

Profiles hold the persistent state. The default profile stores cookies and local storage as a Playwright storage state file, saved automatically after changes and reused next time. Named profiles defined in TOOLS.MCP.BROWSER.PROFILES can go further and use a full Chromium user data directory, which keeps extensions and everything else a real browser profile holds. A profile can also point at an existing browser through a CDP endpoint, which attaches to a Chrome you started yourself instead of launching a new one.

Ad blocking is a security feature as well as a performance setting. SoAI evaluates Chromium requests against a packaged or refreshed EasyList matcher and keeps the existing matcher if a refresh fails. This reduces contact with known advertising infrastructure and malicious ads, but it does not block every tracker or hostile script and does not replace the private-network navigation policy. See Browser ad blocking for its security role and limits.

An administrator with Configuration changes (CONFIG_PATCH) can edit these keys: select the Settings button at the right of the header, then Settings, then select Advanced in the Settings page header. The page becomes Advanced settings and the control changes to Basic. Search for a key, edit it, and select Save. Blocking fonts and media by default keeps pages loading quickly; images stay on because a screenshot without them is not much use.

The Chromium runtime downloads on first use, which can take a while on a slow connection. With offline mode on SoAI will not install it, though a runtime that is already installed keeps working.

Where the browser may go

Browser navigation follows its own rule, separate from the private-network switches the other tool families use. While SoAI is online, the browser navigation policy blocks private and loopback addresses, and no setting relaxes that policy. An agent cannot point the browser at your router or SoAI's own admin interface.

Changing TOOLS.MCP.WEB_FETCH.BLOCK_PRIVATE_NETWORK_EGRESS or TOOLS.MCP.HTTP_REQUEST.BLOCK_PRIVATE_NETWORK_EGRESS affects only that named HTTP tool. Neither setting changes browser navigation policy.

Offline mode inverts the rule: SoAI allows only URLs that resolve to the local machine.

Browser authority

A browser session carries real cookies. If you sign a profile in to webmail or an admin panel, an agent with browser tools can act as that account (within the site's own permissions). The tool layer does not distinguish reading a page from clicking Delete.

Give browser tools their own profile rather than one holding your day-to-day logins. The Require tool approval toggle prompts for credential autofill and persistence reset, but ordinary navigation, typing, uploads, JavaScript evaluation, and clicks pass without a prompt because their catalog metadata is nondestructive. Use browser_persistence_reset when a profile has picked up state you did not intend it to keep.

Related documentation

• Agent tools overview
• Security hardening
• Secrets vault
• Web and knowledge tools
• Configuration