agent-browser

Overview

What is agent-browser?

agent-browser est un outil d’automatisation de navigateur en ligne de commande conçu pour les agents IA et les workflows basés sur le shell. Il se connecte directement à Chrome ou Chromium via le Chrome DevTools Protocol (CDP), ce qui permet de scénariser de vraies interactions navigateur depuis le terminal ou l’environnement d’exécution d’un agent.

Avec agent-browser, vous pouvez :

• Ouvrir et parcourir des pages web (agent-browser open <url>)
• Découvrir les éléments interactifs via des snapshots structurés
• Cliquer sur des boutons, suivre des liens et interagir avec des formulaires
• Remplir des champs, saisir du texte et simuler des frappes clavier
• Prendre des snapshots pour comprendre la structure de la page et les actions possibles
• Gérer des sessions et conserver un état authentifié
• Gérer des parcours d’authentification (y compris OAuth et 2FA avec intervention humaine)
• Utiliser des proxys pour le geo-testing ou les environnements d’entreprise
• Enregistrer des traces de performances pour le profiling
• Capturer des vidéos de sessions navigateur pour le debug ou la documentation

Who is agent-browser for?

agent-browser est particulièrement adapté si vous :

• Faites tourner un agent IA ou un framework d’automatisation qui a besoin d’un vrai contrôle du navigateur
• Cherchez un moyen orienté CLI pour automatiser des workflows Chrome/Chromium
• Avez besoin d’un ciblage robuste des éléments, compatible avec les LLM (via des @refs compacts)
• Automatisez des parcours de connexion, la soumission de formulaires ou des flux web applicatifs multi-étapes
• Souhaitez capturer des tests reproductibles, des démos ou des sessions de debug sous forme de vidéos ou de traces

Il est particulièrement utile dans les scénarios suivants :

• Automatisation de navigateur : navigation scriptée, clics et remplissage de formulaires
• Automatisation de workflows : séquences de bout en bout comme « log in → navigate → export report »
• Automatisation de tests : smoke tests, vérifications de régression et profiling de performances d’applications web

When agent-browser is and is not a good fit

Utilisez agent-browser lorsque :

• Vous pouvez exécuter une CLI localement et avez accès à Chrome ou Chromium
• Vous voulez un comportement navigateur déterministe et scriptable, exposé à un agent IA
• Vous avez besoin d’un contrôle fin des sessions, cookies et mécanismes d’authentification

Ce n’est pas forcément le bon choix si :

• Vous ne pouvez pas installer ou exécuter Chrome/Chromium sur la machine hôte
• Vous avez seulement besoin de HTML brut ou de requêtes HTTP simples (un client HTTP ou scraper pur sera plus simple)
• Vous cherchez un contrôle de navigateur headless étroitement couplé à d’autres bibliothèques d’automatisation dans un langage ou runtime spécifique

How to Use

Installation options

agent-browser prend en charge plusieurs méthodes d’installation. Choisissez celle qui correspond le mieux à votre environnement :

• npm (Node.js)

  npm i -g agent-browser
  

• Homebrew (macOS/Linux)

  brew install agent-browser
  

• Rust / Cargo

  cargo install agent-browser
  

Après avoir installé la CLI, lancez la configuration intégrée de Chrome :

agent-browser install

Cela télécharge et configure une version compatible de Chrome/Chromium. Lorsqu’une nouvelle version est disponible, mettez à jour avec :

agent-browser upgrade

Si vous utilisez agent-browser comme skill dans une plateforme d’agents, vous pouvez aussi l’ajouter avec :

npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser

Consultez le fichier SKILL.md dans le dépôt pour les dernières informations de configuration propres au skill.

Core browser automation workflow

Chaque workflow agent-browser suit une boucle simple : open → snapshot → interact → re-snapshot.

1. Naviguer vers une page

   agent-browser open https://example.com/form
   

2. Prendre un snapshot pour découvrir les éléments
   Utilisez le mode snapshot interactif pour obtenir une liste compacte des éléments cliquables et remplissables avec des @refs :

   agent-browser snapshot -i
   

   Exemple de sortie (simplifiée) :

   @e1 [input type="email"]
   @e2 [input type="password"]
   @e3 [button] "Submit"
   

3. Interagir via les refs

   agent-browser fill @e1 "user@example.com"
   agent-browser fill @e2 "password123"
   agent-browser click @e3
   

4. Attendre et refaire un snapshot

   agent-browser wait --load networkidle
   agent-browser snapshot -i
   

Ce pattern permet à un agent IA de raisonner sur une vue structurelle compacte plutôt que sur le DOM complet, ce qui réduit fortement la consommation de contexte.

Command reference basics

agent-browser expose un riche ensemble de commandes (voir references/commands.md), notamment :

• Navigation

  agent-browser open <url>
  agent-browser back
  agent-browser forward
  agent-browser reload
  agent-browser close
  

• Snapshot et refs

  agent-browser snapshot          # arbre complet
  agent-browser snapshot -i       # éléments interactifs uniquement (recommandé)
  agent-browser snapshot -c       # sortie compacte
  agent-browser snapshot -d 3     # profondeur maximale
  agent-browser snapshot -s "#main"  # limité à un sélecteur CSS
  

• Interactions

  agent-browser click @e1
  agent-browser dblclick @e1
  agent-browser hover @e1
  agent-browser focus @e1
  agent-browser fill @e2 "text"
  agent-browser type @e2 "text"
  agent-browser press Enter
  

Consultez references/snapshot-refs.md pour une explication détaillée sur la génération des @refs et leur durée de validité.

Working with sessions and authentication

agent-browser fournit des outils intégrés pour la navigation authentifiée et multi-session. C’est utile pour les parcours de connexion, les tests multi-comptes ou l’isolation de rôles utilisateur.

• Sessions nommées (voir references/session-management.md) :

  # Session "auth" : parcours de connexion
  agent-browser --session auth open https://app.example.com/login
  
  # Session "public" : navigation séparée
  agent-browser --session public open https://example.com
  

  Chaque session dispose de cookies, stockage, cache et historique isolés.

• Persistance de l’état de session :

  # Sauvegarder cookies et stockage
  agent-browser state save ./auth-state.json
  
  # Restaurer plus tard
  agent-browser state load ./auth-state.json
  agent-browser open https://app.example.com/dashboard
  

• Patterns d’authentification (voir references/authentication.md) :

  • Importer des cookies depuis un Chrome de debug dans lequel vous êtes déjà connecté
  • Parcourir les formulaires de login classiques avec snapshots et fill/click
  • Gérer l’authentification par cookies, l’auth HTTP basic et le rafraîchissement de tokens

Pour des flux OAuth ou 2FA complexes, une intervention humaine peut rester nécessaire lors de la configuration initiale, après quoi agent-browser peut réutiliser l’état authentifié sauvegardé.

Proxy support and network configuration

Si vous devez faire transiter le trafic via un proxy (pour du geo-testing, de la limitation de débit ou un environnement d’entreprise), utilisez les options décrites dans references/proxy-support.md :

• Proxy HTTP/HTTPS via option CLI

  agent-browser --proxy "http://proxy.example.com:8080" open https://example.com
  

• Configuration via variables d’environnement

  export HTTP_PROXY="http://proxy.example.com:8080"
  export HTTPS_PROXY="https://proxy.example.com:8080"
  agent-browser open https://example.com
  

• Proxy SOCKS

  export ALL_PROXY="socks5://proxy.example.com:1080"
  agent-browser open https://example.com
  

Profiling and performance tracing

Pour l’automatisation de tests et les analyses de performances, agent-browser peut capturer des traces de performances Chrome (voir references/profiling.md) :

# Démarrer le profiling
agent-browser profiler start

# Exécuter votre scénario
agent-browser open https://example.com
agent-browser click @e1
agent-browser wait 1000

# Arrêter et sauvegarder la trace
agent-browser profiler stop ./trace.json

Vous pouvez ouvrir le fichier trace.json résultant dans Chrome DevTools (onglet Performance) ou dans des visualiseurs compatibles pour analyser l’exécution JavaScript, le rendu et les événements de timing utilisateur.

Video recording for debugging and documentation

agent-browser peut enregistrer une vidéo de la session navigateur, ce qui est utile pour diagnostiquer des automatisations défaillantes ou créer des guides pas à pas (voir references/video-recording.md) :

# Démarrer l’enregistrement
agent-browser record start ./demo.webm

# Effectuer des actions
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e1

# Arrêter l’enregistrement
agent-browser record stop

Vous pouvez intégrer ces enregistrements .webm dans votre documentation, les partager avec votre équipe ou les joindre à des rapports de bug.

Using templates for common workflows

Le dépôt inclut des modèles de scripts shell dans le répertoire templates/ pour vous aider à construire des workflows réutilisables :

• templates/form-automation.sh – pattern structuré pour remplir et soumettre des formulaires
• templates/authenticated-session.sh – exemple de connexion et de persistance d’état de session
• templates/capture-workflow.sh – pattern pour snapshotter ou enregistrer un parcours multi-étapes

Vous pouvez copier et adapter ces scripts à votre propre environnement, à vos jobs de CI ou à vos pipelines d’agents.

FAQ

Quels problèmes agent-browser résout-il par rapport à de simples clients HTTP ?

agent-browser contrôle une véritable instance Chrome/Chromium via CDP. Cela lui permet de gérer :

• Le rendu côté client et le JavaScript complexe
• Les single-page apps qui dépendent des APIs navigateur
• De vraies interactions utilisateur (clics, saisie, frappes clavier)
• Le timing visuel, le comportement de rendu et les traces de performance

Si vous avez seulement besoin de HTML ou de JSON bruts depuis des endpoints simples, un client HTTP peut suffire. Pour tout ce qui doit se comporter comme un utilisateur réel dans un navigateur, agent-browser est plus adapté.

Comment installer Chrome ou Chromium pour agent-browser ?

Après avoir installé la CLI avec npm, Homebrew ou Cargo, exécutez :

agent-browser install

Cette commande télécharge et configure une version compatible de Chrome/Chromium qu’agent-browser peut piloter via CDP. Lorsqu’une nouvelle version est publiée, mettez à jour avec :

agent-browser upgrade

agent-browser peut-il réutiliser ma session de navigateur déjà connectée ?

Oui. references/authentication.md explique comment démarrer Chrome avec --remote-debugging-port et importer les cookies d’une session dans laquelle vous êtes déjà connecté. Une fois les cookies importés, vous pouvez sauvegarder cet état authentifié avec agent-browser state save et le restaurer ultérieurement sans rejouer tout le parcours de login.

agent-browser est-il adapté au CI et aux tests automatisés ?

Oui. agent-browser est un outil CLI qui fonctionne bien dans des environnements automatisés, dès lors que Chrome/Chromium est disponible. Vous pouvez :

• Exécuter des parcours de bout en bout dans vos suites de tests
• Capturer des traces de performance pendant les builds
• Enregistrer des vidéos des scénarios en échec

En CI, utilisez la méthode d’installation adaptée à votre image de build (npm, Homebrew ou Cargo), puis scripttez vos parcours avec des scripts shell ou votre framework d’agents.

Comment agent-browser aide-t-il les agents IA à gérer des pages complexes ?

Plutôt que de renvoyer le DOM complet, agent-browser fournit des snapshots compacts avec des @refs stables pour les éléments importants (liens, boutons, champs de saisie, etc.). Cela réduit drastiquement l’usage de tokens et facilite pour un agent IA :

• La compréhension de la structure de la page
• La sélection du bon élément via sa ref
• L’émission de commandes précises (click, fill, press)

references/snapshot-refs.md détaille la génération des refs, quand les rafraîchir et les bonnes pratiques pour une automatisation robuste.

agent-browser prend-il en charge les proxys et réseaux d’entreprise ?

Oui. Vous pouvez configurer des proxys HTTP, HTTPS et SOCKS soit via des options CLI (--proxy), soit via des variables d’environnement (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY). references/proxy-support.md couvre la configuration de base, les proxys avec authentification, les règles de contournement et les conseils de dépannage.

Par où commencer dans le dépôt pour en savoir plus ?

Pour une prise en main pratique d’agent-browser :

• Commencez par SKILL.md pour une vue d’ensemble et un quick start
• Lisez references/commands.md pour la liste complète des commandes et options
• Consultez references/authentication.md, references/session-management.md, references/snapshot-refs.md, references/profiling.md et references/video-recording.md pour les sujets ciblés
• Explorez le répertoire templates/ pour des scripts de workflows prêts à l’emploi que vous pouvez adapter à vos propres cas d’usage