> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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`](https://mastra.zisheng.pro/fr/reference/browser/agent-browser) ou [`StagehandBrowser`](https://mastra.zisheng.pro/fr/reference/browser/stagehand-browser).

## Exemple d’utilisation

```typescript
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

```typescript
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`): Indique s’il faut exécuter Chrome en mode headless. (Default: `true`)

**cdpUrl** (`string | (() => string | Promise<string>)`): URL WebSocket CDP permettant de se connecter à un navigateur existant au lieu d’en lancer un.

**cdpPort** (`number`): Port du débogage à distance de Chrome. Utilisé uniquement lors du lancement de Chrome (et non lors d’une connexion via cdpUrl). (Default: `0 (attribution automatique)`)

**scope** (`'shared' | '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. (Default: `'thread'`)

**viewport** (`{ width: number; height: number }`): Dimensions de la zone d’affichage du navigateur. (Default: `{ width: 1280, height: 720 }`)

**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é.

```typescript
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.

```typescript
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é.

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

Renvoie : `boolean`

#### `close()`

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

```typescript
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é.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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](https://mastra.zisheng.pro/fr/docs/workspace/skills) 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`](https://www.npmjs.com/package/agent-browser)

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

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

### [`browser-use`](https://pypi.org/project/browser-use/)

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

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

### [`browse`](https://www.npmjs.com/package/browse) (commande : `browse`)

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

```bash
npm install -g browse
browse skills install
```

## Articles connexes

- [Guide BrowserViewer](https://mastra.zisheng.pro/fr/docs/browser/browser-viewer) : présentation de la configuration et de l’utilisation
- [MastraBrowser](https://mastra.zisheng.pro/fr/reference/browser/mastra-browser) : référence de l’API de la classe de base
- [Présentation de Workspace](https://mastra.zisheng.pro/fr/docs/workspace/overview) : configuration de Workspace