Classe AgentBrowser

La classe AgentBrowser fournit une automatisation déterministe du navigateur à l’aide de la bibliothèque 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.

Exemple d’utilisation

src/mastra/agents/index.ts

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

= true

Indique si le navigateur doit s’exécuter en mode headless (sans interface utilisateur visible).

viewport?:

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

= { width: 1280, height: 720 }

Dimensions de la zone d’affichage du navigateur, ou 'window' pour correspondre à la fenêtre réelle plutôt qu’à une taille fixe.

timeout?:

number

= 30000

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

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'

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

Portée de l’instance du navigateur. 'shared' partage un navigateur entre tous les fils. 'thread' fournit à chaque fil son propre navigateur.

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

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 :

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

Référence des Tools

browser_goto

Accède à une URL.

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

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

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

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

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

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

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

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

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

browser_back

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

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

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

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

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

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

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

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

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

// 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 : référence de la classe de base
• StagehandBrowser : alternative reposant sur l’IA
• Vue d’ensemble de Browser : guide conceptuel
• Guide agent-browser : guide d’utilisation