BrowserViewer

La classe BrowserViewer fournit l’automatisation de navigateur aux outils basés sur CLI. Elle lance Chrome via Playwright, expose une URL Chrome DevTools Protocol (CDP) et l’injecte automatiquement dans les commandes CLI exécutées via les outils de workspace.

Utilisez BrowserViewer lorsque votre agent pilote un navigateur à l’aide d’un outil CLI tel que browser-use, agent-browser ou browse. Pour l’automatisation de navigateur basée sur un SDK, utilisez AgentBrowser ou StagehandBrowser.

Exemple d’utilisation

src/mastra/index.ts

import { Workspace, LocalSandbox } from '@mastra/core/workspace'
import { Memory } from '@mastra/memory'
import { BrowserViewer } from '@mastra/browser-viewer'
import { Agent } from '@mastra/core/agent'

const workspace = new Workspace({
  sandbox: new LocalSandbox({
    workingDirectory: './workspace',
  }),
  browser: new BrowserViewer({
    cli: 'browser-use',
    headless: false,
  }),
})

const browserAgent = new Agent({
  id: 'browser-agent',
  model: 'openai/gpt-5.6-sol',
  workspace,
  instructions: 'You are a web automation assistant.',
  memory: new Memory(),
})

Connexion à un navigateur existant

const viewer = new BrowserViewer({
  cli: 'browser-use',
  cdpUrl: 'ws://127.0.0.1:9222/devtools/browser/abc123',
})

Lorsque cdpUrl est fourni, BrowserViewer se connecte au navigateur existant au lieu d’en lancer un nouveau. La portée est par défaut définie sur 'shared'.

Paramètres du constructeur

cli:

'agent-browser' | 'browser-use' | 'browse' | 'browse-cli'

CLI utilisée par l’agent pour l’automatisation de navigateur. La CLI se connecte à Chrome via l’URL CDP.

headless?:

boolean

= true

Indique s’il faut exécuter Chrome en mode headless.

cdpUrl?:

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

URL WebSocket CDP permettant de se connecter à un navigateur existant au lieu d’en lancer un.

cdpPort?:

number

= 0 (attribution automatique)

Port du débogage à distance de Chrome. Utilisé uniquement lors du lancement de Chrome (et non lors d’une connexion via cdpUrl).

scope?:

'shared' | 'thread'

= 'thread'

Portée de l’instance de navigateur. 'thread' attribue un navigateur à chaque thread. 'shared' partage un navigateur entre tous les threads. La valeur par défaut est 'shared' lorsque cdpUrl est fourni.

viewport?:

{ width: number; height: number }

= { width: 1280, height: 720 }

Dimensions de la zone d’affichage du navigateur.

executablePath?:

string

Chemin vers un exécutable Chrome. Utilise par défaut Chromium fourni avec Playwright.

onLaunch?:

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

Rappel appelé lorsque le navigateur est prêt.

onClose?:

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

Rappel appelé avant la fermeture du navigateur.

screencast?:

ScreencastOptions

Configuration de la diffusion des images du navigateur vers Studio.

Propriétés

id:

string

Identifiant unique de cette instance de navigateur. Généré sous la forme 'browser-viewer-{timestamp}'.

name:

string

'BrowserViewer'

provider:

string

'browser-viewer'

providerType:

'cli'

Toujours 'cli'. Distingue BrowserViewer des fournisseurs basés sur SDK comme AgentBrowser.

cli:

'agent-browser' | 'browser-use' | 'browse' | 'browse-cli'

Fournisseur CLI pour lequel cette instance est configurée.

status:

BrowserStatus

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

Méthodes

Cycle de vie

launch(threadId?)

Lance Chrome. Pour la portée 'shared', lance un seul navigateur partagé. Pour la portée 'thread', lance un navigateur pour le thread spécifié.

await viewer.launch()
await viewer.launch('thread-123')

ensureReady()

S’assure que le navigateur est lancé et prêt. Pour la portée 'thread', crée si nécessaire un nouveau navigateur pour le thread actuel.

await viewer.ensureReady()

isBrowserRunning(threadId?)

Vérifie si un navigateur est en cours d’exécution. Pour la portée 'thread', vérifie le thread spécifié.

const running = viewer.isBrowserRunning()
const threadRunning = viewer.isBrowserRunning('thread-123')

Renvoie : boolean

close()

Ferme toutes les instances de navigateur et libère les ressources.

await viewer.close()

Accès CDP

getCdpUrl(threadId?)

Renvoie l’URL WebSocket CDP du thread actuel ou spécifié. Les outils CLI utilisent cette URL pour se connecter au navigateur géré.

const cdpUrl = viewer.getCdpUrl()
// => 'ws://127.0.0.1:52481/devtools/browser/abc...'

Renvoie : string | null

connectToExternalCdp(cdpUrl, threadId?)

Se connecte à un navigateur externe par URL CDP pour la diffusion d’écran. Utilisez cette méthode lorsque l’agent fournit son propre point de terminaison de navigateur (par exemple, un service de navigateur dans le cloud). BrowserViewer se connecte pour la diffusion d’écran sans gérer le cycle de vie du navigateur.

await viewer.connectToExternalCdp('wss://cloud.example.com/session', 'thread-123')

Diffusion d’écran

startScreencast(options?)

Commence à diffuser les images du navigateur. Renvoie un ScreencastStream qui émet des événements d’image. Gère automatiquement le changement d’onglet en créant de nouvelles sessions CDP lorsque les onglets changent.

const stream = await viewer.startScreencast({
  format: 'jpeg',
  quality: 80,
})

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 navigateur via CDP. Utilisé par Studio pour l’interaction en direct.

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

injectKeyboardEvent(params, threadId?)

Injecte un événement de clavier dans le navigateur via CDP. Utilisé par Studio pour l’interaction en direct.

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

CLI prises en charge

Chaque CLI doit être installée séparément. Chacune publie aussi une skill qui enseigne à l’agent ses commandes et ses workflows. Lorsqu’une commande CLI s’exécute via workspace_execute_command, Mastra la détecte et injecte automatiquement l’URL CDP avec l’indicateur approprié.

Contrairement aux fournisseurs SDK, BrowserViewer ne fournit pas d’outils d’agent. L’agent utilise à la place les commandes CLI via workspace_execute_command.

agent-browser

Valeur de configuration : 'agent-browser' · Indicateur CDP : --cdp

npm install -g agent-browser
npx skills add vercel-labs/agent-browser

browser-use

Valeur de configuration : 'browser-use' · Indicateur CDP : --cdp-url

pip install browser-use
npx skills add browser-use/browser-use --skill browser-use

browse (commande : browse)

Valeur de configuration : 'browse' · Indicateur CDP : --ws

npm install -g browse
browse skills install

Articles connexes

• Guide BrowserViewer : présentation de la configuration et de l’utilisation
• MastraBrowser : référence de l’API de la classe de base
• Présentation de Workspace : configuration de Workspace