Présentation du navigateur

La prise en charge du navigateur permet aux Agents de parcourir des sites web, d’interagir avec les éléments des pages, de remplir des formulaires et d’extraire des données. Mastra fournit ces fonctionnalités par l’intermédiaire de Providers SDK qui encapsulent des bibliothèques d’automatisation du navigateur, ainsi que d’un Provider CLI pour les Agents qui pilotent les navigateurs avec des Tools en ligne de commande.

Mastra prend en charge trois Providers SDK et un Provider CLI :

• AgentBrowser : Provider fondé sur Playwright qui cible les éléments en privilégiant l’accessibilité. Idéal pour l’automatisation générale du web et le scraping.
• Stagehand : Provider Browserbase doté d’une détection des éléments assistée par l’IA. Idéal pour les interactions complexes qui bénéficient de sélecteurs en langage naturel.
• FirecrawlBrowser : Provider Firecrawl Browser Sandbox qui exécute les Tools AgentBrowser sur des sessions de navigateur hébergées. Idéal pour automatiser des sessions hébergées sans gérer d’infrastructure locale de navigateur.
• BrowserViewer : Provider CLI qui lance Chrome et injecte des URL CDP dans des Tools CLI tels qu’agent-browser, browser-use et browse. Idéal pour les Agents de Workspace qui pilotent des navigateurs au moyen de commandes shell.
• Enregistrement du navigateur (alpha) : couche de Tools facultative qui enregistre les sessions sous forme de vidéos AVI Motion-JPEG avec des légendes facultatives.

Quand utiliser le navigateur

Utilisez le navigateur lorsque votre Agent doit :

• Parcourir des sites web et interagir avec les éléments des pages
• Remplir des formulaires et envoyer des données
• Extraire des données structurées depuis des pages web
• Automatiser des Workflows web à plusieurs étapes
• Effectuer des actions nécessitant un véritable navigateur (rendu JavaScript, flux d’authentification)

Fonctionnement

Lorsque vous attribuez un navigateur à un Agent, Mastra ajoute les Tools du Provider à l’ensemble de Tools de l’Agent. Celui-ci les utilise pour contrôler le navigateur : accéder à des URL, sélectionner des éléments, saisir du texte et lire le contenu des pages.

Chaque Provider propose un ensemble de Tools différent, optimisé pour son approche.

Démarrage rapide

Installez le Provider de votre choix. Cet exemple utilise AgentBrowser.

npm

npm install @mastra/agent-browser

pnpm

pnpm add @mastra/agent-browser

Yarn

yarn add @mastra/agent-browser

Bun

bun add @mastra/agent-browser

Créez une instance de navigateur :

src/mastra/browsers.ts

import { AgentBrowser } from '@mastra/agent-browser'

export const browser = new AgentBrowser({
  headless: false,
})

Attribuez le navigateur à un Agent :

src/mastra/agents/web-agent.ts

import { Agent } from '@mastra/core/agent'
import { browser } from '../browsers'

export const webAgent = new Agent({
  id: 'web-agent',
  name: 'Web Agent',
  description: 'A web automation assistant that can navigate websites and complete tasks.',
  model: 'openai/gpt-5.6-sol',
  browser,
  instructions:
    'You are a web automation assistant. Use browser tools to navigate websites and complete tasks.',
})

L’Agent reçoit automatiquement tous les Tools de navigateur du Provider.

Providers cloud

Tous les Providers SDK peuvent se connecter à des services de navigateur cloud au lieu de lancer un navigateur local.

Firecrawl Browser Sandbox (FirecrawlBrowser native)

FirecrawlBrowser provisionne des sessions hébergées via l’API Firecrawl :

import { FirecrawlBrowser } from '@mastra/browser-firecrawl'

const browser = new FirecrawlBrowser({
  apiKey: process.env.FIRECRAWL_API_KEY,
})

Browserbase (Stagehand native)

Stagehand intègre nativement Browserbase :

import { StagehandBrowser } from '@mastra/stagehand'

const browser = new StagehandBrowser({
  env: 'BROWSERBASE',
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
})

URL CDP (tout Provider)

Connectez-vous à tout navigateur qui expose un point de terminaison Chrome DevTools Protocol (CDP) :

import { AgentBrowser } from '@mastra/agent-browser'

const browser = new AgentBrowser({
  cdpUrl: process.env.BROWSER_CDP_URL,
  headless: true,
})

Cette méthode fonctionne avec tout service de navigateur compatible avec CDP.

Screencast

Les Providers de navigateur diffusent un flux vidéo en direct dans l’interface Mastra Studio. Vous pouvez ainsi observer en temps réel les interactions de l’Agent avec les pages.

La diffusion d’écran nécessite la prise en charge de WebSocket. Installez les packages suivants dans votre projet :

npm

npm install ws @hono/node-ws

pnpm

pnpm add ws @hono/node-ws

Yarn

yarn add ws @hono/node-ws

Bun

bun add ws @hono/node-ws

remarque

Ces packages ne sont pas inclus par défaut, car ils sont incompatibles avec les environnements serverless tels que Cloudflare Workers. S’ils ne sont pas installés, la diffusion d’écran est désactivée, mais toutes les autres fonctionnalités du navigateur continuent de fonctionner normalement.

La diffusion d’écran est activée par défaut et peut être configurée :

const browser = new AgentBrowser({
  screencast: {
    enabled: true,
    format: 'jpeg',
    quality: 80,
    maxWidth: 1280,
    maxHeight: 720,
  },
})

Étapes suivantes

• AgentBrowser
• Stagehand
• Firecrawl
• Enregistrement du navigateur (alpha)
• BrowserViewer
• Référence de MastraBrowser
• 📹 Atelier sur les fonctionnalités de navigateur de Mastra