Browser Agent

The browserless_agent tool turns any MCP-compatible AI assistant into a browser-using agent. Unlike stateless scraping tools, the agent keeps a browser session across tool calls and exposes a snapshot-based protocol so the model can reason about what's on the page and drive it step by step.

Use it when a single scrape isn't enough — filling forms, logging in, clicking through multi-step flows, paginating search results, interacting with consent dialogs, or any task that needs the browser's state to survive between turns.

How it works

The agent follows the classic ReAct loop — Reason → Act → Observe:

goto — navigate to a URL
snapshot — capture every interactive and informational element on the page (buttons, links, inputs, headings, images with alt text) as a compact list with stable selectors
plan — the model reads the snapshot and decides what to do
act — click, type, select, scroll, etc., using selectors taken directly from the snapshot
re-snapshot whenever the page changes (navigation, form submission)
Repeat until the task is done, then close

The browser session means the browser keeps cookies, local storage, and navigation history across commands. State doesn't reset between tool calls — you can log in once and keep interacting with authenticated pages.

Available methods

Method	Purpose
`goto { url, waitUntil? }`	Navigate to a URL. Defaults to `waitUntil: "domcontentloaded"`.
`back { waitUntil? }`	Go back in browser history.
`forward { waitUntil? }`	Go forward in browser history.
`reload { waitUntil? }`	Reload the current page.

Observation

Method	Purpose
`snapshot { maxElements? }`	Capture the page as a list of interactive + informational elements with selectors.
`text { selector }`	Extract the text of a specific element.
`html { selector? }`	Get the raw HTML of a section (or the whole page).
`evaluate { content }`	Run arbitrary JavaScript in the page context (IIFE syntax).

Interaction

Method	Purpose
`click { selector }`	Click an element.
`type { selector, text }`	Type text into an input.
`select { selector, value }`	Choose an option in a `<select>`.
`checkbox { selector, checked? }`	Toggle a checkbox (preferred over `click` for checkboxes).
`hover { selector }`	Hover over an element.
`scroll { selector?, direction? }`	Scroll the page or a specific element.

Waiting

Method	Purpose
`waitForSelector { selector, timeout? }`	Wait for a DOM element to appear.
`waitForNavigation { timeout? }`	Wait for a page navigation to complete.
`waitForTimeout { time }`	Wait for a fixed duration (ms).
`waitForRequest { url?, method?, timeout? }`	Wait for a network request matching a URL glob.
`waitForResponse { url?, statuses?, timeout? }`	Wait for a network response matching a URL glob and/or status codes.

Session

Method	Purpose
`liveURL { timeout?, interactable?, quality?, type?, resizable? }`	Open a shareable live view of the browser that a human can watch or interact with.
`close`	End the browser session.

Batching

When multiple actions share the same page state (for example filling a form), they can be batched into a single tool call using the commands array. This is significantly faster than invoking the tool once per step.

{
  "commands": [
    { "method": "type", "params": { "selector": "input#email", "text": "user@example.com" } },
    { "method": "type", "params": { "selector": "input#password", "text": "secret" } },
    { "method": "click", "params": { "selector": "input#remember-me" } },
    { "method": "click", "params": { "selector": "button[type='submit']" } }
  ]
}

Batching is safe for actions that don't change the page (type, hover, scroll, checkbox, non-navigating select). Page-changing actions — click on a link or submit button, goto, or anything that triggers navigation — should be the last command in the batch, because the next command would execute against the old DOM.

Error recovery

The agent protocol returns structured errors with codes the model can reason about:

Code	Meaning	Typical recovery
`SELECTOR_NOT_FOUND`	Element didn't exist or wasn't found in time	Try a deep selector (`< selector`) — the element may be in shadow DOM. Otherwise re-snapshot.
`NAVIGATION_TIMEOUT`	Page didn't reach the requested ready state	Retry with a longer timeout or `waitUntil: "domcontentloaded"`.
`TIMEOUT`	Generic operation timeout	Retry with a longer timeout.
`BROWSER_CRASHED`	Session is gone	The MCP client transparently reconnects — the agent just re-navigates.
`INVALID_PARAMS`	Bad arguments	Not retryable.
`RATE_LIMITED`	Too many requests	Wait and retry.

When a selector isn't found, the error response also includes a fresh snapshot so the model can re-plan without an extra round trip.

When to use the agent vs. Smart Scraper

Use browserless_smartscraper when you need the content of a single page. It picks the best strategy (direct fetch → proxy → headless browser → CAPTCHA solving) and returns the content in your preferred format.
Use browserless_agent when the task requires multiple turns, state, or interaction — logging in, filling forms, paginating, navigating menus, reacting to what's on the page.

Example tasks

Ask your AI assistant:

Find a French ratatouille recipe on Allrecipes with a 4-star rating or higher and at least 15 reviews. Note the variety of vegetables included and the overall cooking time.

Open Google Flights, search for a round-trip flight from New York to Tokyo departing March 10, 2026 and returning March 24, 2026, and list the five cheapest options.

Search for a local text-to-speech repository on GitHub updated in the last 10 days with at least 200 stars and summarize its main objective.

Go to FedEx. Calculate the shipping rates for a 10-pound package from Miami, FL to San Francisco, CA, and summarize prices and delivery dates.

How it works​

Available methods​

Navigation​

Observation​

Interaction​

Waiting​

Session​

Batching​

Error recovery​

When to use the agent vs. Smart Scraper​

Example tasks​

Further reading​