Browser

Browser support lets agents navigate websites, interact with page elements, fill out forms, and extract data. Mastra offers two kinds of browser providers:

• SDK providers wrap a browser automation library and give the agent browser tools directly.
• CLI providers launch a browser that the agent controls through command-line tools.

Mastra includes three SDK providers and one CLI provider:

• AgentBrowser: An SDK provider built on Playwright that finds page elements through accessibility information. Use it for general web automation and scraping.
• Stagehand: An SDK provider built on the Stagehand library from Browserbase. It uses AI to find page elements. Use it for complex interactions where describing an element in natural language works better than a fixed selector.
• FirecrawlBrowser: An SDK provider that runs AgentBrowser tools in hosted Firecrawl Browser Sandbox sessions. Use it to avoid running browsers on your own infrastructure.
• BrowserViewer: A CLI provider that launches Chrome and passes its Chrome DevTools Protocol (CDP) URL to CLI tools such as agent-browser, browser-use, and browse. Use it for workspace agents that control browsers through shell commands.

When to use a browser

Give your agent a browser when it needs to:

• Navigate websites and interact with page elements
• Fill out and submit forms
• Extract structured data from web pages
• Automate web tasks that take several steps
• Work with pages that only function in a real browser, such as pages that render content with JavaScript or require a login

How it works

When you assign a browser to an agent, Mastra includes the provider's tools in the agent's toolset. The agent uses these tools to control the browser. It can open URLs and select elements. It can also type text and read page content.

Each provider offers a different set of tools optimized for its approach.

Quickstart

Install your provider of choice, for this example you'll use the AgentBrowser provider.

npm

npm install @mastra/agent-browser

pnpm

pnpm add @mastra/agent-browser

Yarn

yarn add @mastra/agent-browser

Bun

bun add @mastra/agent-browser

Create a new browser instance:

src/mastra/browsers.ts

import { AgentBrowser } from '@mastra/agent-browser'

export const browser = new AgentBrowser({
  headless: false,
})

Assign the browser to an agent:

src/mastra/agents/web-agent.ts

import { Agent } from '@mastra/core/agent'
import { browser } from '../browsers'

export const webAgent = new Agent({
  id: 'web-agent',
  name: 'Web Agent',
  description: 'A web automation assistant that can navigate websites and complete tasks.',
  model: 'openai/gpt-6.1-sol',
  browser,
  instructions:
    'You are a web automation assistant. Use browser tools to navigate websites and complete tasks.',
})

The agent automatically receives all browser tools from the provider.

Cloud providers

All SDK providers support connecting to cloud browser services instead of launching a local browser.

Firecrawl Browser Sandbox (FirecrawlBrowser native)

FirecrawlBrowser provisions hosted sessions through the Firecrawl API:

import { FirecrawlBrowser } from '@mastra/browser-firecrawl'

const browser = new FirecrawlBrowser({
  apiKey: process.env.FIRECRAWL_API_KEY,
})

Browserbase (Stagehand native)

Stagehand has native Browserbase integration:

import { StagehandBrowser } from '@mastra/stagehand'

const browser = new StagehandBrowser({
  env: 'BROWSERBASE',
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
})

Browser Use Cloud (AgentBrowser CDP)

Connect AgentBrowser to a Browser Use Cloud browser using your Browser Use API key:

import { AgentBrowser } from '@mastra/agent-browser'

const browser = new AgentBrowser({
  cdpUrl: `wss://connect.browser-use.com?apiKey=${process.env.BROWSER_USE_API_KEY}`,
})

CDP URL (any provider)

Connect to any browser exposing a Chrome DevTools Protocol (CDP) endpoint:

import { AgentBrowser } from '@mastra/agent-browser'

const browser = new AgentBrowser({
  cdpUrl: process.env.BROWSER_CDP_URL,
  headless: true,
})

This works with any CDP-compatible browser service.

Screencast

Browser providers stream a live video feed of the browser to the Mastra Studio UI. This lets you watch the agent interact with pages in real-time.

Screencast requires WebSocket support. Install these packages in your project:

npm

npm install ws @hono/node-ws

pnpm

pnpm add ws @hono/node-ws

Yarn

yarn add ws @hono/node-ws

Bun

bun add ws @hono/node-ws

note

These packages aren't included by default because they're incompatible with serverless environments like Cloudflare Workers. If they aren't installed, screencast is disabled but all other browser functionality works normally.

Screencast is enabled by default and can be configured:

const browser = new AgentBrowser({
  screencast: {
    format: 'jpeg',
    quality: 80,
    maxWidth: 1280,
    maxHeight: 720,
  },
})

Record browser sessions

AgentBrowser and StagehandBrowser can opt into recording for reviewing, sharing, or debugging browser runs. Configure outputDir to add the recording tools:

src/mastra/browsers.ts

import { join } from 'node:path'
import { AgentBrowser } from '@mastra/agent-browser'

export const browser = new AgentBrowser({
  recording: {
    outputDir: join(process.cwd(), 'browser-recordings'),
  },
})

StagehandBrowser accepts the same recording option. The agent uses browser_record to start, check, and stop a recording, and browser_record_caption to label major actions. Stopping saves the video and lets the agent return its path. A custom outputPath can be absolute or relative to the current working directory, and must resolve to a path inside recording.outputDir.

Recordings use Motion-JPEG AVI and don't require ffmpeg. The default maximum duration is 30 seconds, with a 120-second hard cap. The default maximum frame size is 1024 × 720, captions are limited to 80 characters, and only one recording can be active per process.

Next steps

• AgentBrowser
• Stagehand
• Firecrawl
• BrowserViewer
• MastraBrowser reference
• 📹 Mastra browser capabilities workshop