Automatisation de navigateur avec agent-browser

La CLI utilise Chrome/Chromium via CDP directement. Installez-la 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. Exécutez agent-browser upgrade pour mettre à jour vers la dernière version.

Flux de travail principal

Toute 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 la navigation ou les changements DOM, obtenir de nouvelles références

agent-browser open https://example.com/form
agent-browser snapshot -i
# Sortie : @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 --load networkidle
agent-browser snapshot -i  # Vérifier le résultat

Chaînage de commandes

Les commandes peuvent être chaînées avec && dans un seul appel shell. Le navigateur persiste entre les commandes via un démon en arrière-plan, donc le chaînage est sûr et plus efficace que des appels séparés.

# Chaîner ouvrir + attendre + instantané en un seul appel
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i

# Chaî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 wait --load networkidle && agent-browser screenshot page.png

Quand chaî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 qui convient :

Option 1 : Importer l'authentification depuis le navigateur de l'utilisateur (le plus rapide pour les 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 des 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 les tâches récurrentes)

# Première exécution : connexion manuelle ou automatisée
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 3 : 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 automatiquement sauvegardé

# Prochaine fois : état automatiquement restauré
agent-browser --session-name myapp open https://app.example.com/dashboard

Option 4 : Coffre-fort d'authentification (identifiants stockés chiffré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 du formulaire de connexion apparaissent avant de remplir/cliquer, ce qui est plus fiable sur les écrans de connexion SPA différés.

Option 5 : Fichier d'état (sauvegarde/charge manuelle)

# 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 OAuth, 2FA, authentification par cookie et modèles de renouvellement de jeton.

Commandes essentielles

# 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 -s "#selector" # 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 saisir du texte
agent-browser type @e2 "texte"         # Saisir 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"    # Saisir 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.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

# Attendre
agent-browser wait @e1                # Attendre un élément
agent-browser wait --load networkidle # Attendre le réseau 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 ./file.pdf          # Cliquer sur un élément pour déclencher le téléchargement
agent-browser wait --download ./output.zip     # Attendre la fin de tout téléchargement
agent-browser --download-path ./downloads open <url>  # Définir le répertoire de téléchargement par défaut

# 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

# Zone d'affichage et émulation d'appareil
agent-browser set viewport 1920 1080          # Définir la taille de la zone d'affichage (défaut : 1280x720)
agent-browser set viewport 1920 1080 2        # Rétine 2x (même taille CSS, captures d'écran en plus haute résolution)
agent-browser set device "iPhone 14"          # Émuler un appareil (zone d'affichage + 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 des étiquettes d'éléments numérotées
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 au format PDF

# Aperçu en direct / streaming
agent-browser stream enable           # Démarrer le streaming WebSocket en temps réel 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 la screencasting
agent-browser stream disable          # Arrêter le streaming en cours et supprimer le fichier .stream

# 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 afin de ne jamais bloquer l'agent.
# Les boîtes de dialogue confirm et prompt nécessitent toujours une gestion explicite.
# Utilisez --no-auto-dialog pour désactiver la gestion automatique.
agent-browser dialog accept              # Accepter la boîte de dialogue
agent-browser dialog accept "ma saisie"   # 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 au dernier
agent-browser diff snapshot --baseline before.txt    # Comparer l'instantané actuel à 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

Streaming

Chaque session démarre automatiquement un serveur de streaming 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

Exécutez plusieurs commandes en une seule invocation en redirigeant un tableau JSON de tableaux de chaînes vers batch. Cela évite la surcharge de démarrage de processus par commande lors de l'exécution de workflows en plusieurs étapes.

echo '[
  ["open", "https://example.com"],
  ["snapshot", "-i"],
  ["click", "@e1"],
  ["screenshot", "result.png"]
]' | agent-browser batch --json

# S'arrêter à la première erreur
agent-browser batch --bail < commands.json

Utilisez batch lorsque vous avez une séquence de commandes connue qui ne dépend pas de la sortie intermédiaire. Utilisez des commandes séparées ou le chaînage && lorsque vous devez analyser la sortie entre les étapes (par exemple, instantané pour découvrir les références, puis interagir).

Modèles courants

Soumission de formulaire

agent-browser open https://example.com/signup
agent-browser snapshot -i
agent-browser fill @e1 "Jane Doe"
agent-browser fill @e2 "[email protected]"
agent-browser select @e3 "California"
agent-browser check @e4
agent-browser click @e5
agent-browser wait --load networkidle

Authentification avec coffre-fort (Recommandé)

# Sauvegarder les identifiants une fois (chiffrés avec AGENT_BROWSER_ENCRYPTION_KEY)
# Recommandé : rediriger 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

# Se connecter en utilisant le profil sauvegardé (le LLM 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

auth login attend les sélecteurs de nom d'utilisateur/mot de passe/soumettre avant d'interagir, avec un délai d'attente lié au délai d'action par défaut.

Authentification avec persistance d'état

# Se connecter une fois et sauvegarder l'état
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "$USERNAME"
agent-browser fill @e2 "$PASSWORD"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save auth.json

# Réutiliser dans des sessions futures
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard

Persistance de session

# Sauvegarder/restaurer automatiquement les cookies et localStorage entre les redémarrages du navigateur
agent-browser --session-name myapp open https://app.example.com/login
# ... flux de connexion ...
agent-browser close  # État automatiquement sauvegardé dans ~/.agent-browser/sessions/

# Prochaine fois, l'état est automatiquement chargé
agent-browser --session-name myapp open https://app.example.com/dashboard

# Chiffrer l'état au repos
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
agent-browser --session-name secure open https://app.example.com

# Gérer les états sauvegardés
agent-browser state list
agent-browser state show myapp-default.json
agent-browser state clear myapp
agent-browser state clean --older-than 7

Travailler avec des iframes

Le contenu des iframes est automatiquement intégré dans les instantanés. Les références à l'intérieur des iframes portent le contexte du cadre, vous pouvez donc interagir directement avec elles.

agent-browser open https://example.com/checkout
agent-browser snapshot -i
# @e1 [heading] "Checkout"
# @e2 [Iframe] "payment-frame"
#   @e3 [input] "Numéro de carte"
#   @e4 [input] "Date d'expiration"
#   @e5 [button] "Payer"

# Interagir directement — aucun changement de cadre nécessaire
agent-browser fill @e3 "4111111111111111"
agent-browser fill @e4 "12/28"
agent-browser click @e5

# Pour limiter un instantané à un seul iframe :
agent-browser frame @e2
agent-browser snapshot -i         # Contenu de l'iframe uniquement
agent-browser frame main          # Revenir au cadre principal

Extraction de données

agent-browser open https://example.com/products
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 l'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://example.com
agent-browser --auto-connect snapshot

# Ou avec un port CDP explicite
agent-browser --cdp 9222 snapshot

Auto-connect découvre Chrome via DevToolsActivePort, les ports de débogage courants (9222, 9229), et tombe sur une connexion WebSocket directe si la découverte CDP basée sur HTTP échoue.

Schéma de couleurs (Dark Mode)

# Définir le schéma de couleurs (dark/light, défaut : light)
agent-browser set color-scheme dark
agent-browser open https://example.com  # La page sera rendue en mode sombre (si pris en charge par le site)

Capture d'écran différée / asynchrone

Pour les pages où le contenu met du temps à s'afficher :

# Option 1 : définir un délai d'attente de chargement avant la capture d'écran
agent-browser set timeout 30000
agent-browser screenshot --full

# Option 2 : configuration par commande
agent-browser screenshot --wait 2000

Configuration

La plupart des options peuvent être définies avec des variables d'environnement ou des fichiers de configuration :

Variable d'environnement	Description	Défaut
`BROWSER_PATH`	Chemin vers le binaire Chrome/Chromium	Auto-détecté
`CDP_PORT`	Port CDP à utiliser	9222
`AGENT_BROWSER_ENCRYPTION_KEY`	Clé de chiffrement pour les fichiers d'état/d'identifiants	Aucun (non chiffré)
`AGENT_BROWSER_DOWNLOAD_PATH`	Répertoire de téléchargement par défaut	Répertoire temporaire
`AGENT_BROWSER_DEFAULT_TIMEOUT`	Délai d'attente par défaut pour les actions (ms)	30000

Créez un fichier ~/.agent-browser/config.json pour les préférences persistantes :

{
  "defaultTimeout": 15000,
  "viewport": {
    "width": 1920,
    "height": 1080
  },
  "colorScheme": "light",
  "downloadPath": "/chemin/vers/telechargements"
}

Gestion des erreurs

Délai d'attente : Toutes les commandes ont des délais d'attente configurables (--timeout ou AGENT_BROWSER_DEFAULT_TIMEOUT). Si un élément n'est pas trouvé dans le délai, la commande échoue avec un code de sortie non nul.
Réessais : agent-browser retry <count> <delay> <command> pour réessayer une commande jusqu'à ce qu'elle réussisse.

# Réessayer 3 fois avec un délai de 2 secondes entre chaque tentative
agent-browser retry 3 2 snapshot -i

Codes de sortie : Les commandes réussies renvoient 0. Les échecs renvoient un code d'erreur spécifique (généralement 1 pour les erreurs génériques, 2 pour les délais d'attente, 3 pour les problèmes de connexion navigateur).

lunrenyi/ai-agent.sh

Qu'est-ce que ai-agent.sh ?

Demander à votre IA préférée

Documentation