Automatisation de navigateur pour agents sandboxés

Cette compétence est destinée aux agents s'exécutant sur machines distantes sandboxées (VM cloud, CI, agents de codage) qui ont besoin de contrôler un navigateur headless.

Prérequis

browser-use doctor    # Vérifier l'installation

Pour les détails de configuration, voir https://github.com/browser-use/browser-use/blob/main/browser_use/skill_cli/README.md

Flux de travail principal

1. Naviguer : browser-use open <url> — démarre le navigateur headless si nécessaire
2. Inspecter : browser-use state — retourne les éléments cliquables avec indices
3. Interagir : utiliser les indices de state (browser-use click 5, browser-use input 3 "text")
4. Vérifier : browser-use state ou browser-use screenshot pour confirmer
5. Répéter : le navigateur reste ouvert entre les commandes
6. Nettoyer : browser-use close une fois terminé

Modes de navigateur

browser-use open <url>                                    # Par défaut : Chromium headless
browser-use cloud connect                                 # Provisionner un navigateur cloud et se connecter
browser-use --connect open <url>                          # Découvrir automatiquement Chrome via CDP
browser-use --cdp-url ws://localhost:9222/... open <url>  # Se connecter via URL CDP

Commandes

# Navigation
browser-use open <url>                    # Naviguer vers URL
browser-use back                          # Revenir en arrière dans l'historique
browser-use scroll down                   # Défiler vers le bas (--amount N pour pixels)
browser-use scroll up                     # Défiler vers le haut
browser-use tab list                      # Lister tous les onglets avec statut de verrou
browser-use tab new [url]                 # Ouvrir un nouvel onglet (vierge ou avec URL)
browser-use tab switch <index>            # Basculer vers l'onglet par index
browser-use tab close <index> [index...]  # Fermer un ou plusieurs onglets

# État de page — toujours exécuter state en premier pour obtenir les indices d'éléments
browser-use state                         # URL, titre, éléments cliquables avec indices
browser-use screenshot [path.png]         # Capture d'écran (base64 si pas de chemin, --full pour page complète)

# Interactions — utiliser les indices de state
browser-use click <index>                 # Cliquer sur l'élément par index
browser-use click <x> <y>                 # Cliquer aux coordonnées en pixels
browser-use type "text"                   # Taper dans l'élément actif
browser-use input <index> "text"          # Cliquer sur l'élément, puis taper
browser-use keys "Enter"                  # Envoyer les touches clavier (aussi "Control+a", etc.)
browser-use select <index> "option"       # Sélectionner une option de menu déroulant
browser-use upload <index> <path>         # Télécharger un fichier dans une saisie de fichier
browser-use hover <index>                 # Survoler l'élément
browser-use dblclick <index>              # Double-cliquer sur l'élément
browser-use rightclick <index>            # Clic droit sur l'élément

# Extraction de données
browser-use eval "js code"                # Exécuter du JavaScript, retourner le résultat
browser-use get title                     # Titre de la page
browser-use get html [--selector "h1"]    # HTML de la page (ou limité au sélecteur)
browser-use get text <index>              # Contenu texte de l'élément
browser-use get value <index>             # Valeur input/textarea
browser-use get attributes <index>        # Attributs de l'élément
browser-use get bbox <index>              # Boîte englobante (x, y, largeur, hauteur)

# Attendre
browser-use wait selector "css"           # Attendre un élément (--state visible|hidden|attached|detached, --timeout ms)
browser-use wait text "text"              # Attendre que le texte apparaisse

# Cookies
browser-use cookies get [--url <url>]     # Obtenir les cookies (optionnellement filtrés)
browser-use cookies set <name> <value>    # Définir un cookie (--domain, --secure, --http-only, --same-site, --expires)
browser-use cookies clear [--url <url>]   # Effacer les cookies
browser-use cookies export <file>         # Exporter en JSON
browser-use cookies import <file>         # Importer depuis JSON

# Python — session persistante avec accès au navigateur
browser-use python "code"                 # Exécuter du Python (les variables persistent entre les appels)
browser-use python --file script.py       # Exécuter un fichier
browser-use python --vars                 # Afficher les variables définies
browser-use python --reset                # Effacer l'espace de noms

# Session
browser-use close                         # Fermer le navigateur et arrêter le daemon
browser-use sessions                      # Lister les sessions actives
browser-use close --all                   # Fermer toutes les sessions

L'objet Python browser fournit : browser.url, browser.title, browser.html, browser.goto(url), browser.back(), browser.click(index), browser.type(text), browser.input(index, text), browser.keys(keys), browser.upload(index, path), browser.screenshot(path), browser.scroll(direction, amount), browser.wait(seconds).

Tunnels

Exposer les serveurs de développement locaux au navigateur via les tunnels Cloudflare.

browser-use tunnel <port>                 # Démarrer le tunnel (idempotent)
browser-use tunnel list                   # Afficher les tunnels actifs
browser-use tunnel stop <port>            # Arrêter le tunnel
browser-use tunnel stop --all             # Arrêter tous les tunnels

Chaînage de commandes

Les commandes peuvent être chaînées avec &&. Le navigateur persiste via le daemon, donc le chaînage est sûr et efficace.

browser-use open https://example.com && browser-use state
browser-use input 5 "user@example.com" && browser-use input 6 "password" && browser-use click 7

Chaînez quand vous n'avez pas besoin de la sortie intermédiaire. Exécutez séparément quand vous devez analyser state pour découvrir d'abord les indices.

Flux de travail courants

Exposer les serveurs de développement locaux

python -m http.server 3000 &                      # Démarrer le serveur de développement
browser-use tunnel 3000                            # → https://abc.trycloudflare.com
browser-use open https://abc.trycloudflare.com     # Naviguer dans le tunnel

Les tunnels sont indépendants des sessions de navigateur et persistent au-delà de browser-use close.

Multi-agent (mode --connect)

Plusieurs agents peuvent partager un navigateur via --connect. Chaque agent obtient son propre onglet — les autres agents ne peuvent pas interferer.

Configuration : S'enregistrer une fois, puis passer l'index avec chaque commande --connect :

INDEX=$(browser-use register)                    # → affiche "1"
browser-use --connect $INDEX open <url>          # Naviguer dans l'onglet propre de l'agent
browser-use --connect $INDEX state               # Obtenir l'état depuis l'onglet de l'agent
browser-use --connect $INDEX click <element>     # Cliquer dans l'onglet de l'agent

• Verrouillage d'onglet : Quand un agent mute un onglet (clic, frappe, navigation), cet onglet lui est verrouillé. Les autres agents reçoivent une erreur s'ils essaient de muter le même onglet.
• Accès en lecture seule : les commandes state, screenshot, get et wait fonctionnent sur n'importe quel onglet indépendamment des verrous.
• Les sessions d'agent expirent après 5 minutes d'inactivité. Exécutez browser-use register à nouveau pour obtenir un nouvel index.

Options globales

Conseils

1. Toujours exécuter state en premier pour voir les éléments disponibles et leurs indices
2. Les sessions persistent — le navigateur reste ouvert entre les commandes jusqu'à sa fermeture
3. Les tunnels sont indépendants — ils persistent au-delà de browser-use close
4. tunnel est idempotent — l'appeler à nouveau pour le même port retourne l'URL existante

Dépannage

• Le navigateur ne démarre pas ? browser-use close puis réessayer. Exécutez browser-use doctor pour vérifier.
• Élément introuvable ? browser-use scroll down puis browser-use state
• Le tunnel ne fonctionne pas ? which cloudflared pour vérifier, browser-use tunnel list pour voir les tunnels actifs

Nettoyage

browser-use close                         # Fermer la session du navigateur
browser-use tunnel stop --all             # Arrêter les tunnels (le cas échéant)