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

# Classe AgentBrowser

La classe `AgentBrowser` fournit une automatisation déterministe du navigateur à l’aide de la bibliothèque [agent-browser](https://github.com/vercel-labs/agent-browser). Elle utilise des snapshots de l’arbre d’accessibilité et des références d’éléments (par exemple `@e5`) pour des interactions précises et reproductibles.

Utilisez `AgentBrowser` lorsque vous avez besoin d’une automatisation fiable et déterministe du navigateur. Pour des interactions en langage naturel reposant sur l’IA, consultez [`StagehandBrowser`](https://mastra.zisheng.pro/fr/reference/browser/stagehand-browser).

## 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. Use browser_snapshot to see the page structure,
then interact with elements using their refs (e.g., @e5).`,
  model: 'openai/gpt-5.6-sol',
  browser,
})
```

## Paramètres du constructeur

**headless** (`boolean`): Indique si le navigateur doit s’exécuter en mode headless (sans interface utilisateur visible). (Default: `true`)

**viewport** (`{ width: number; height: number } | 'window'`): Dimensions de la zone d’affichage du navigateur, ou 'window' pour correspondre à la fenêtre réelle plutôt qu’à une taille fixe. (Default: `{ width: 1280, height: 720 }`)

**timeout** (`number`): Délai d’expiration par défaut, en millisecondes, des opérations du navigateur. (Default: `30000`)

**cdpUrl** (`string | (() => string | Promise<string>)`): URL WebSocket CDP permettant de se connecter à un navigateur existant. Utile pour les Providers de navigateurs cloud.

**scope** (`'shared' | 'thread'`): Portée de l’instance du navigateur. 'shared' partage un navigateur entre tous les fils. 'thread' fournit à chaque fil son propre navigateur. (Default: `'thread' (ou 'shared' lorsque cdpUrl est fourni)`)

**onLaunch** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): Callback appelé une fois le navigateur prêt.

**onClose** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): Callback appelé avant la fermeture du navigateur.

**screencast** (`ScreencastOptions`): Configuration de l’envoi en streaming des images du navigateur vers Studio.

**recording** (`BrowserRecordingOptions`): Option alpha permettant d’ajouter des Tools d’enregistrement du navigateur. Fournissez outputDir pour ajouter browser\_record et browser\_record\_caption à l’ensemble de Tools. Vous pouvez aussi définir maxDurationMs, maxWidth et maxHeight comme valeurs par défaut de chaque enregistrement.

**excludeTools** (`BrowserToolName[]`): Noms des Tools à exclure de l’ensemble de Tools du navigateur. Utilisez cette option pour désactiver certains Tools avec les modèles qui ne prennent pas en charge des fonctionnalités telles que la vision.

## Tools

`AgentBrowser` fournit 16 Tools déterministes d’automatisation du navigateur. Tous les Tools qui interagissent avec des éléments utilisent les références du snapshot de l’arbre d’accessibilité.

Lorsque `recording` est configuré, `AgentBrowser` ajoute également les Tools alpha `browser_record` et `browser_record_caption`. Consultez [Enregistrement du navigateur (alpha)](https://mastra.zisheng.pro/fr/docs/browser/recording).

### Tools principaux

| Tool                 | Description                                                                                                    |
| -------------------- | -------------------------------------------------------------------------------------------------------------- |
| `browser_goto`       | Accéder à une URL                                                                                              |
| `browser_snapshot`   | Obtenir un snapshot de l’arbre d’accessibilité avec les références d’éléments                                  |
| `browser_click`      | Cliquer sur un élément à partir de sa référence                                                                |
| `browser_type`       | Saisir du texte dans un élément                                                                                |
| `browser_press`      | Appuyer sur des touches du clavier                                                                             |
| `browser_select`     | Sélectionner une option dans une liste déroulante                                                              |
| `browser_scroll`     | Faire défiler la page ou un élément                                                                            |
| `browser_screenshot` | Capturer une image au format PNG (zone d’affichage par défaut ; définir `fullPage: true` pour la page entière) |
| `browser_close`      | Fermer le navigateur                                                                                           |

### Tools étendus

| Tool               | Description                                                         |
| ------------------ | ------------------------------------------------------------------- |
| `browser_hover`    | Survoler un élément                                                 |
| `browser_back`     | Revenir en arrière dans l’historique du navigateur                  |
| `browser_dialog`   | Gérer les boîtes de dialogue du navigateur (alert, confirm, prompt) |
| `browser_wait`     | Attendre les changements d’état d’un élément                        |
| `browser_tabs`     | Gérer les onglets du navigateur (list, new, switch, close)          |
| `browser_drag`     | Glisser-déposer des éléments                                        |
| `browser_evaluate` | Exécuter du JavaScript dans la page (solution de dernier recours)   |

Pour exclure certains Tools, transmettez `excludeTools` au constructeur :

```typescript
const browser = new AgentBrowser({
  excludeTools: ['browser_screenshot'],
})
```

## Référence des Tools

### `browser_goto`

Accède à une URL.

```text
// Tool input
{
  "url": "https://example.com",
  "waitUntil": "domcontentloaded",
  "timeout": 30000
}
```

| Paramètre   | Type                                            | Description                                                        |
| ----------- | ----------------------------------------------- | ------------------------------------------------------------------ |
| `url`       | `string`                                        | URL à ouvrir                                                       |
| `waitUntil` | `"load" \| "domcontentloaded" \| "networkidle"` | Moment auquel considérer la navigation comme terminée (facultatif) |
| `timeout`   | `number`                                        | Délai d’expiration de la navigation en ms (facultatif)             |

### `browser_snapshot`

Obtient un snapshot de l’arbre d’accessibilité de la page. Renvoie des références d’éléments telles que `@e5`, à utiliser avec les autres Tools.

```text
// Tool input
{
  "interactiveOnly": true,
  "maxDepth": 10
}
```

| Paramètre         | Type      | Description                                              |
| ----------------- | --------- | -------------------------------------------------------- |
| `interactiveOnly` | `boolean` | Inclure uniquement les éléments interactifs (facultatif) |
| `maxDepth`        | `number`  | Profondeur maximale de l’arbre (facultatif)              |

**Exemple de sortie :**

```text
[document] Example Page
  [banner]
    [link @e1] Home
    [link @e2] About
  [main]
    [heading @e3] Welcome
    [textbox @e4] Search...
    [button @e5] Submit
```

### `browser_click`

Clique sur un élément à l’aide de sa référence issue du snapshot.

```text
{
  "ref": "@e5",
  "button": "left",
  "clickCount": 1,
  "modifiers": ["Control", "Shift"]
}
```

| Paramètre    | Type                            | Description                                              |
| ------------ | ------------------------------- | -------------------------------------------------------- |
| `ref`        | `string`                        | Référence de l’élément issue du snapshot (requise)       |
| `button`     | `"left" \| "right" \| "middle"` | Bouton de la souris (facultatif)                         |
| `clickCount` | `number`                        | Nombre d’activations, 2 pour un double clic (facultatif) |
| `modifiers`  | `string[]`                      | Touches de modification (facultatif)                     |

### `browser_type`

Saisit du texte dans un élément d’entrée.

```text
// Tool input
{
  "ref": "@e4",
  "text": "search query",
  "clear": true,
  "delay": 50
}
```

| Paramètre | Type      | Description                                        |
| --------- | --------- | -------------------------------------------------- |
| `ref`     | `string`  | Référence de l’élément issue du snapshot (requise) |
| `text`    | `string`  | Texte à saisir (requis)                            |
| `clear`   | `boolean` | Effacer d’abord le contenu existant (facultatif)   |
| `delay`   | `number`  | Délai entre les frappes en ms (facultatif)         |

### `browser_press`

Appuie sur des touches du clavier.

```text
// Tool input
{
  "key": "Enter",
  "modifiers": ["Control"]
}

// Key combinations
{ "key": "Control+a" }
{ "key": "Control+c" }
```

| Paramètre   | Type       | Description                                                                           |
| ----------- | ---------- | ------------------------------------------------------------------------------------- |
| `key`       | `string`   | Nom de la touche (par exemple « Enter », « Tab », « Escape », « Control+a ») (requis) |
| `modifiers` | `string[]` | Touches de modification (facultatif)                                                  |

### `browser_select`

Sélectionne une option dans une liste déroulante. Fournissez `value`, `label` ou `index`.

```text
// Tool input - by value
{
  "ref": "@e10",
  "value": "option-value"
}

// Tool input - by label
{
  "ref": "@e10",
  "label": "Option Text"
}

// Tool input - by index
{
  "ref": "@e10",
  "index": 0
}
```

### `browser_scroll`

Fait défiler la page ou un élément donné.

```text
// Tool input
{
  "direction": "down",
  "amount": 300,
  "ref": "@e15"
}
```

| Paramètre   | Type                                  | Description                                                         |
| ----------- | ------------------------------------- | ------------------------------------------------------------------- |
| `direction` | `"up" \| "down" \| "left" \| "right"` | Sens du défilement (requis)                                         |
| `amount`    | `number`                              | Nombre de pixels à faire défiler, 300 par défaut (facultatif)       |
| `ref`       | `string`                              | Élément à faire défiler ; fait défiler la page si omis (facultatif) |

### `browser_hover`

Survole un élément afin de déclencher les effets de survol.

```text
// Tool input
{
  "ref": "@e7"
}
```

### `browser_back`

Revient en arrière dans l’historique du navigateur.

```text
// Tool input (no parameters required)

```

### `browser_dialog`

Gère les boîtes de dialogue du navigateur (alert, confirm, prompt). Clique sur un élément qui déclenche une boîte de dialogue, puis la traite.

```text
// Tool input
{
  "triggerRef": "@e5",
  "action": "accept",
  "text": "response"
}
```

| Paramètre    | Type                    | Description                                         |
| ------------ | ----------------------- | --------------------------------------------------- |
| `triggerRef` | `string`                | Élément qui déclenche la boîte de dialogue (requis) |
| `action`     | `"accept" \| "dismiss"` | Traitement de la boîte de dialogue (requis)         |
| `text`       | `string`                | Texte des boîtes de dialogue prompt (facultatif)    |

### `browser_wait`

Attend qu’un élément atteigne un état donné.

```text
// Tool input
{
  "ref": "@e20",
  "state": "visible",
  "timeout": 30000
}
```

| Paramètre | Type                                                | Description                                     |
| --------- | --------------------------------------------------- | ----------------------------------------------- |
| `ref`     | `string`                                            | Référence de l’élément à attendre (facultative) |
| `state`   | `"visible" \| "hidden" \| "attached" \| "detached"` | État à attendre (facultatif)                    |
| `timeout` | `number`                                            | Temps d’attente maximal en ms (facultatif)      |

### `browser_tabs`

Gère les onglets du navigateur.

```text
// List all tabs
{ "action": "list" }

// Open new tab
{ "action": "new", "url": "https://example.com" }

// Switch to tab by index
{ "action": "switch", "index": 0 }

// Close tab by index
{ "action": "close", "index": 1 }
```

### `browser_drag`

Fait glisser un élément vers un emplacement cible.

```text
// Tool input
{
  "sourceRef": "@e10",
  "targetRef": "@e20"
}
```

| Paramètre   | Type     | Description                      |
| ----------- | -------- | -------------------------------- |
| `sourceRef` | `string` | Élément à faire glisser (requis) |
| `targetRef` | `string` | Élément cible du dépôt (requis)  |

### `browser_evaluate`

Exécute du JavaScript dans le contexte de la page. Utilisez-le comme solution de dernier recours lorsque les autres Tools ne couvrent pas votre cas d’utilisation.

```text
// Tool input
{
  "script": "document.title",
  "returnValue": true
}
```

| Paramètre     | Type      | Description                                         |
| ------------- | --------- | --------------------------------------------------- |
| `script`      | `string`  | JavaScript à exécuter (requis)                      |
| `returnValue` | `boolean` | Indique s’il faut renvoyer le résultat (facultatif) |

### `browser_screenshot`

Capture une image de la page actuelle au format PNG (zone d’affichage par défaut ; définissez `fullPage: true` pour capturer la page entière). Renvoie un contenu d’image que les modèles dotés de fonctionnalités de vision peuvent interpréter directement. Utilisez `browser_snapshot` si vous avez uniquement besoin de texte ou de données structurées.

```text
// Viewport only (default)

// Full scrollable page
{ "fullPage": true }
```

| Paramètre  | Type      | Description                                                                                                   |
| ---------- | --------- | ------------------------------------------------------------------------------------------------------------- |
| `fullPage` | `boolean` | Capturer toute la page défilable plutôt que la seule zone d’affichage (facultatif, valeur par défaut : false) |

### `browser_close`

Ferme le navigateur et libère les ressources.

```text
// Tool input (no parameters required)

```

## Fonctionnement des références

Le Tool `browser_snapshot` renvoie un arbre d’accessibilité avec des références d’éléments telles que `@e1`, `@e2`, etc. Ces références sont des identifiants stables à utiliser avec les autres Tools :

1. Appelez `browser_snapshot` pour afficher la structure de la page
2. Trouvez l’élément avec lequel vous souhaitez interagir
3. Utilisez sa référence avec des Tools d’interaction tels que `browser_type` ou `browser_scroll`.

```text
// 1. Get snapshot
// Returns: [textbox @e4] Search... [link @e5] Home

// 2. Type in the search box
{ "tool": "browser_type", "input": { "ref": "@e4", "text": "mastra" } }

// 3. Navigate to home
{ "tool": "browser_goto", "input": { "url": "https://example.com" } }
```

## Ressources associées

- [MastraBrowser](https://mastra.zisheng.pro/fr/reference/browser/mastra-browser) : référence de la classe de base
- [StagehandBrowser](https://mastra.zisheng.pro/fr/reference/browser/stagehand-browser) : alternative reposant sur l’IA
- [Vue d’ensemble de Browser](https://mastra.zisheng.pro/fr/docs/browser/overview) : guide conceptuel
- [Guide agent-browser](https://mastra.zisheng.pro/fr/docs/browser/agent-browser) : guide d’utilisation