Enregistrement du navigateur (bêta)

Ajouté dans : @mastra/core@1.43.0

L’enregistrement du navigateur ajoute deux Tools facultatifs qui permettent à un Agent de sauvegarder une session sous forme de vidéo AVI Motion-JPEG. L’Agent peut également ajouter de courtes légendes pendant son travail.

beta

Cette fonctionnalité est en bêta. Des changements incompatibles peuvent survenir sans hausse de version majeure tant que l’API n’est pas stable.

Quand utiliser l’enregistrement du navigateur

Utilisez l’enregistrement du navigateur lorsque vous devez :

• Examiner ce qu’un Agent a effectué dans un navigateur
• Partager une courte exécution d’automatisation du navigateur avec un collègue
• Déboguer des actions manquées, des chargements de page lents ou une navigation inattendue
• Ajouter de courtes légendes qui expliquent chaque étape importante

Les Tools d’enregistrement sont désactivés par défaut. Activez-les uniquement pour les Agents qui doivent écrire des fichiers vidéo.

Activer l’enregistrement

Transmettez un objet recording à AgentBrowser ou StagehandBrowser. Le seul champ obligatoire est outputDir. Vous pouvez également définir maxDurationMs, maxWidth et maxHeight comme valeurs par défaut de chaque enregistrement lancé par ce navigateur.

L’exemple suivant active l’enregistrement pour AgentBrowser :

src/mastra/browsers/agent-browser.ts

import { join } from 'node:path'
import { AgentBrowser } from '@mastra/agent-browser'

export const browser = new AgentBrowser({
  headless: false,
  recording: {
    outputDir: join(process.cwd(), 'browser-recordings'),
    maxDurationMs: 60_000,
    maxWidth: 1280,
    maxHeight: 720,
  },
})

La même option fonctionne avec StagehandBrowser :

src/mastra/browsers/stagehand-browser.ts

import { join } from 'node:path'
import { StagehandBrowser } from '@mastra/stagehand'

export const browser = new StagehandBrowser({
  headless: false,
  recording: {
    outputDir: join(process.cwd(), 'browser-recordings'),
    maxDurationMs: 60_000,
    maxWidth: 1280,
    maxHeight: 720,
  },
})

L’Agent peut remplacer ces valeurs par défaut pour chaque enregistrement en transmettant maxDurationMs, maxWidth ou maxHeight au Tool browser_record lors du démarrage.

Tools d’enregistrement

L’activation de l’enregistrement ajoute les Tools suivants :

Tool	Description
browser_record	Démarre, arrête ou vérifie l’état d’un enregistrement.
browser_record_caption	Ajoute une courte légende au moment actuel de l’enregistrement.

browser_record accepte un champ action :

• start : démarre l’enregistrement de la session actuelle du navigateur.
• status : vérifie si un enregistrement est actif.
• stop : arrête l’enregistrement et écrit le fichier .avi.

L’option outputPath de browser_record doit être un chemin absolu situé dans le répertoire recording.outputDir configuré. Si vous l’omettez, Mastra crée un fichier dans outputDir.

Exemple d’instructions pour l’Agent

Indiquez à l’Agent quand enregistrer et quand ajouter des légendes :

src/mastra/agents/browser-agent.ts

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

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  model: 'openai/gpt-5.6-sol',
  browser,
  instructions: `Use browser tools to complete the requested task.

When the user asks for a recording:
1. Call browser_record with action="start" before browser work begins.
2. After each major action, call browser_record_caption with a caption of about six words.
3. Call browser_record with action="stop" as soon as the task is complete.
4. Return the saved video path to the user.`,
})

Format de sortie et limites

Les enregistrements sont sauvegardés sous forme de fichiers AVI Motion-JPEG. Ce format est encodé en JavaScript et ne nécessite ni ffmpeg ni dépendances natives.

Limites par défaut :

• Durée maximale : 30 secondes
• Limite stricte de durée : 120 secondes
• Taille maximale des images : 1 024 × 720
• Légendes : 80 caractères chacune
• Un enregistrement actif par processus

Privilégiez des enregistrements courts. Les longues sessions de navigateur produisent des fichiers plus volumineux et sont plus difficiles à examiner.

Étapes suivantes

• AgentBrowser
• Stagehand
• Présentation du navigateur