Stagehand

Le package @mastra/stagehand permet d'automatiser le navigateur au moyen du SDK Stagehand 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

npm install @mastra/stagehand

pnpm

pnpm add @mastra/stagehand

Yarn

yarn add @mastra/stagehand

Bun

bun add @mastra/stagehand

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

src/mastra/agents/stagehand-agent.ts

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 :

{
  "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 :

[
  { "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.

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 :

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 :

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 pour découvrir toutes les options de configuration.

Enregistrement

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

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) pour plus de détails.

Voir aussi

• Présentation du navigateur
• AgentBrowser
• Enregistrement du navigateur (alpha)
• Référence de StagehandBrowser