Automatisation de navigateur avec agent-browser
Le CLI utilise Chrome/Chromium directement via CDP. Installez-le via npm i -g agent-browser, brew install agent-browser, ou cargo install agent-browser. Exécutez agent-browser install pour télécharger Chrome.
Flux de travail principal
Chaque automatisation de navigateur suit ce modèle :
- Naviguer :
agent-browser open <url> - Instantané :
agent-browser snapshot -i(obtenir des références d'éléments comme@e1,@e2) - Interagir : Utiliser les références pour cliquer, remplir, sélectionner
- Nouvel instantané : Après une navigation ou des modifications du DOM, obtenir des références fraîches
agent-browser open https://exemple.com/formulaire
agent-browser snapshot -i
# Sortie : @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Envoyer"
agent-browser fill @e1 "[email protected]"
agent-browser fill @e2 "motdepasse123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i # Vérifier le résultat
Enchaînement de commandes
Les commandes peuvent être enchaînées avec && dans un seul appel shell. Le navigateur persiste entre les commandes via un démon en arrière-plan, donc l'enchaînement est sûr et plus efficace que des appels séparés.
# Enchaîner ouvrir + attendre + instantané en un seul appel
agent-browser open https://exemple.com && agent-browser wait --load networkidle && agent-browser snapshot -i
# Enchaîner plusieurs interactions
agent-browser fill @e1 "[email protected]" && agent-browser fill @e2 "motdepasse123" && agent-browser click @e3
# Naviguer et capturer
agent-browser open https://exemple.com && agent-browser wait --load networkidle && agent-browser screenshot page.png
Quand enchaîner : Utilisez && lorsque vous n'avez pas besoin de lire la sortie d'une commande intermédiaire avant de continuer (par exemple, ouvrir + attendre + capture d'écran). Exécutez les commandes séparément lorsque vous devez d'abord analyser la sortie (par exemple, instantané pour découvrir les références, puis interagir en utilisant ces références).
Gestion de l'authentification
Lors de l'automatisation d'un site nécessitant une connexion, choisissez l'approche appropriée :
Option 1 : Importer l'auth depuis le navigateur de l'utilisateur (plus rapide pour des tâches ponctuelles)
# Se connecter au Chrome en cours d'exécution de l'utilisateur (il est déjà connecté)
agent-browser --auto-connect state save ./auth.json
# Utiliser cet état d'authentification
agent-browser --state ./auth.json open https://app.exemple.com/tableau-de-bord
Les fichiers d'état contiennent les jetons de session en texte clair -- ajoutez-les à .gitignore et supprimez-les lorsqu'ils ne sont plus nécessaires. Définissez AGENT_BROWSER_ENCRYPTION_KEY pour le chiffrement au repos.
Option 2 : Profil persistant (le plus simple pour des tâches récurrentes)
# Première exécution : connexion manuelle ou via automatisation
agent-browser --profile ~/.monapp open https://app.exemple.com/connexion
# ... remplir les identifiants, soumettre ...
# Toutes les exécutions suivantes : déjà authentifié
agent-browser --profile ~/.monapp open https://app.exemple.com/tableau-de-bord
Option 3 : Nom de session (sauvegarde/restauration automatique des cookies + localStorage)
agent-browser --session-name monapp open https://app.exemple.com/connexion
# ... flux de connexion ...
agent-browser close # État sauvegardé automatiquement
# Prochaine fois : état restauré automatiquement
agent-browser --session-name monapp open https://app.exemple.com/tableau-de-bord
Option 4 : Coffre-fort d'authentification (identifiants stockés chiffrés, connexion par nom)
echo "$MOTDEPASSE" | agent-browser auth save monapp --url https://app.exemple.com/connexion --nom-utilisateur utilisateur --password-stdin
agent-browser auth login monapp
Option 5 : Fichier d'état (sauvegarde/chargement manuel)
# Après s'être connecté :
agent-browser state save ./auth.json
# Dans une session future :
agent-browser state load ./auth.json
agent-browser open https://app.exemple.com/tableau-de-bord
Voir references/authentication.md pour les modèles OAuth, 2FA, auth basée sur les cookies et renouvellement de jetons.
Commandes essentielles
# Navigation
agent-browser open <url> # Naviguer (alias : goto, navigate)
agent-browser close # Fermer le navigateur
# Instantané
agent-browser snapshot -i # Éléments interactifs avec références (recommandé)
agent-browser snapshot -i -C # Inclure les éléments interactifs au curseur (divs avec onclick, cursor:pointer)
agent-browser snapshot -s "#sélecteur" # Limiter au sélecteur CSS
# Interaction (utiliser les @refs de l'instantané)
agent-browser click @e1 # Cliquer sur un élément
agent-browser click @e1 --new-tab # Cliquer et ouvrir dans un nouvel onglet
agent-browser fill @e2 "texte" # Effacer et taper du texte
agent-browser type @e2 "texte" # Taper sans effacer
agent-browser select @e1 "option" # Sélectionner une option de liste déroulante
agent-browser check @e1 # Cocher une case
agent-browser press Entrée # Appuyer sur une touche
agent-browser keyboard type "texte" # Taper au focus actuel (sans sélecteur)
agent-browser keyboard inserttext "texte" # Insérer sans événements de touche
agent-browser scroll down 500 # Faire défiler la page
agent-browser scroll down 500 --selector "div.contenu" # Faire défiler dans un conteneur spécifique
# Obtenir des informations
agent-browser get text @e1 # Obtenir le texte d'un élément
agent-browser get url # Obtenir l'URL actuelle
agent-browser get title # Obtenir le titre de la page
agent-browser get cdp-url # Obtenir l'URL WebSocket CDP
# Attendre
agent-browser wait @e1 # Attendre un élément
agent-browser wait --load networkidle # Attendre que le réseau soit inactif
agent-browser wait --url "**/page" # Attendre un motif d'URL
agent-browser wait 2000 # Attendre en millisecondes
agent-browser wait --text "Bienvenue" # Attendre que le texte apparaisse (correspondance de sous-chaîne)
agent-browser wait --fn "!document.body.innerText.includes('Chargement...')" # Attendre la disparition du texte
agent-browser wait "#spinner" --state hidden # Attendre la disparition d'un élément
# Téléchargements
agent-browser download @e1 ./fichier.pdf # Cliquer sur un élément pour déclencher le téléchargement
agent-browser wait --download ./sortie.zip # Attendre la fin de tout téléchargement
agent-browser --download-path ./téléchargements open <url> # Définir le répertoire de téléchargement par défaut
# Fenêtre et émulation d'appareil
agent-browser set viewport 1920 1080 # Définir la taille de la fenêtre (par défaut : 1280x720)
agent-browser set viewport 1920 1080 2 # 2x retina (même taille CSS, captures d'écran en haute résolution)
agent-browser set device "iPhone 14" # Émuler un appareil (fenêtre + agent utilisateur)
# Capture
agent-browser screenshot # Capture d'écran dans un répertoire temporaire
agent-browser screenshot --full # Capture d'écran pleine page
agent-browser screenshot --annotate # Capture d'écran annotée avec étiquettes numérotées des éléments
agent-browser screenshot --screenshot-dir ./captures # Enregistrer dans un répertoire personnalisé
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf sortie.pdf # Enregistrer au format PDF
# Presse-papiers
agent-browser clipboard read # Lire le texte du presse-papiers
agent-browser clipboard write "Bonjour le monde !" # Écrire du texte dans le presse-papiers
agent-browser clipboard copy # Copier la sélection actuelle
agent-browser clipboard paste # Coller depuis le presse-papiers
# Comparaison (comparer les états de page)
agent-browser diff snapshot # Comparer l'instantané actuel au dernier
agent-browser diff snapshot --baseline avant.txt # Comparer l'instantané actuel à un fichier sauvegardé
agent-browser diff screenshot --baseline avant.png # Différence visuelle de pixels
agent-browser diff url <url1> <url2> # Comparer deux pages
agent-browser diff url <url1> <url2> --wait-until networkidle # Stratégie d'attente personnalisée
agent-browser diff url <url1> <url2> --selector "#principal" # Limiter à un élément
Modèles courants
Soumission de formulaire
agent-browser open https://exemple.com/inscription
agent-browser snapshot -i
agent-browser fill @e1 "Jean Dupont"
agent-browser fill @e2 "[email protected]"
agent-browser select @e3 "Californie"
agent-browser check @e4
agent-browser click @e5
agent-browser wait --load networkidle
Authentification avec coffre-fort (recommandé)
# Enregistrer les identifiants une fois (chiffrés avec AGENT_BROWSER_ENCRYPTION_KEY)
# Recommandé : passer le mot de passe via stdin pour éviter l'historique du shell
echo "motdepasse" | agent-browser auth save github --url https://github.com/login --nom-utilisateur utilisateur --password-stdin
# Se connecter en utilisant le profil sauvegardé (l'IA ne voit jamais le mot de passe)
agent-browser auth login github
# Lister/afficher/supprimer les profils
agent-browser auth list
agent-browser auth show github
agent-browser auth delete github
Authentification avec persistance d'état
# Se connecter une fois et sauvegarder l'état
agent-browser open https://app.exemple.com/connexion
agent-browser snapshot -i
agent-browser fill @e1 "$NOM_UTILISATEUR"
agent-browser fill @e2 "$MOTDEPASSE"
agent-browser click @e3
agent-browser wait --url "**/tableau-de-bord"
agent-browser state save auth.json
# Réutiliser dans des sessions futures
agent-browser state load auth.json
agent-browser open https://app.exemple.com/tableau-de-bord
Persistance de session
# Sauvegarder/restaurer automatiquement les cookies et localStorage après redémarrage du navigateur
agent-browser --session-name monapp open https://app.exemple.com/connexion
# ... flux de connexion ...
agent-browser close # État sauvegardé automatiquement dans ~/.agent-browser/sessions/
# La prochaine fois, l'état est chargé automatiquement
agent-browser --session-name monapp open https://app.exemple.com/tableau-de-bord
# Chiffrer l'état au repos
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
agent-browser --session-name sécurisé open https://app.exemple.com
# Gérer les états sauvegardés
agent-browser state list
agent-browser state show monapp-default.json
agent-browser state clear monapp
agent-browser state clean --older-than 7
Extraction de données
agent-browser open https://exemple.com/produits
agent-browser snapshot -i
agent-browser get text @e5 # Obtenir le texte d'un élément spécifique
agent-browser get text body > page.txt # Obtenir tout le texte de la page
# Sortie JSON pour analyse
agent-browser snapshot -i --json
agent-browser get text @e1 --json
Sessions parallèles
agent-browser --session site1 open https://site-a.com
agent-browser --session site2 open https://site-b.com
agent-browser --session site1 snapshot -i
agent-browser --session site2 snapshot -i
agent-browser session list
Se connecter à un Chrome existant
# Découvrir automatiquement un Chrome en cours d'exécution avec le débogage à distance activé
agent-browser --auto-connect open https://exemple.com
agent-browser --auto-connect snapshot
# Ou avec un port CDP explicite
agent-browser --cdp 9222 snapshot
Schéma de couleurs (mode sombre)
# Mode sombre persistant via indicateur (s'applique à toutes les pages et nouveaux onglets)
agent-browser --color-scheme dark open https://exemple.com
# Ou via variable d'environnement
AGENT_BROWSER_COLOR_SCHEME=dark agent-browser open https://exemple.com
# Ou définir pendant la session (persiste pour les commandes suivantes)
agent-browser set media dark
Fenêtre et test réactif
# Définir une taille de fenêtre personnalisée (par défaut : 1280x720)
agent-browser set viewport 1920 1080
agent-browser screenshot bureau.png
# Tester la disposition de largeur mobile
agent-browser set viewport 375 812
agent-browser screenshot mobile.png
# Retina/HiDPI : même disposition CSS à densité de pixels 2x
# Les captures d'écran restent à la taille logique de la fenêtre, mais le contenu est rendu en DPI supérieur
agent-browser set viewport 1920 1080 2
agent-browser screenshot retina.png
# Émulation d'appareil (définit la fenêtre + l'agent utilisateur en une étape)
agent-browser set device "iPhone 14"
agent-browser screenshot appareil.png
Le paramètre scale (3ème argument) définit window.devicePixelRatio sans changer la disposition CSS. Utilisez-le pour tester le rendu retina ou capturer des captures d'écran en haute résolution.
Navigateur visuel (débogage)
agent-browser --headed open https://exemple.com
agent-browser highlight @e1 # Mettre en surbrillance un élément
agent-browser inspect # Ouvrir les outils de développement Chrome pour la page active
agent-browser record start demo.webm # Enregistrer la session
agent-browser profiler start # Démarrer le profilage des outils de développement Chrome
agent-browser profiler stop trace.json # Arrêter et sauvegarder le profil (chemin optionnel)
Utilisez AGENT_BROWSER_HEADED=1 pour activer le mode avec tête via variable d'environnement. Les extensions de navigateur fonctionnent en mode avec et sans tête.
Fichiers locaux (PDF, HTML)
# Ouvrir des fichiers locaux avec des URLs file://
agent-browser --allow-file-access open file:///chemin/vers/document.pdf
agent-browser --allow-file-access open file:///chemin/vers/page.html
agent-browser screenshot sortie.png
Simulateur iOS (Safari mobile)
# Lister les simulateurs iOS disponibles
agent-browser device list
# Lancer Safari sur un appareil spécifique
agent-browser -p ios --device "iPhone 16 Pro" open https://exemple.com
# Même flux de travail que sur bureau - instantané, interagir, nouvel instantané
agent-browser -p ios snapshot -i
agent-browser -p ios tap @e1 # Appuyer (alias pour cliquer)
agent-browser -p ios fill @e2 "texte"
agent-browser -p ios swipe up # Geste spécifique au mobile
# Prendre une capture d'écran
agent-browser -p ios screenshot mobile.png
# Fermer la session (arrête le simulateur)
agent-browser -p ios close
Prérequis : macOS avec Xcode, Appium (npm install -g appium && appium driver install xcuitest)
Appareils réels : Fonctionne avec des appareils iOS physiques s'ils sont préconfigurés. Utilisez --device "<UDID>" où UDID provient de xcrun xctrace list devices.
Sécurité
Toutes les fonctionnalités de sécurité sont facultatives. Par défaut, agent-browser n'impose aucune restriction sur la navigation, les actions ou la sortie.
Limites de contenu (recommandé pour les agents IA)
Activez --content-boundaries pour envelopper la sortie provenant de la page dans des marqueurs qui aident les LLM à distinguer la sortie de l'outil du contenu de page non fiable :
export AGENT_BROWSER_CONTENT_BOUNDARIES=1
agent-browser snapshot
# Sortie :
# --- AGENT_BROWSER_PAGE_CONTENT nonce=<hex> origin=https://exemple.com ---
# [arbre d'accessibilité]
# --- END_AGENT_BROWSER_PAGE_CONTENT nonce=<hex> ---
Liste blanche de domaines
Restreignez la navigation aux domaines de confiance. Les caractères génériques comme *.exemple.com correspondent également au domaine nu exemple.com. Les requêtes de sous-ressources, les connexions WebSocket et EventSource vers des domaines non autorisés sont également bloquées. Incluez les domaines CDN dont dépendent vos pages cibles :
export AGENT_BROWSER_ALLOWED_DOMAINS="exemple.com,api.exemple.com,cdn.exemple.com"
agent-browser open https://exemple.com
Limites de navigation et d'actions
Définissez des limites sur les actions du navigateur :
export AGENT_BROWSER_MAX_NAVIGATIONS=10
export AGENT_BROWSER_MAX_CLICKS=50
export AGENT_BROWSER_MAX_FILLS=20
export AGENT_BROWSER_MAX_SCREENSHOTS=5
# Limite de temps pour le travail d'agent :
export AGENT_BROWSER_MAX_WALL_CLOCK_TIME=300000 # 5 minutes en millisecondes
Désactiver les téléchargements
export AGENT_BROWSER_DISABLE_DOWNLOADS=1
Mode restreint
--restricted active toutes les fonctionnalités de sécurité :
agent-browser --restricted open https://exemple.com
C'est équivalent à définir toutes les variables d'environnement de sécurité et le mode de navigation restreint. Voir references/security.md pour plus de détails.
Livres/interactifs
# Avec gestion centrale de l'état (recommandé - l'IA gère l'état)
agent-browser --session-state-dir ~/.agent-browser/sessions state save monapp.json
# Basculer entre les sessions
agent-browser --session-state-dir ~/.agent-browser/sessions --session-name "test-a" open https://[...]