Classe MastraBrowser

La classe MastraBrowser est la classe de base abstraite des Providers d'automatisation de Browser. Son interface commune couvre le lancement du Browser et l'isolation des fils de discussion, ainsi que le streaming du screencast et les événements d'entrée.

Vous n'instanciez pas directement MastraBrowser. Utilisez plutôt l'implémentation d'un Provider :

• AgentBrowser : automatisation déterministe du Browser au moyen de références
• StagehandBrowser : automatisation du Browser reposant sur l'IA et le langage naturel
• BrowserViewer : automatisation du Browser fondée sur la CLI avec injection d'une URL CDP

Exemple d'utilisation

src/mastra/agents/index.ts

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

const browser = new AgentBrowser({
  headless: true,
  viewport: { width: 1280, height: 720 },
  scope: 'thread',
})

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  instructions: 'You can browse the web to find information.',
  model: 'openai/gpt-5.6-sol',
  browser,
})

Paramètres du constructeur

headless?:

boolean

= true

Indique si le Browser doit être exécuté en mode headless (sans interface utilisateur visible).

viewport?:

{ width: number; height: number } | 'window'

= { width: 1280, height: 720 }

Dimensions du viewport du Browser. Contrôle la taille de la fenêtre du Browser. Définissez cette option sur 'window' pour correspondre à la fenêtre réelle du Browser au lieu d'utiliser une taille fixe ; cette valeur est prise en charge par le Provider agent-browser et par Stagehand lors d'une connexion au moyen de CDP.

timeout?:

number

Délai d’expiration par défaut, en millisecondes. Chaque Provider définit sa propre sémantique et sa valeur par défaut. Consultez la référence du Provider pour plus de détails.

cdpUrl?:

string | (() => string | Promise<string>)

URL WebSocket CDP, endpoint HTTP ou fonction de Provider synchrone/asynchrone. Lorsqu'elle est fournie, se connecte à un Browser existant au lieu d'en lancer un nouveau. Les endpoints HTTP sont résolus en WebSocket en interne. Ne peut pas être utilisée avec scope: 'thread' (utilise automatiquement la portée shared).

scope?:

'shared' | 'thread'

= 'thread' (ou 'shared' lorsque cdpUrl est fourni)

Portée de l'instance de Browser entre les fils de discussion. 'shared' signifie que tous les fils partagent une seule instance de Browser. 'thread' signifie que chaque fil possède sa propre instance de Browser (isolation complète).

onLaunch?:

(args: { browser: MastraBrowser }) => void | Promise<void>

Callback invoqué lorsque le Browser atteint l'état 'ready'.

onClose?:

(args: { browser: MastraBrowser }) => void | Promise<void>

Callback invoqué avant la fermeture du Browser.

screencast?:

ScreencastOptions

Configuration du streaming des frames du Browser.

ScreencastOptions

format?:

'jpeg' | 'png'

Format des images des frames du screencast.

quality?:

number

Qualité de l'image (1 à 100). S'applique uniquement au format JPEG.

maxWidth?:

number

Largeur maximale des frames du screencast.

maxHeight?:

number

Hauteur maximale des frames du screencast.

everyNthFrame?:

number

Capture une frame sur N afin de réduire la bande passante.

Propriétés

Les propriétés suivantes (id, name, provider) sont abstraites et doivent être définies par les implémentations concrètes des Providers :

id:

string

Identifiant unique de cette instance de Browser. Abstrait, défini par le Provider.

name:

string

Nom lisible du Provider Browser (par exemple, 'AgentBrowser' ou 'StagehandBrowser'). Abstrait, défini par le Provider.

provider:

string

Identifiant du Provider (par exemple, 'vercel-labs/agent-browser' ou 'browserbase/stagehand'). Abstrait, défini par le Provider.

headless:

boolean

Indique si le Browser est exécuté en mode headless.

status:

BrowserStatus

État actuel du Browser : 'pending', 'launching', 'ready', 'error', 'closing' ou 'closed'.

Méthodes

Cycle de vie

ensureReady()

Vérifie que le Browser est lancé et prêt à être utilisé. Appelée automatiquement avant l'exécution d'un Tool. Implémentée dans la classe de base.

await browser.ensureReady()

close()

Ferme le Browser et nettoie toutes les ressources. Implémentée dans la classe de base avec une gestion sûre des conditions de concurrence.

await browser.close()

isBrowserRunning()

Vérifie si le Browser est en cours d'exécution.

const isRunning = browser.isBrowserRunning()

Renvoie : boolean

Gestion des fils de discussion

setCurrentThread(threadId)

Définit l'identifiant du fil de discussion actuel pour les opérations du Browser. Utilisée en interne par l'environnement d'exécution de l'Agent.

browser.setCurrentThread('thread-123')

getCurrentThread()

Récupère l'identifiant du fil de discussion actuel.

const threadId = browser.getCurrentThread()

Renvoie : string

hasThreadSession(threadId)

Vérifie si un fil de discussion possède une session Browser active.

const hasSession = browser.hasThreadSession('thread-123')

Renvoie : boolean

closeThreadSession(threadId)

Ferme la session Browser d'un fil de discussion précis. Avec la portée 'thread', ferme l'instance de Browser de ce fil. Avec la portée 'shared', efface l'état du fil.

await browser.closeThreadSession('thread-123')

Tools

getTools()

Renvoie les Tools du Browser à utiliser avec les Agents. Chaque Provider renvoie des Tools différents selon son modèle.

const tools = browser.getTools()

Renvoie : Record<string, Tool>

Diffusion d'écran

startScreencast(options?, threadId?)

Démarre le streaming des frames du Browser. Renvoie un ScreencastStream qui émet des événements de frame.

const stream = await browser.startScreencast({ format: 'jpeg', quality: 80 }, 'thread-123')

stream.on('frame', frame => {
  console.log('Frame received:', frame.data.length, 'bytes')
})

stream.on('stop', reason => {
  console.log('Screencast stopped:', reason)
})

Renvoie : Promise<ScreencastStream>

Injection d'entrées

injectMouseEvent(params, threadId?)

Injecte un événement de souris dans le Browser. Utilisée par Studio pour l'interaction en direct.

await browser.injectMouseEvent({
  type: 'mousePressed',
  x: 100,
  y: 200,
  button: 'left',
  clickCount: 1,
})

injectKeyboardEvent(params, threadId?)

Injecte un événement de clavier dans le Browser. Utilisée par Studio pour l'interaction en direct.

await browser.injectKeyboardEvent({
  type: 'keyDown',
  key: 'Enter',
  code: 'Enter',
})

État

getState(threadId?)

Récupère l'état actuel du Browser, notamment l'URL et les onglets.

const state = await browser.getState('thread-123')
console.log('Current URL:', state.currentUrl)
console.log('Tabs:', state.tabs)

Renvoie : Promise<BrowserState>

interface BrowserState {
  currentUrl: string | null
  tabs: BrowserTabState[]
  activeTabIndex: number
}

interface BrowserTabState {
  id: string
  url: string
  title: string
}

getCurrentUrl(threadId?)

Récupère l'URL de la page actuelle.

const url = await browser.getCurrentUrl()

Renvoie : Promise<string | null>

Portée du Browser

L'option scope contrôle la manière dont les instances de Browser sont partagées entre les fils de discussion :

Portée	Description	Cas d'utilisation
'shared'	Tous les fils partagent une seule instance de Browser	Économique pour les tâches sans conflit
'thread'	Chaque fil possède sa propre instance de Browser	Isolation complète des utilisateurs simultanés

// Shared browser for all threads
const sharedBrowser = new AgentBrowser({
  scope: 'shared',
})

// Isolated browser per thread
const isolatedBrowser = new AgentBrowser({
  scope: 'thread',
})

Lorsque vous utilisez cdpUrl pour vous connecter à un Browser externe, la portée utilise automatiquement 'shared', car vous ne pouvez pas lancer de nouvelles instances de Browser.

Providers Browser cloud

Connectez-vous à des services Browser cloud au moyen de l'option cdpUrl :

// Static CDP URL
const browser = new AgentBrowser({
  cdpUrl: 'wss://browser.example.com/ws',
})

// Dynamic CDP URL (e.g., session-based)
const browser = new AgentBrowser({
  cdpUrl: async () => {
    const session = await createBrowserSession()
    return session.wsUrl
  },
})

Voir aussi

• AgentBrowser : automatisation déterministe du Browser
• StagehandBrowser : automatisation du Browser reposant sur l'IA
• Présentation de Browser : guide conceptuel de l'automatisation de Browser