Skip to main content

AgentBrowser

The @mastra/agent-browser package provides browser automation using Playwright with accessibility-first element targeting. Elements are identified by refs from the page's accessibility tree, making interactions reliable across different page layouts.

When to use AgentBrowser
Direct link to When to use AgentBrowser

Use AgentBrowser when you need:

  • Reliable element targeting through accessibility refs
  • Fine-grained control over browser actions
  • Playwright's robust automation capabilities
  • Support for keyboard shortcuts and complex interactions

Quickstart
Direct link to Quickstart

Install the package:

npm install @mastra/agent-browser

Create a browser instance and assign it to an agent:

src/mastra/agents/browser-agent.ts
import { Agent } from '@mastra/core/agent'
import { AgentBrowser } from '@mastra/agent-browser'

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

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  model: 'openai/gpt-5.4',
  browser,
  instructions: `You are a web automation assistant.

When interacting with pages:
1. Use browser_snapshot to get the current page state and element refs
2. Use the refs (like @e1, @e2) to target elements for clicks and typing
3. After actions, take another snapshot to verify the result`,
})
note

For local launches (the default), AgentBrowser requires a Chromium binary installed via Playwright. This is normally downloaded automatically when you install @mastra/agent-browser. If launching the browser fails with "browser executable is missing", run npx playwright install chromium. If you connect to a remote browser using the cdpUrl option, no local Chromium is needed.

Element refs
Direct link to Element refs

AgentBrowser uses accessibility tree refs to identify elements. When an agent calls browser_snapshot, it receives a text representation of the page with refs like @e1, @e2, etc. The agent then uses these refs with other tools to interact with elements.

note

See AgentBrowser reference for all configuration options and tool details.

On this page