Browser-Use en Python : créez des agents IA qui pilotent un vrai navigateur web

L'automatisation classique du navigateur casse dès qu'un site web change. Une classe CSS renommée, un tunnel de paiement redessiné, une bannière de cookies inattendue — et vos sélecteurs Playwright soigneusement écrits s'effondrent. Browser-Use inverse le modèle : au lieu de scripter chaque clic, vous confiez un vrai navigateur à un LLM et vous décrivez l'objectif. L'agent lit chaque page, décide quoi cliquer, saisir et extraire, et s'adapte quand la mise en page évolue.

Le projet est devenu le framework open source de référence pour les agents IA de navigation, avec plus de 79 000 étoiles GitHub et un rythme de publication soutenu en 2026 — l'équipe a livré Browser Use CLI 3.0 début juillet. Dans ce tutoriel, vous allez construire des agents de navigation en Python à partir de zéro : d'abord un agent de recherche, puis un extracteur de données structurées avec Pydantic, enfin un agent doté d'outils personnalisés et d'une gestion sûre des identifiants.

Si vous préférez TypeScript, nous avons couvert le versant JavaScript de ce domaine dans notre tutoriel Stagehand et Browserbase. Ici, ce sera 100 % Python.

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Python 3.11 ou plus récent installé
• uv comme gestionnaire de paquets (voir notre guide complet d'uv) — pip fonctionne aussi
• Une clé API pour au moins un fournisseur de LLM (OpenAI, Anthropic ou Google Gemini)
• Des bases en async/await en Python

Aucune expérience Playwright ou Selenium n'est requise — c'est justement tout l'intérêt.

Ce que vous allez construire

À la fin de ce tutoriel, vous aurez trois agents fonctionnels :

1. Un agent de recherche qui explore le web et résume ce qu'il trouve
2. Un extracteur structuré qui transforme Hacker News en modèles Pydantic validés
3. Un agent de tâches avec des outils personnalisés, qui enregistre les résultats sur disque et gère les connexions sans jamais exposer votre mot de passe au LLM

En chemin, vous comprendrez le fonctionnement de la boucle d'agent, la configuration du navigateur et comment garder des exécutions fiables et économiques.

Comment fonctionne Browser-Use

Browser-Use exécute un vrai navigateur Chromium et le pilote via le Chrome DevTools Protocol. À chaque étape, la bibliothèque :

1. Capture la page courante sous forme d'arbre DOM simplifié, avec une capture d'écran optionnelle
2. Envoie cet état à votre LLM avec la description de la tâche et l'historique
3. Reçoit une décision — cliquer sur l'élément 12, écrire dans l'élément 7, faire défiler, naviguer ou terminer
4. Exécute l'action, puis recommence

Comme le LLM voit la page comme du contenu plutôt que comme des sélecteurs fragiles, le même agent survit à des refontes qui tueraient un bot scripté. La contrepartie, c'est le coût et la latence : chaque étape est un appel LLM, d'où l'importance du choix du modèle et des limites d'étapes — nous verrons les deux.

Étape 1 : mise en place du projet

Créez un projet et installez la bibliothèque :

mkdir browser-agents && cd browser-agents
uv init
uv add browser-use python-dotenv pydantic

Browser-Use télécharge sa propre version de Chromium au premier lancement : aucune installation de navigateur séparée n'est nécessaire. Si vous préférez pip :

pip install browser-use python-dotenv pydantic

Créez un fichier .env avec la clé du fournisseur que vous comptez utiliser :

# .env — choisissez-en un (ou plusieurs)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

Étape 2 : votre premier agent

Créez first_agent.py :

import asyncio
 
from dotenv import load_dotenv
 
load_dotenv()
 
from browser_use import Agent, ChatOpenAI
 
 
async def main():
    llm = ChatOpenAI(model="gpt-5")
 
    agent = Agent(
        task=(
            "Find the number 1 post on Show HN today. "
            "Give me its title, points, and what the project does."
        ),
        llm=llm,
    )
 
    history = await agent.run()
    print(history.final_result())
 
 
if __name__ == "__main__":
    asyncio.run(main())

Lancez-le :

uv run python first_agent.py

Une fenêtre Chromium s'ouvre, l'agent navigue vers Hacker News, lit la page Show HN et affiche un résumé. Observez le terminal : chaque étape journalise le raisonnement de l'agent, l'action choisie et l'élément ciblé. Ce journal est votre principal outil de débogage.

Deux points méritent attention dans le code :

• load_dotenv() s'exécute avant l'import de browser_use. Dans certaines configurations, la bibliothèque lit les clés des fournisseurs au moment de l'import ; charger l'environnement d'abord est la bonne habitude.
• history.final_result() renvoie la réponse finale de l'agent sous forme de texte. L'objet history expose aussi chaque étape, chaque URL visitée et chaque capture d'écran — utile pour les audits.

Choisir un modèle

Browser-Use fournit ses propres wrappers de chat : changer de fournisseur revient à modifier une ligne :

from browser_use import ChatOpenAI, ChatAnthropic, ChatGoogle
 
llm = ChatOpenAI(model="gpt-5")                     # OpenAI
llm = ChatAnthropic(model="claude-sonnet-5")        # Anthropic
llm = ChatGoogle(model="gemini-3-flash-preview")    # Google, rapide et économique

Un schéma pratique : prototypez avec un modèle rapide et peu coûteux comme Gemini Flash, puis passez à un modèle plus puissant seulement si l'agent se perd sur des parcours complexes. Chaque étape étant un appel LLM, une tâche de 30 étapes avec un modèle onéreux chiffre vite.

Étape 3 : configurer le navigateur

Le navigateur par défaut fonctionne, mais les vrais projets exigent un contrôle du mode headless, de la taille de fenêtre et de la réutilisation de session. Passez une instance Browser à l'agent :

from browser_use import Agent, Browser, ChatOpenAI
 
browser = Browser(
    headless=False,                                # fenêtre visible pendant le développement
    window_size={"width": 1280, "height": 900},
)
 
agent = Agent(
    task="Compare the pricing pages of Vercel and Netlify and summarize the differences.",
    browser=browser,
    llm=ChatOpenAI(model="gpt-5"),
)

Passez headless=True sur serveur et en CI. Gardez la fenêtre visible pendant le développement — regarder l'agent travailler est le moyen le plus rapide de comprendre pourquoi il réussit ou échoue.

Sauter la partie ennuyeuse avec initial_actions

Si vous savez déjà où commence la tâche, ne gaspillez pas d'appels LLM en navigation. initial_actions exécute des actions déterministes avant que le modèle ne prenne la main :

agent = Agent(
    task="Summarize the theories described on this page.",
    initial_actions=[
        {"navigate": {"url": "https://en.wikipedia.org/wiki/Randomness"}},
    ],
    llm=llm,
)

C'est l'optimisation la plus simple qui existe : un navigate codé en dur ne coûte rien, tandis que demander au LLM « d'aller sur Wikipédia et chercher X » peut consommer trois ou quatre étapes.

Étape 4 : sortie structurée avec Pydantic

Les réponses en texte libre conviennent aux humains, mais les pipelines ont besoin de données. Passez un modèle Pydantic via output_model_schema et la réponse finale de l'agent sera validée contre ce schéma :

import asyncio
 
from dotenv import load_dotenv
 
load_dotenv()
 
from pydantic import BaseModel
 
from browser_use import Agent, ChatOpenAI
 
 
class Post(BaseModel):
    title: str
    url: str
    points: int
    comments: int
 
 
class TopPosts(BaseModel):
    posts: list[Post]
 
 
async def main():
    agent = Agent(
        task="Go to news.ycombinator.com and extract the top 5 posts.",
        llm=ChatOpenAI(model="gpt-5"),
        output_model_schema=TopPosts,
    )
 
    history = await agent.run()
    result = history.structured_output  # une instance de TopPosts
 
    for post in result.posts:
        print(f"{post.points:>4} pts  {post.title}")
 
 
if __name__ == "__main__":
    asyncio.run(main())

history.structured_output vous donne un objet TopPosts entièrement validé — pas de regex, pas de parsing JSON, pas de nettoyage du type « le modèle a ajouté un commentaire à la fin ». Si l'extraction ne peut pas satisfaire le schéma, vous le savez immédiatement plutôt qu'en aval.

Cette approche se combine naturellement avec un pipeline de scraping : pointez l'agent structuré vers des pages découvertes par un crawler comme celui de notre guide Crawlee en TypeScript, ou comparez-la avec l'approche par API de notre tutoriel Firecrawl.

Étape 5 : outils personnalisés

Les actions intégrées couvrent le navigateur. Les outils personnalisés permettent à l'agent d'agir en dehors du navigateur — écrire des fichiers, appeler vos API, interroger une base de données. Enregistrez-les avec la classe Tools :

import asyncio
import json
from pathlib import Path
 
from dotenv import load_dotenv
 
load_dotenv()
 
from browser_use import Agent, ChatOpenAI, Tools
 
tools = Tools()
 
 
@tools.action(description="Save extracted data as JSON to the local results folder.")
def save_results(filename: str, data: str) -> str:
    out = Path("results")
    out.mkdir(exist_ok=True)
    path = out / filename
    path.write_text(data, encoding="utf-8")
    return f"Saved to {path}"
 
 
@tools.action(description="Check whether a product price is below the alert threshold.")
def check_price_alert(price: float, threshold: float) -> str:
    if price <= threshold:
        return f"ALERT: price {price} is at or below threshold {threshold}"
    return f"No alert: price {price} is above threshold {threshold}"
 
 
async def main():
    agent = Agent(
        task=(
            "Look up the current price of the Raspberry Pi 5 8GB on the official "
            "raspberrypi.com site. Use check_price_alert with threshold 80. "
            "Then save the product name, price, and alert status with save_results "
            "as price_watch.json."
        ),
        llm=ChatOpenAI(model="gpt-5"),
        tools=tools,
    )
 
    await agent.run()
    print(json.loads(Path("results/price_watch.json").read_text()))
 
 
if __name__ == "__main__":
    asyncio.run(main())

La description du décorateur est ce que voit le LLM : rédigez-la comme une bonne docstring destinée à un développeur junior — ce que fait l'outil, et quand l'utiliser. Les outils peuvent être synchrones ou async, et les annotations de types des paramètres servent à construire le schéma que remplit le modèle.

C'est le même modèle mental d'appel d'outils que celui des frameworks d'agents comme le Claude Agent SDK — Browser-Use ajoute simplement un navigateur à la boucle.

Étape 6 : se connecter sans divulguer ses identifiants

La méthode naïve pour automatiser une connexion consiste à coller le mot de passe dans la tâche. Ne faites pas cela — la tâche part chez le fournisseur de LLM à chaque étape. Browser-Use résout le problème avec sensitive_data : vous passez des marqueurs, et les vraies valeurs sont substituées localement au moment de la saisie dans la page. Le modèle ne voit jamais que les noms des marqueurs.

agent = Agent(
    task=(
        "Log in to https://example.com/login with x_username and x_password, "
        "then open the account dashboard and report the current plan name."
    ),
    llm=llm,
    sensitive_data={
        "x_username": "anis@example.com",
        "x_password": "s3cr3t-from-env",
    },
)

Chargez les valeurs réelles depuis des variables d'environnement, jamais en dur. Pour l'authentification à deux facteurs, combinez cela avec un outil personnalisé (par exemple une action get_2fa_code qui interroge l'API de votre application d'authentification) et indiquez explicitement à l'agent, dans la tâche, d'utiliser cet outil au lieu d'essayer d'extraire des codes depuis les pages.

Étape 7 : des exécutions fiables et abordables

Quelques habitudes séparent les agents de démonstration des agents fiables :

Plafonnez les étapes. Un agent qui s'emballe coûte cher. agent.run(max_steps=25) fixe un plafond strict ; pour la plupart des tâches ciblées, 15 à 30 étapes suffisent largement.

Écrivez les tâches comme des specs, pas comme des intuitions. Comparez :

Mauvais : "Trouve des infos sur les prix des ordinateurs portables"
Bon :     "Va sur example-shop.com, cherche 'ultrabook 14 pouces',
           extrais le nom et le prix des 5 premiers résultats.
           Si une bannière de cookies apparaît, accepte-la.
           N'ouvre pas les pages produits."

Des étapes numérotées, des critères de réussite explicites et des instructions pour les obstacles connus (bannières de cookies, popups de newsletter) augmentent nettement le taux de réussite.

Journalisez tout. L'objet history enregistre chaque action, URL et capture d'écran. Persistez-le pour les exécutions non supervisées — quand un job nocturne échoue, le journal des étapes vous dit exactement où.

Ne passez en headless qu'après un fonctionnement correct en mode visible. La plupart des cas « l'agent est bloqué » sautent aux yeux après dix secondes d'observation de la fenêtre.

Tester votre implémentation

Vérifiez chaque brique de bout en bout :

1. uv run python first_agent.py — vous devriez voir des journaux étape par étape puis un résumé textuel du premier post Show HN.
2. Lancez l'extracteur structuré — il doit afficher cinq titres de Hacker News avec leurs points, et history.structured_output doit être une instance de TopPosts (ajoutez print(type(result)) pour le confirmer).
3. Lancez l'agent à outils — un fichier results/price_watch.json doit exister et se parser comme du JSON valide.

Si les trois passent, vous disposez de la panoplie complète : perception, extraction structurée et effets de bord.

Dépannage

L'agent tourne en boucle sur la même page. La tâche est probablement ambiguë. Ajoutez des critères de fin explicites (« termine quand tu as extrait 5 éléments ») et abaissez max_steps pour que les échecs échouent vite.

Erreurs d'authentification du fournisseur. Vérifiez que le nom de la clé correspond au wrapper : OPENAI_API_KEY pour ChatOpenAI, ANTHROPIC_API_KEY pour ChatAnthropic, GOOGLE_API_KEY pour ChatGoogle, et que load_dotenv() est appelé avant la création de l'agent.

Chromium ne démarre pas sur un serveur. Les machines Linux headless peuvent manquer de bibliothèques système ; installez les dépendances Chromium habituelles de votre distribution et activez toujours headless=True en environnement serveur.

La validation de la sortie structurée échoue. Simplifiez le schéma et précisez dans la tâche exactement quels champs remplir. Des champs optionnels avec des valeurs par défaut raisonnables absorbent mieux les pages désordonnées que des champs obligatoires stricts.

Les coûts dépassent les prévisions. Prototypez avec un modèle moins cher, utilisez initial_actions pour sauter les étapes de navigation et plafonnez max_steps. Le nombre d'étapes est le facteur de coût : une tâche bien spécifiée bouclée en 8 étapes coûte une fraction d'une tâche vague qui erre pendant 40.

Prochaines étapes

• Emballez votre agent dans un job planifié et envoyez les alertes vers un bot Telegram construit avec grammY
• Comparez l'approche pilotée par LLM avec le scripting déterministe de notre tutoriel scraper web IA avec Playwright et Claude
• Orchestrez plusieurs agents de navigation dans un système multi-agents plus large avec CrewAI ou le Claude Agent SDK pour Python
• Explorez l'offre cloud de Browser-Use si vous avez besoin de navigateurs hébergés avec proxys et gestion des captchas à grande échelle

Conclusion

Browser-Use fait du navigateur un outil de plus entre les mains d'un LLM. Vous avez installé la bibliothèque, lancé un agent de recherche, extrait des données validées avec des schémas Pydantic, étendu l'agent avec des outils Python personnalisés et géré des identifiants sans les divulguer au modèle. La boucle centrale — décrire l'objectif, laisser l'agent percevoir et agir, valider la sortie — reste la même, que vous surveilliez un prix ou pilotiez une flotte de jobs d'extraction nocturnes.

Le chemin pragmatique pour la suite : choisissez une petite tâche de navigation répétitive et agaçante que vous faites chaque semaine, rédigez-la comme une spécification précise, et confiez-la à un agent. Ce premier workflow automatisé vous en apprendra plus sur l'ingénierie « prompt comme spec » que n'importe quelle lecture.