Automatisation de Navigateur avec agent-browser
L'interface en ligne de commande utilise Chrome/Chromium directement via CDP. Installez avec npm i -g agent-browser, brew install agent-browser ou cargo install agent-browser. Exécutez agent-browser install pour télécharger Chrome. Les installations existantes de Chrome, Brave, Playwright et Puppeteer sont détectées automatiquement. Exécutez agent-browser upgrade pour passer à la dernière version.
Workflow de Base
Toute automatisation de navigateur suit ce modèle :
- Naviguer :
agent-browser open <url> - Instantané :
agent-browser snapshot -i(obtenir les références d'éléments comme@e1,@e2) - Interagir : Utiliser les références pour cliquer, remplir, sélectionner
- Re-instantané : Après navigation ou modifications du DOM, obtenir de nouvelles références
agent-browser open https://example.com/form
agent-browser snapshot -i
# Résultat : @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"
agent-browser fill @e1 "[email protected]"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait 2000
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 open + snapshot en un seul appel (open attend déjà le chargement de la page)
agent-browser open https://example.com && agent-browser snapshot -i
# Enchaîner plusieurs interactions
agent-browser fill @e1 "[email protected]" && agent-browser fill @e2 "password123" && agent-browser click @e3
# Naviguer et capturer
agent-browser open https://example.com && agent-browser screenshot
Quand enchaîner : Utilisez && lorsque vous n'avez pas besoin de lire la sortie d'une commande intermédiaire avant de poursuivre (par exemple, open + wait + screenshot). Exécutez les commandes séparément lorsque vous devez d'abord analyser la sortie (par exemple, snapshot pour découvrir les références, puis interagir avec ces références).
Gestion de l'Authentification
Lors de l'automatisation d'un site nécessitant une connexion, choisissez l'approche adaptée :
Option 1 : Importer l'authentification 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.example.com/dashboard
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 un chiffrement au repos.
Option 2 : Réutilisation de profil Chrome (aucune configuration)
# Lister les profils Chrome disponibles
agent-browser profiles
# Réutiliser l'état de connexion existant de l'utilisateur
agent-browser --profile Default open https://gmail.com
Option 3 : Profil persistant (pour des tâches récurrentes)
# Première exécution : connexion manuelle ou via automatisation
agent-browser --profile ~/.myapp open https://app.example.com/login
# ... remplir les identifiants, soumettre ...
# Toutes les exécutions suivantes : déjà authentifié
agent-browser --profile ~/.myapp open https://app.example.com/dashboard
Option 4 : Nom de session (sauvegarde/restauration automatique des cookies + localStorage)
agent-browser --session-name myapp open https://app.example.com/login
# ... flux de connexion ...
agent-browser close # État auto-sauvegardé
# Prochaine fois : état auto-restauré
agent-browser --session-name myapp open https://app.example.com/dashboard
Option 5 : Coffre-fort d'authentification (identifiants stockés cryptés, connexion par nom)
echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
agent-browser auth login myapp
auth login navigue avec load puis attend que les sélecteurs de formulaire de connexion apparaissent avant de remplir/cliquer, ce qui est plus fiable sur les écrans de connexion SPA différés.
Option 6 : Fichier d'état (sauvegarde/chargement manuel)
# Après connexion :
agent-browser state save ./auth.json
# Dans une session future :
agent-browser state load ./auth.json
agent-browser open https://app.example.com/dashboard
Voir references/authentication.md pour les modèles OAuth, 2FA, authentification par cookie et rafraîchissement de jeton.
Commandes Essentielles
# Lot : TOUJOURS utiliser batch pour 2+ commandes séquentielles. Les commandes s'exécutent dans l'ordre.
agent-browser batch "open https://example.com" "snapshot -i"
agent-browser batch "open https://example.com" "screenshot"
agent-browser batch "click @e1" "wait 1000" "screenshot"
# Navigation
agent-browser open <url> # Naviguer (alias : goto, navigate)
agent-browser close # Fermer le navigateur
agent-browser close --all # Fermer toutes les sessions actives
# Instantané
agent-browser snapshot -i # Éléments interactifs avec références (recommandé)
agent-browser snapshot -i --urls # Inclure les URLs href pour les liens
agent-browser snapshot -s "#selector" # Limiter au sélecteur CSS
# Interaction (utiliser les @ref 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 Enter # 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 clavier
agent-browser scroll down 500 # Faire défiler la page
agent-browser scroll down 500 --selector "div.content" # 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
# Attente
agent-browser wait @e1 # Attendre un élément
agent-browser wait 2000 # Attendre en millisecondes
agent-browser wait --url "**/page" # Attendre un motif d'URL
agent-browser wait --text "Bienvenue" # Attendre l'apparition d'un texte (correspondance partielle)
agent-browser wait --load networkidle # Attendre l'inactivité réseau (attention : voir Pièges)
agent-browser wait --fn "!document.body.innerText.includes('Chargement...')" # Attendre la disparition d'un texte
agent-browser wait "#spinner" --state hidden # Attendre la disparition d'un élément
# Téléchargements
agent-browser download @e1 ./file.pdf # Cliquer sur un élément pour déclencher un téléchargement
agent-browser wait --download ./output.zip # Attendre la fin d'un téléchargement
agent-browser --download-path ./downloads open <url> # Définir le répertoire de téléchargement par défaut
# Gestion des onglets
agent-browser tab list # Lister tous les onglets ouverts
agent-browser tab new # Ouvrir un nouvel onglet vierge
agent-browser tab new https://example.com # Ouvrir une URL dans un nouvel onglet
agent-browser tab 2 # Basculer vers l'onglet par index (base 0)
agent-browser tab close # Fermer l'onglet actuel
agent-browser tab close 2 # Fermer l'onglet par index
# Réseau
agent-browser network requests # Inspecter les requêtes suivies
agent-browser network requests --type xhr,fetch # Filtrer par type de ressource
agent-browser network requests --method POST # Filtrer par méthode HTTP
agent-browser network requests --status 2xx # Filtrer par statut (200, 2xx, 400-499)
agent-browser network request <requestId> # Voir les détails complets de la requête/réponse
agent-browser network route "**/api/*" --abort # Bloquer les requêtes correspondantes
agent-browser network har start # Démarrer l'enregistrement HAR
agent-browser network har stop ./capture.har # Arrêter et sauvegarder le fichier HAR
# Fenêtre et Émulation d'Appareil
agent-browser set viewport 1920 1080 # Définir la taille de la fenêtre (défaut : 1280x720)
agent-browser set viewport 1920 1080 2 # 2x rétine (même taille CSS, captures plus 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 annotée avec des étiquettes numérotées des éléments
agent-browser screenshot --screenshot-dir ./shots # Sauvegarder dans un répertoire personnalisé
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf output.pdf # Sauvegarder en PDF
# Aperçu en direct / diffusion en continu
agent-browser stream enable # Démarrer la diffusion WebSocket en cours d'exécution sur un port auto-sélectionné
agent-browser stream enable --port 9223 # Lier un port localhost spécifique
agent-browser stream status # Inspecter l'état activé, le port, la connexion et le screencasting
agent-browser stream disable # Arrêter la diffusion en continu et supprimer le fichier .stream de métadonnées
# 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
# Boîtes de dialogue (alert, confirm, prompt, beforeunload)
# Par défaut, les boîtes de dialogue alert et beforeunload sont automatiquement acceptées pour ne jamais bloquer l'agent.
# Les boîtes confirm et prompt nécessitent encore un traitement explicite.
# Utilisez --no-auto-dialog (ou AGENT_BROWSER_NO_AUTO_DIALOG=1) pour désactiver la gestion automatique.
agent-browser dialog accept # Accepter la boîte de dialogue
agent-browser dialog accept "mon entrée" # Accepter la boîte de dialogue prompt avec du texte
agent-browser dialog dismiss # Rejeter/annuler la boîte de dialogue
agent-browser dialog status # Vérifier si une boîte de dialogue est actuellement ouverte
# Diff (comparer les états de page)
agent-browser diff snapshot # Comparer l'instantané actuel avec le précédent
agent-browser diff snapshot --baseline before.txt # Comparer l'instantané actuel avec un fichier sauvegardé
agent-browser diff screenshot --baseline before.png # Diff visuel 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 "#main" # Limiter à un élément
# Chat (contrôle en langage naturel par IA)
agent-browser chat "ouvre google.com et cherche des chats" # Instruction unique
agent-browser chat # Mode REPL interactif
agent-browser -q chat "résume cette page" # Silencieux (texte uniquement, sans appels d'outils)
agent-browser -v chat "remplis le formulaire de connexion" # Verbeux (afficher la sortie des commandes)
agent-browser --model openai/gpt-4o chat "prends une capture d'écran" # Remplacer le modèle
Diffusion en continu
Chaque session démarre automatiquement un serveur de flux WebSocket sur un port attribué par le système d'exploitation. Utilisez agent-browser stream status pour voir le port lié et l'état de la connexion. Utilisez stream disable pour le démonter, et stream enable --port <port> pour le réactiver sur un port spécifique.
Exécution par Lots
Utilisez TOUJOURS batch lorsque vous exécutez 2 commandes ou plus en séquence. Batch exécute les commandes dans l'ordre, donc les commandes dépendantes (comme naviguer puis capturer) fonctionnent correctement. Chaque argument entre guillemets est une commande distincte.
# Naviguer et prendre un instantané
agent-browser batch "open https://example.com" "snapshot -i"
# Naviguer, instantané et capture d'écran en un seul appel
agent-browser batch "open https://example.com" "snapshot -i" "screenshot"
# Cliquer, attendre, puis capturer
agent-browser batch "click @e1" "wait 1000" "screenshot"
# Avec --bail pour s'arrêter à la première erreur
agent-browser batch --bail "open https://example.com" "click @e1" "screenshot"
N'utilisez une seule commande (pas de batch) que lorsque vous devez lire la sortie avant de décider de la commande suivante. Par exemple, vous devez exécuter snapshot -i en tant que commande unique lorsque vous avez besoin de lire les références pour décider sur quoi cliquer. Après avoir lu l'instantané, mettez les étapes restantes en lot.
Le mode stdin est également pris en charge pour une utilisation programmatique :
echo '[["open","https://example.com"],["screenshot"]]' | agent-browser batch --json
agent-browser batch --bail < commands.json
Stratégies d'Efficacité
Ces modèles minimisent le nombre d'appels d'outils et l'utilisation de jetons.
Utilisez --urls pour éviter de re-naviguer. Lorsque vous devez visiter des liens à partir d'une page, utilisez snapshot -i --urls pour obtenir toutes les URLs href à l'avance. Ensuite, ouvrez chaque URL directement au lieu de cliquer sur des références et de revenir en arrière.
Instantané une fois, agissez plusieurs fois. Ne refaites jamais d'instantané de la même page. Extrayez toutes les informations nécessaires (références, URLs, texte) d'un seul instantané, puis mettez les actions restantes en lot.
Workflow multi-page (par exemple, "visiter N sites et capturer chacun") :
# 1. Obtenir toutes les URLs en un seul appel
agent-browser batch "open https://news.ycombinator.com" "snapshot -i --urls"
# Lire la sortie pour extraire les URLs, puis visiter chacune directement :
# 2. Un lot par site cible
agent-browser batch "open https://github.com/example/repo" "screenshot"
agent-browser batch "open https://example.com/article" "screenshot"
agent-browser batch "open https://other.com/page" "screenshot"
Cette approche utilise 4 appels d'outils au lieu de 14+ . Ne revenez jamais à la page de liste entre les visites.
Modèles Courants
Soumission de Formulaire
# Naviguer et obtenir la structure du formulaire
agent-browser batch "open https://example.com/signup" "snapshot -i"
# Lire la sortie de l'instantané pour identifier les références du formulaire, puis remplir et soumettre
agent-browser batch "fill @e1 \"Jane Doe\"" "fill @e2 \"[email protected]\"" "select @e3 \"California\"" "check @e4" "click @e5" "wait 2000"
Authentification avec Coffre-Fort (Recommandée)
# Sauvegarder les identifiants une fois (cryptés avec AGENT_BROWSER_ENCRYPTION_KEY)
# Recommandé : passer le mot de passe via stdin pour éviter l'exposition dans l'historique du shell
echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
# Connexion à l'aide du profil sauvegardé (l'LLM ne voit jamais le mot de passe)
agent-browser auth login github
# Lister/afficher/supprimer les profils
agent-browser auth list
a
...
[tronqué pour la traduction]