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

# 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`](https://mastra.zisheng.pro/fr/reference/browser/agent-browser) : automatisation déterministe du Browser au moyen de références
- [`StagehandBrowser`](https://mastra.zisheng.pro/fr/reference/browser/stagehand-browser) : automatisation du Browser reposant sur l'IA et le langage naturel
- [`BrowserViewer`](https://mastra.zisheng.pro/fr/reference/browser/browser-viewer) : automatisation du Browser fondée sur la CLI avec injection d'une URL CDP

## Exemple d'utilisation

```typescript
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`): Indique si le Browser doit être exécuté en mode headless (sans interface utilisateur visible). (Default: `true`)

**viewport** (`{ width: number; height: number } | 'window'`): 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. (Default: `{ width: 1280, height: 720 }`)

**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'`): 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). (Default: `'thread' (ou 'shared' lorsque cdpUrl est fourni)`)

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

**screencast.format** (`'jpeg' | 'png'`): Format des images des frames du screencast.

**screencast.quality** (`number`): Qualité de l'image (1 à 100). S'applique uniquement au format JPEG.

**screencast.maxWidth** (`number`): Largeur maximale des frames du screencast.

**screencast.maxHeight** (`number`): Hauteur maximale des frames du screencast.

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

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

```typescript
await browser.close()
```

#### `isBrowserRunning()`

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

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

```typescript
browser.setCurrentThread('thread-123')
```

#### `getCurrentThread()`

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

```typescript
const threadId = browser.getCurrentThread()
```

**Renvoie :** `string`

#### `hasThreadSession(threadId)`

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

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

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

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

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

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

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

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

**Renvoie :** `Promise<BrowserState>`

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

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

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

```typescript
// 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](https://mastra.zisheng.pro/fr/reference/browser/agent-browser) : automatisation déterministe du Browser
- [StagehandBrowser](https://mastra.zisheng.pro/fr/reference/browser/stagehand-browser) : automatisation du Browser reposant sur l'IA
- [Présentation de Browser](https://mastra.zisheng.pro/fr/docs/browser/overview) : guide conceptuel de l'automatisation de Browser