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

# Stagehand

Le package `@mastra/stagehand` permet d'automatiser le navigateur au moyen du [SDK Stagehand](https://docs.browserbase.com/stagehand/introduction) de Browserbase. Stagehand utilise l'IA pour comprendre le contexte de la page et localiser les éléments, ce qui permet de les décrire en langage naturel plutôt qu'avec des sélecteurs explicites.

## Quand utiliser Stagehand

Utilisez Stagehand lorsque vous avez besoin :

- de cibler des éléments en langage naturel (« sélectionne le bouton de connexion ») ;
- d'extraire des données de pages grâce à l'IA ;
- d'une intégration cloud native à Browserbase ;
- d'une interface d'outils simplifiée pour les actions courantes.

## Démarrage rapide

Installez le package :

**npm**:

```bash
npm install @mastra/stagehand
```

**pnpm**:

```bash
pnpm add @mastra/stagehand
```

**Yarn**:

```bash
yarn add @mastra/stagehand
```

**Bun**:

```bash
bun add @mastra/stagehand
```

Créez une instance de navigateur et affectez-la à un Agent :

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

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

export const stagehandAgent = new Agent({
  id: 'stagehand-agent',
  name: 'Stagehand Agent',
  model: 'openai/gpt-5.6-sol',
  browser,
  instructions: `You are a web automation assistant.

Use stagehand tools to interact with pages:
- stagehand_navigate to go to URLs
- stagehand_act to perform actions described in natural language
- stagehand_extract to get structured data from the page
- stagehand_observe to find available actions on the page
- stagehand_screenshot to visually inspect the page`,
})
```

## Actions en langage naturel

Lorsque l'Agent utilise l'outil `stagehand_act`, celui-ci accepte des descriptions d'actions en langage naturel :

- « Appuie sur le bouton de connexion »
- « Saisis `'[user@example.com](mailto:user@example.com)'` dans le champ d'adresse e-mail »
- « Sélectionne les États-Unis dans la liste déroulante des pays »

L'IA de Stagehand interprète l'action et trouve l'élément approprié dans la page.

## Extraction de données

Lorsque l'Agent utilise l'outil `stagehand_extract`, il peut extraire des données structurées des pages.

Exemple d'instruction : « Extrais le nom du produit, son prix et sa disponibilité »

L'outil renvoie des données structurées d'après le contenu de la page :

```json
{
  "name": "Widget Pro",
  "price": "$29.99",
  "availability": "In Stock"
}
```

## Observation des actions

Lorsque l'Agent utilise l'outil `stagehand_observe`, celui-ci analyse la page actuelle et renvoie les actions possibles.

Exemple d'instruction : « Quelles actions puis-je effectuer dans ce formulaire de connexion ? »

L'outil renvoie une liste d'actions disponibles :

```json
[
  { "action": "Press 'Sign In' button", "element": "button" },
  { "action": "Type in 'Email' field", "element": "input" },
  { "action": "Open 'Forgot Password' link", "element": "a" }
]
```

## Captures d'écran

Lorsque l'Agent utilise l'outil `stagehand_screenshot`, celui-ci capture une image PNG de la page actuelle et la renvoie sous forme de contenu image que les modèles dotés de capacités visuelles peuvent interpréter directement.

Utilisez les captures d'écran lorsque vous devez inspecter visuellement la page, par exemple pour évaluer les images, la mise en page ou les couleurs. Pour le texte ou les données structurées, utilisez plutôt `stagehand_extract` ou `stagehand_observe`.

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

Pour désactiver l'outil de capture d'écran avec les modèles qui ne prennent pas en charge la vision, utilisez `excludeTools` :

```typescript
const browser = new StagehandBrowser({
  headless: false,
  model: 'openai/gpt-5.6-sol',
  excludeTools: ['stagehand_screenshot'],
})
```

## Browserbase

Stagehand dispose d'une intégration native à Browserbase pour l'infrastructure de navigateurs dans le cloud :

```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',
})
```

Consultez la [référence de StagehandBrowser](https://mastra.zisheng.pro/fr/reference/browser/stagehand-browser) pour découvrir toutes les options de configuration.

## Enregistrement

Stagehand peut activer les outils expérimentaux d'enregistrement du navigateur :

```typescript
const browser = new StagehandBrowser({
  headless: false,
  model: 'openai/gpt-5.6-sol',
  recording: {
    outputDir: './browser-recordings',
  },
})
```

Cette option ajoute `browser_record` et `browser_record_caption` à l'ensemble d'outils de l'Agent. Consultez l'[enregistrement du navigateur (alpha)](https://mastra.zisheng.pro/fr/docs/browser/recording) pour plus de détails.

## Voir aussi

- [Présentation du navigateur](https://mastra.zisheng.pro/fr/docs/browser/overview)
- [AgentBrowser](https://mastra.zisheng.pro/fr/docs/browser/agent-browser)
- [Enregistrement du navigateur (alpha)](https://mastra.zisheng.pro/fr/docs/browser/recording)
- [Référence de StagehandBrowser](https://mastra.zisheng.pro/fr/reference/browser/stagehand-browser)