Tutoriel Browser Use : ouvrir des pages, cliquer sur des boutons et extraire des données avec un agent IA

Après uvx browser-use install, le vrai blocage arrive souvent avec la task. Si vous écrivez seulement « ouvre le site et regarde », l’agent ne sait pas ce qu’il doit accomplir. Il peut tourner en boucle, deviner ou s’arrêter trop tôt.

Browser Use est une bibliothèque Python open source qui permet à une IA de contrôler un navigateur Chromium pour automatiser des tâches web. Elle peut tourner en local ou dans un environnement self-hosted, sans dépendre de Browser Use Cloud. Si vous connaissez déjà le concept de Browser Agent, ce tutoriel vous mène de l’installation à la première tâche réussie, avec configuration de sécurité, lecture des résultats et débogage.

Browser Use en une phrase

Browser Use est une Python library for AI browser automation. Elle permet à un LLM Agent d’utiliser le navigateur comme une personne : naviguer, cliquer, saisir du texte, faire défiler, extraire des données et prendre des captures.

Son positionnement est local ou self-hosted, sans dépendance à Browser Use Cloud. La bibliothèque open source et le Cloud Agent n’utilisent pas la même API. Ici, on reste sur l’entrée open source ; les capacités du Cloud SDK comme structured output, human-in-the-loop ou live preview ne sont pas couvertes.

Si vous vous demandez encore « qu’est-ce qu’un Browser Agent ? », commencez par l’article de concept Browser Agent quand il sera publié. Si le concept est clair, ce guide répond à la question pratique : comment le faire tourner maintenant ?

Installation et préparation : de uv à la clé API

Au 2026-06-30, le README officiel et le quickstart décrivent le flux suivant :

1. Version Python requise

Browser Use nécessite Python 3.11 ou plus récent. L’exemple du quickstart officiel crée un venv en Python 3.12, mais vous pouvez choisir selon votre environnement.

2. Installer uv (recommandé)

uv est un gestionnaire de paquets Python moderne développé par Astral. Si uv n’est pas encore installé :

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Initialiser le projet et installer browser-use

# Créer le dossier du projet
mkdir my-browser-use
cd my-browser-use

# Initialiser le projet
uv init

# Installer browser-use avec les dépendances core
uv add "browser-use[core]"

# Synchroniser les dépendances
uv sync

Si vous n’utilisez pas uv, pip fonctionne aussi :

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

pip install "browser-use[core]"

4. Installer l’environnement Chromium

Browser Use s’appuie sur Playwright. Il faut donc installer Chromium :

uvx browser-use install

Cette commande télécharge et configure Chromium pour permettre à l’agent de lancer une instance de navigateur.

5. Configurer la clé API

Browser Use doit se connecter à un LLM pour comprendre la tâche et prendre des décisions. Le quickstart officiel recommande ChatBrowserUse, un modèle conçu pour les tâches navigateur.

Créez un fichier .env à la racine du projet :

# .env
BROWSER_USE_API_KEY=your_api_key_here

Si vous utilisez OpenAI, Anthropic, Google Gemini ou Ollama en local, renseignez la clé correspondante :

OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GOOGLE_API_KEY=your_google_key

Premier script : le modèle minimal

Le script minimal contient trois parties : importer les modules, créer l’Agent, exécuter la tâche.

from browser_use import Agent, Browser, ChatBrowserUse
import asyncio

async def main():
    # Créer une instance de navigateur (visible pendant le débogage)
    browser = Browser(headless=False)

    # Créer l'instance LLM
    llm = ChatBrowserUse()

    # Créer l'Agent
    agent = Agent(
        task="Ouvre quotes.toscrape.com, fais défiler d'un écran, clique sur le bouton 'Next', puis extrais tous les textes de quotes et leurs auteurs sur la deuxième page",
        llm=llm,
        browser=browser
    )

    # Exécuter la tâche avec une limite d'étapes
    history = await agent.run(max_steps=20)

    # Fermer le navigateur
    await browser.close()

if __name__ == "__main__":
    asyncio.run(main())

Ce script fait plusieurs choses :

1. Browser(headless=False) : affiche la fenêtre du navigateur pour faciliter le débogage. Une fois le test terminé, vous pouvez passer à headless=True.
2. ChatBrowserUse() : utilise le modèle navigateur officiel. Vous pouvez aussi passer à ChatOpenAI(model="gpt-4o") ou à un autre modèle.
3. task doit être concret : n’écrivez pas « ouvre le site et regarde ». Écrivez plutôt « navigue vers X URL, fais défiler, clique sur le bouton Y, extrais le contenu Z ». Une tâche vague provoque des boucles ou des arrêts prématurés.
4. max_steps=20 : limite l’agent à 20 actions. Pour une première tâche, 10 à 20 étapes permettent de déboguer sans laisser l’agent insister sur une action bloquée.

Lancez le script :

uv run python main.py

Ne laissez pas l’agent tourner sans fin : max_steps est la ligne de sécurité

max_steps limite le nombre d’étapes d’exécution. La valeur officielle par défaut est 100, mais pour une première tâche, baissez-la plutôt à 10-20.

Pourquoi cette limite compte :

• L’agent peut rencontrer un clic impossible, une page lente, une popup ou un élément masqué, puis répéter la même action.
• Sans limite, il peut consommer temps et tokens sans progresser.
• L’objectif de la première tâche est de valider le fonctionnement, pas d’obtenir un workflow parfait. Une limite courte fait remonter les problèmes plus vite.

Réglages conseillés :

# Première tâche : 10 à 20 étapes
await agent.run(max_steps=20)

# Tâche plus complexe : ajuster si nécessaire, mais éviter de dépasser 50 au début
await agent.run(max_steps=50)

Configuration de départ sûre pour débuter

Ne commencez pas avec votre compte principal connecté, et ne laissez pas l’agent naviguer librement vers n’importe quel site. Une configuration sûre comprend :

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

1. Mode debug headless=False

browser = Browser(headless=False)

La fenêtre du navigateur est visible. Vous pouvez voir si l’agent clique au mauvais endroit, si la page reste bloquée ou si la consigne est imprécise. Une fois le débogage terminé, passez à headless=True.

2. Limiter la navigation avec allowed_domains

browser = Browser(
    headless=False,
    allowed_domains=["quotes.toscrape.com"]
)

allowed_domains empêche l’agent de naviguer vers d’autres domaines. Si la tâche concerne un seul site, gardez cette limite.

Browser Use prend en charge les wildcards de sous-domaine comme allowed_domains=["*.example.com"], mais pas les wildcards de TLD. allowed_domains=["example.*"] ne sera pas reconnu. Pour un site fixe, le plus stable reste d’écrire le domaine complet :

allowed_domains=["quotes.toscrape.com", "github.com"]

3. Utiliser un profil isolé, pas votre Chrome principal

browser = Browser(
    headless=False,
    user_data_dir="./browser_profile"
)

L’agent crée un profil de navigateur séparé. Il n’accède pas aux cookies, sessions ou données sensibles de votre Chrome principal. Cette première leçon utilise uniquement des pages publiques.

4. Ne pas utiliser disable_security

Le paramètre disable_security désactive des protections du navigateur. La documentation officielle le marque comme non recommandé. Si vous le voyez dans un autre tutoriel, passez cette partie.

Lire le résultat : voir le navigateur bouger ne suffit pas

agent.run() renvoie un AgentHistoryList. Plusieurs méthodes permettent de lire le résultat et le déroulé :

history = await agent.run(max_steps=20)

# Résultat final
result = history.final_result()
print("Résultat final :", result)

# Contenu extrait
extracted = history.extracted_content()
print("Contenu extrait :", extracted)

# Liste des erreurs
errors = history.errors()
print("Erreurs :", errors)

# Présence d'erreurs
if history.has_errors():
    print("La tâche a rencontré des erreurs")

# Liste des URL visitées
urls = history.urls()
print("URL visitées :", urls)

# Chemins des captures d'écran
screenshots = history.screenshot_paths()
print("Captures :", screenshots)

# Noms des actions exécutées
actions = history.action_names()
print("Actions :", actions)

# Nombre total d'étapes
steps = history.number_of_steps()
print("Étapes :", steps)

Erreur fréquente au début : regarder la fenêtre bouger et supposer que la tâche a réussi. Si final_result() est vide, l’agent s’est peut-être arrêté trop tôt ou la tâche était mal formulée. Si errors() contient des entrées, commencez par les lire.

Première série de tâches : ouvrir, cliquer, extraire

Utilisez quotes.toscrape.com comme premier terrain d’essai. C’est un site public conçu pour l’entraînement au scraping, sans connexion, avec une structure simple.

Tâche 1 : ouvrir et faire défiler

agent = Agent(
    task="Ouvre quotes.toscrape.com et fais défiler d'un écran",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=10)
print("URL visitées :", history.urls())

Tâche 2 : cliquer sur un bouton

agent = Agent(
    task="Ouvre quotes.toscrape.com et clique sur le bouton 'Next' en bas de la page",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=10)
print("Réussite :", history.is_successful())

Tâche 3 : extraire du contenu

agent = Agent(
    task="Ouvre quotes.toscrape.com et extrais tous les textes de quotes et leurs auteurs sur la première page",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=15)
extracted = history.extracted_content()
print("Contenu extrait :", extracted)

Tâche 4 : combiner les actions

agent = Agent(
    task="Ouvre quotes.toscrape.com, clique sur le bouton 'Next', puis extrais tous les textes de quotes et leurs auteurs sur la deuxième page",
    llm=ChatBrowserUse(),
    browser=Browser(headless=False, allowed_domains=["quotes.toscrape.com"])
)
history = await agent.run(max_steps=20)
print("Résultat final :", history.final_result())
print("Erreurs :", history.errors())

Où regarder après un échec

Quand l’agent renvoie un résultat vide, une erreur ou reste bloqué, suivez cette liste :

1. Le clic échoue

• Vérifiez si history.errors() contient “click failed” ou “element not found”
• Ajoutez un fallback clavier dans la tâche : « si le clic échoue, utilise Tab pour trouver le bouton, puis appuie sur Enter »
• Regardez history.screenshot_paths() pour savoir si l’élément était visible

2. L’extraction est vide

• Vérifiez history.urls() pour confirmer que la page s’est bien ouverte
• Regardez history.screenshot_paths() pour voir l’état de la page
• Assurez-vous que la tâche est précise : « extraire tous les textes de quotes et leurs auteurs », pas « regarder le contenu »

3. La page bloque

• Vérifiez si allowed_domains a bloqué une navigation
• Vérifiez la connexion réseau et le temps de chargement
• Réduisez max_steps ou ajoutez un comportement de timeout : « si la page ne charge pas en 10 secondes, retourne à l’accueil »

4. Le résultat est incomplet

• Vérifiez si max_steps a arrêté trop tôt
• Regardez history.number_of_steps() pour connaître le nombre d’étapes utilisées
• Reformulez la tâche et découpez-la en sous-tâches

5. Toute la tâche échoue

• Vérifiez que la clé API dans .env est correcte
• Confirmez que le modèle est pris en charge : ChatBrowserUse, OpenAI, Anthropic, Google Gemini ou Ollama local
• Vérifiez si la tâche est trop abstraite : remplacez « ouvre le site et regarde » par des actions concrètes

Agent beta vs API stable : deux entrées

Au 2026-06-30, le README officiel décrit deux chemins d’import pour l’Agent :

API stable

from browser_use import Agent, Browser

C’est l’entrée stable. Si vous utilisiez déjà Browser Use, vous pouvez continuer avec ce chemin.

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

API beta (0.13)

from browser_use.beta import Agent, BrowserProfile, ChatBrowserUse

C’est le beta agent 0.13, appuyé par un Rust core et un browser harness. Le README officiel indique que les anciens utilisateurs peuvent rester sur l’API stable, tandis que les nouveaux peuvent essayer la beta.

Si vous hésitez, vérifiez le README officiel actuel. Ce guide utilise des exemples stables ; l’API beta peut être différente.

Open source ou Cloud : connaître la limite

Ce guide utilise la bibliothèque open source Browser Use en local.

Browser Use Cloud est un service hébergé avec une API différente :

• Le Cloud SDK utilise actuellement l’API v3
• Cloud fournit structured output, human-in-the-loop, live preview, persistent profiles et d’autres fonctions de production
• Le SDK Python/TypeScript Cloud n’est pas compatible avec l’API de la bibliothèque open source

Quand envisager Cloud :

• Déploiement en production ou environnement hébergé
• Besoins avancés comme stealth, CAPTCHA ou proxy, non couverts ici
• Comptes multiples, profils persistants et collaboration d’équipe

Ce guide reste sur l’entrée locale. L’utilisation de Cloud et la tarification relèvent d’un autre article.

Prochaines étapes

Ce tutoriel couvre l’entrée locale dans Browser Use : installation, clés API, script minimal, ouverture de page, clic sur bouton, extraction d’informations et débogage.

Bonnes pistes ensuite :

• Déjà publié : guide pratique OpenClaw pour l’automatisation navigateur, Computer-Use Agent : laisser l’IA utiliser votre ordinateur, guide des plugins MCP
• Sujets à venir : Playwright MCP avec Claude, Codex et Cursor ; ingénierie Stagehand ; choix d’outils Browser Use ; sessions connectées et authentification ; infrastructure cloud ; conformité et sécurité
• Documentation officielle : quickstart, prompting guide, browser config

Commencez par faire réussir une tâche sur quotes.toscrape.com ou une page GitHub publique, puis passez seulement ensuite aux sessions connectées et à Cloud.