Classe StagehandBrowser

La classe StagehandBrowser fournit une automatisation de navigateur reposant sur l’IA à l’aide de 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.

Exemple d’utilisation

src/mastra/agents/index.ts

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

= true

Indique si le navigateur doit s’exécuter en mode headless.

viewport?:

{ width: number; height: number } | 'window'

= { width: 1280, height: 720 }

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.

env?:

'LOCAL' | 'BROWSERBASE'

= 'LOCAL'

Environnement dans lequel exécuter le navigateur. Utilisez 'BROWSERBASE' pour une exécution dans le cloud.

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

= 'openai/gpt-5.5'

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.

selfHeal?:

boolean

= true

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.

domSettleTimeout?:

number

= 5000

Délai d’expiration, en millisecondes, pour la stabilisation du DOM après les actions.

verbose?:

0 | 1 | 2

= 1

Niveau de verbosité des logs. 0 = silencieux, 1 = erreurs uniquement, 2 = détaillé.

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'

= 'thread' (ou 'shared' lorsque cdpUrl est fourni)

Portée de l’instance du navigateur entre les fils.

timeout?:

number

= 30000

Délai d’expiration par défaut, en millisecondes, des opérations Stagehand.

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

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 :

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.

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

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.

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

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.

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

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

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

stagehand_navigate

Accède à une URL.

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

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

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

// Tool input (no parameters required)
{}

Utiliser Browserbase

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

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 :

// 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 : référence de la classe de base
• AgentBrowser : alternative déterministe
• Vue d’ensemble de Browser : guide conceptuel
• Guide Stagehand : guide d’utilisation