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

# Classe StagehandBrowser

La classe `StagehandBrowser` fournit une automatisation de navigateur reposant sur l’IA à l’aide de [Stagehand](https://github.com/browserbase/stagehand). Pour les interactions, elle utilise des instructions en langage naturel au lieu de références d’éléments.

Utilisez `StagehandBrowser` lorsque vous souhaitez que l’IA interprète et exécute des actions dans le navigateur à partir du langage naturel. Pour une automatisation déterministe reposant sur des références d’éléments, consultez [`AgentBrowser`](https://mastra.zisheng.pro/fr/reference/browser/agent-browser).

## Exemple d’utilisation

```typescript
import { Agent } from '@mastra/core/agent'
import { StagehandBrowser } from '@mastra/stagehand'

const browser = new StagehandBrowser({
  headless: true,
  model: 'openai/gpt-5.6-sol',
  selfHeal: true,
})

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  instructions: `You can browse the web using natural language.
Use stagehand_act to perform actions like "click the login button".
Use stagehand_extract to get data from pages.`,
  model: 'openai/gpt-5.6-sol',
  browser,
})
```

## Paramètres du constructeur

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

**viewport** (`{ width: number; height: number } | 'window'`): Dimensions de la zone d’affichage du navigateur. 'window' correspond à la fenêtre réelle du navigateur et s’applique uniquement lors d’une connexion via CDP ; un navigateur lancé localement utilise la taille par défaut. (Default: `{ width: 1280, height: 720 }`)

**env** (`'LOCAL' | 'BROWSERBASE'`): Environnement dans lequel exécuter le navigateur. Utilisez 'BROWSERBASE' pour une exécution dans le cloud. (Default: `'LOCAL'`)

**apiKey** (`string`): Clé d’API Browserbase. Requise lorsque env vaut 'BROWSERBASE'.

**projectId** (`string`): ID du projet Browserbase. Requis lorsque env vaut 'BROWSERBASE'.

**model** (`string | ModelConfiguration`): Configuration du modèle pour les opérations d’IA. Peut être une chaîne telle que 'openai/gpt-5.5' ou un objet contenant modelName, apiKey et baseURL. (Default: `'openai/gpt-5.5'`)

**selfHeal** (`boolean`): Active les sélecteurs autoréparateurs. Lorsque cette option est activée, Stagehand utilise l’IA pour trouver les éléments même si les sélecteurs initiaux échouent. (Default: `true`)

**domSettleTimeout** (`number`): Délai d’expiration, en millisecondes, pour la stabilisation du DOM après les actions. (Default: `5000`)

**verbose** (`0 | 1 | 2`): Niveau de verbosité des logs. 0 = silencieux, 1 = erreurs uniquement, 2 = détaillé. (Default: `1`)

**systemPrompt** (`string`): Prompt système personnalisé pour les opérations d’IA.

**cdpUrl** (`string | (() => string | Promise<string>)`): URL WebSocket CDP ou point de terminaison HTTP permettant de se connecter à un navigateur existant. Les points de terminaison HTTP sont résolus en WebSocket en interne.

**scope** (`'shared' | 'thread'`): Portée de l’instance du navigateur entre les fils. (Default: `'thread' (ou 'shared' lorsque cdpUrl est fourni)`)

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

**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 également définir maxDurationMs, maxWidth et maxHeight comme valeurs par défaut pour chaque enregistrement.

**excludeTools** (`StagehandToolName[]`): 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 certaines fonctionnalités, telles que la vision.

## Tools

`StagehandBrowser` fournit 7 Tools d’automatisation de navigateur reposant sur l’IA.

Lorsque `recording` est configuré, `StagehandBrowser` 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                                                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `stagehand_act`        | Effectuer des actions à l’aide d’instructions en langage naturel                                                         |
| `stagehand_extract`    | Extraire des données structurées des pages                                                                               |
| `stagehand_observe`    | Découvrir les éléments utiles d’une page                                                                                 |
| `stagehand_navigate`   | Accéder à une URL                                                                                                        |
| `stagehand_tabs`       | Gérer les onglets du navigateur                                                                                          |
| `stagehand_screenshot` | Capturer une capture d’écran au format PNG (zone d’affichage par défaut ; définir `fullPage: true` pour la page entière) |
| `stagehand_close`      | Fermer le navigateur                                                                                                     |

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

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

## Référence des Tools

### `stagehand_act`

Effectue une action à l’aide d’instructions en langage naturel. L’IA interprète votre instruction et exécute l’action appropriée dans le navigateur.

```text
// Tool input
{
  "instruction": "click the login button",
  "variables": { "username": "john" },
  "useVision": true,
  "timeout": 30000
}

// With variable substitution
{
  "instruction": "type %email% into the email field",
  "variables": { "email": "user@example.com" }
}
```

| Paramètre     | Type                     | Description                                             |
| ------------- | ------------------------ | ------------------------------------------------------- |
| `instruction` | `string`                 | Instruction en langage naturel (requise)                |
| `variables`   | `Record<string, string>` | Variables de substitution %variableName% (facultatives) |
| `useVision`   | `boolean`                | Activer les fonctionnalités de vision (facultatif)      |
| `timeout`     | `number`                 | Délai d’expiration en ms (facultatif)                   |

**Renvoie :**

```typescript
interface ActResult {
  success: boolean
  message?: string
  action?: string
  url?: string
}
```

### `stagehand_extract`

Extrait des données structurées d’une page à l’aide d’instructions en langage naturel.

```text
// Basic extraction
{
  "instruction": "extract all product names and prices"
}

// With schema for structured output
{
  "instruction": "extract the product information",
  "schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "price": { "type": "number" },
      "inStock": { "type": "boolean" }
    }
  }
}
```

**Renvoie :**

```typescript
interface ExtractResult<T = unknown> {
  success: boolean
  data?: T
  hint?: string
  error?: string
  url?: string
}
```

### `stagehand_observe`

Découvre les éléments utiles d’une page. Renvoie une liste d’éléments accompagnés de leurs sélecteurs et descriptions.

```text
// Find specific elements
{
  "instruction": "find all buttons related to checkout"
}

// Find all interactive elements
{
  "onlyVisible": true
}
```

| Paramètre     | Type      | Description                                                                    |
| ------------- | --------- | ------------------------------------------------------------------------------ |
| `instruction` | `string`  | Instruction en langage naturel (facultative ; omettez-la pour tout rechercher) |
| `onlyVisible` | `boolean` | Inclure uniquement les éléments visibles (facultatif)                          |
| `timeout`     | `number`  | Délai d’expiration en ms (facultatif)                                          |

**Renvoie :**

```typescript
interface ObserveResult {
  success: boolean
  actions: StagehandAction[]
  url?: string
}

interface StagehandAction {
  selector: string
  description: string
  method?: string
  arguments?: string[]
}
```

### `stagehand_navigate`

Accède à une URL.

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

| Paramètre   | Type                                            | Description                                                        |
| ----------- | ----------------------------------------------- | ------------------------------------------------------------------ |
| `url`       | `string`                                        | URL à ouvrir (requise)                                             |
| `waitUntil` | `"load" \| "domcontentloaded" \| "networkidle"` | Moment auquel considérer la navigation comme terminée (facultatif) |

### `stagehand_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 (or current if omitted)
{ "action": "close", "index": 1 }
```

### `stagehand_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 `stagehand_observe` ou `stagehand_extract` 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) |

### `stagehand_close`

Ferme le navigateur et libère les ressources.

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

```

## Utiliser Browserbase

Exécutez Stagehand dans le cloud à l’aide de Browserbase :

```typescript
const browser = new StagehandBrowser({
  env: 'BROWSERBASE',
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
  model: 'openai/gpt-5.6-sol',
})
```

## Configuration du modèle

Configurez le modèle d’IA pour les opérations Stagehand :

```typescript
// String format: "provider/model"
const browser = new StagehandBrowser({
  model: 'openai/gpt-5.6-sol',
})

// Object format for custom configuration
const browser = new StagehandBrowser({
  model: {
    modelName: 'gpt-5.4',
    apiKey: process.env.OPENAI_API_KEY,
    baseURL: 'https://api.openai.com/v1',
  },
})
```

## AgentBrowser et StagehandBrowser

| Aspect                | AgentBrowser                      | StagehandBrowser                 |
| --------------------- | --------------------------------- | -------------------------------- |
| **Approche**          | Références déterministes (`@e5`)  | Langage naturel                  |
| **Précision**         | Ciblage exact des éléments        | Interprétation par l’IA          |
| **Flexibilité**       | Nécessite d’abord un snapshot     | Instructions directes            |
| **Cas d’utilisation** | Automatisation reproductible      | Automatisation adaptative        |
| **Vitesse**           | Plus rapide (sans inférence d’IA) | Plus lente (avec inférence d’IA) |

Choisissez `AgentBrowser` pour une automatisation précise et reproductible. Choisissez `StagehandBrowser` pour des interactions flexibles en langage naturel.

## Ressources associées

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