Guide

Browser-use, un agent LLM qui pilote le navigateur

Browser-use est une bibliothèque Python qui confie un navigateur à un modèle de langage. Fonctionnement, coût en tokens, sécurité et alternatives.

L'équipe CodeWorlds17 min de lecture ·

Pratique HTML et CSS dans des leçons interactives avec un éditeur de code.

Crée un compte gratuit→
Dans cet article9

Browser-use est une bibliothèque Python qui confie à un modèle de langage le contrôle d'un navigateur : le modèle clique, remplit des formulaires et lit des pages pour lesquelles il n'existe pas d'API officielle. La version actuelle est la 0.13.8, publiée le 16 août 2026, la licence est MIT, et le dépôt browser-use/browser-use compte environ 109,9 mille étoiles. Le prix de ce confort, ce sont les tokens et le manque de fiabilité.

Ce que fait vraiment browser-use

Le cœur de la bibliothèque est une boucle. L'agent collecte l'état de la page, l'envoie au modèle avec le texte de la tâche et un historique réduit des étapes précédentes, reçoit en retour une liste d'actions, les exécute dans le navigateur et recommence. La boucle s'arrête quand le modèle appelle l'action done, quand la limite d'échecs est atteinte, ou quand le délai par étape expire.

L'interface est courte. Agent(task=..., llm=...) plus await agent.run() constitue tout le programme minimal. Les autres paramètres, et le constructeur en compte bien plus de cinquante, servent à ajuster cette boucle : combien d'actions par étape, quelle quantité d'historique, s'il faut joindre une capture d'écran, combien de temps attendre le réseau, quels domaines sont autorisés.

L'ensemble des actions disponibles pour le modèle est fermé et défini dans le registre d'outils. Les actions évidentes sont là : navigate, click, input, scroll, send_keys, go_back, switch, close, select_dropdown et dropdown_options. Il y a aussi des opérations de lecture : extract fait passer le markdown de la page par un modèle, search_page cherche un motif dans le texte à la manière de grep, find_elements interroge le DOM avec un sélecteur CSS. Il y a des actions sur les fichiers, write_file, read_file, replace_file, save_as_pdf et screenshot, ainsi que evaluate, qui exécute du JavaScript arbitraire sur la page. À la fin se trouve done, qui clôt l'exécution et renvoie le résultat.

Dans la version 0.13, le navigateur est piloté directement via le Chrome DevTools Protocol. Playwright n'apparaît plus parmi les dépendances du paquet ; cdp-use et browser-harness y figurent. Les noms de champs de BrowserProfile sont restés proches de ceux de Playwright, parce que le profil hérite de classes décrivant les arguments de lancement et de contexte, mais la couche d'exécution est celle du projet.

Ce que browser-use ne fait pas compte tout autant. Ce n'est pas un framework de collecte de contenu à grande échelle, c'est le rôle de Firecrawl. Ce n'est pas un exécuteur de tests, ce rôle revient à Playwright. Il n'isole pas le code exécuté, c'est à quoi sert E2B. Ce n'est pas non plus un framework d'agents généraliste comme LangChain, même s'il peut y être intégré comme un simple outil.

Version, licence et santé du projet

La licence ne laisse aucun doute, ce qui est un confort rare dans cette catégorie d'outils. Le fichier LICENSE du paquet publié contient le texte MIT complet avec la mention « Copyright (c) 2024 Gregor Zunic ». Le classifieur PyPI indique License :: OSI Approved :: MIT License, et l'API GitHub renvoie l'identifiant SPDX MIT pour le dépôt. Trois sources indépendantes concordent, il n'y a pas de répertoire séparé avec des conditions commerciales et aucune clause limitant l'hébergement concurrent.

Le projet a démarré le 31 octobre 2024 et a grandi vite. Aujourd'hui il compte environ 109,9 mille étoiles, 12 084 forks et 363 issues ouvertes, il n'est pas archivé, et la dernière modification de la branche principale date du 21 août 2026. Le rythme des versions est élevé et l'interface bouge entre les versions mineures : Controller est un alias de Tools, Browser un alias de BrowserSession, et des paramètres du constructeur continuent d'arriver et de changer de valeur par défaut. Épinglez la version exacte et traitez chaque mise à jour comme un changement qui impose de retester vos scénarios.

Un problème opérationnel distinct tient à la façon dont les dépendances sont déclarées. Le paquet les épingle avec un signe égal plutôt qu'avec une plage : openai==2.16.0, anthropic==0.76.0, pydantic==2.12.5, mcp==1.26.0, httpx==0.28.1 et plusieurs dizaines d'autres. Si votre application utilise son propre client OpenAI ou Claude dans une autre version, l'installation dans un seul environnement virtuel se terminera par un conflit. Un environnement séparé ou un processus séparé n'est pas excessif ici, c'est une exigence pratique. La version minimale de Python est la 3.11.

Un cloud commercial fonctionne autour de la bibliothèque à browser-use.com. La facturation est basée sur des crédits : il y a une dotation mensuelle de crédits liée à l'offre, les offres annuelles reçoivent leurs crédits dès le départ, et les crédits sont dépensés sur n'importe quel produit aux tarifs d'usage publiés. Une voie séparée couvre un pool annuel de crédits, des accords de niveau de service et des conditions de conservation des données. Je ne cite pas de chiffres, parce que la page des tarifs est rendue côté client et ne peut pas être lue de façon fiable à partir de la réponse brute du serveur.

Deux points à la frontière entre open source et cloud méritent d'être nommés clairement. D'abord, si vous créez un agent sans passer de modèle, la bibliothèque se rabat sur ChatBrowserUse, le fournisseur propre au projet, qui exige une BROWSER_USE_API_KEY. Le comportement par défaut mène donc à un service payant plutôt qu'au modèle que vous avez déjà. Ensuite, la télémétrie est activée par défaut : la variable ANONYMIZED_TELEMETRY vaut true par défaut, et BROWSER_USE_CLOUD_SYNC reprend cette valeur par défaut. Un client PostHog figure parmi les dépendances. Si l'agent circule dans des systèmes internes d'entreprise, mettez les deux variables à false avant la première exécution.

Comment l'état de la page parvient au modèle

Cette question détermine votre facture de tokens, donc la réponse mérite d'être connue précisément. Browser-use n'envoie pas de HTML brut au modèle et ne se repose pas uniquement sur une image. Il construit sa propre représentation textuelle simplifiée en fusionnant trois sources du Chrome DevTools Protocol : DOM.getDocument fournit la structure de l'arbre, DOMSnapshot.captureSnapshot ajoute la géométrie et les styles calculés, et Accessibility.getFullAXTree apporte les rôles et les noms d'accessibilité.

À partir de l'arbre fusionné, le sérialiseur ne garde que les nœuds importants pour l'agent : éléments interactifs, éléments scrollables et frames. Chaque nœud interactif reçoit un numéro d'ordre et entre dans le texte sous une forme proche du HTML, précédée de cet index entre crochets. Un astérisque devant l'index signale un élément apparu depuis l'étape précédente, ce qui permet au modèle de remarquer qu'un clic a ouvert une boîte de dialogue modale.

[12]<button type=submit aria-label=Search>Search</button>
[13]<input type=text name=q placeholder=Enter a phrase />
*[14]<div role=dialog aria-label=Consent>Privacy settings</div>

L'ensemble des attributs copiés dans cette représentation est fixe et a des conséquences sur le coût. Par défaut, il s'agit de title, type, checked, id, name, role, value, placeholder, data-date-format, alt, aria-label, aria-expanded, data-state, aria-checked, aria-valuemin, aria-valuemax, aria-valuenow et aria-placeholder. L'attribut class est commenté dans le code source, donc volontairement ignoré, car sur une page Tailwind il consommerait à lui seul l'essentiel de la fenêtre de contexte. La liste peut être remplacée avec le paramètre include_attributes.

La sérialisation a un plafond strict. Le paramètre max_clickable_elements_length vaut 40 000 caractères par défaut et tronque la représentation au-delà de ce seuil. Sur une page avec une longue liste de résultats, cela signifie que le modèle en voit le début plutôt que l'ensemble, et c'est la cause la plus fréquente de la phrase « je n'ai pas trouvé cet élément » alors que l'élément est bien sur la page.

La capture d'écran est une couche supplémentaire, contrôlée par use_vision et activée par défaut. L'image voyage vers le modèle comme donnée dans le message, et sa résolution est régie par vision_detail_level avec les valeurs auto, low et high, ainsi que par llm_screenshot_size, qui prend un tuple largeur et hauteur. Pour les modèles de la famille Claude Sonnet, la bibliothèque fixe elle-même 1400 sur 850 pixels, car au-delà de ce seuil l'image est redimensionnée côté fournisseur et vous payez des pixels que le modèle ne voit jamais en pleine résolution.

Premier agent et contrôle de l'exécution

L'installation et le démarrage se présentent ainsi.

Bash
# a separate environment, because the dependencies are hard pinned
python -m venv .venv && source .venv/bin/activate

# pin the exact version
pip install "browser-use==0.13.8"

# switch telemetry off before the first run
export ANONYMIZED_TELEMETRY=false
export BROWSER_USE_CLOUD_SYNC=false

# your own provider key, not the browser-use cloud
export OPENAI_API_KEY=sk-...

Un programme avec une configuration réaliste, plutôt qu'un extrait marketing, ressemble à ceci.

Python
import asyncio

from browser_use import Agent, BrowserProfile, ChatOpenAI

profile = BrowserProfile(
    headless=True,
    allowed_domains=['*.example.com'],
    block_ip_addresses=True,
    wait_between_actions=0.2,
    wait_for_network_idle_page_load_time=1.0,
    highlight_elements=False,
    user_data_dir=None,
)

async def main():
    agent = Agent(
        task='Find the plan in the pricing table with a 50 user limit and save its name.',
        llm=ChatOpenAI(model='gpt-5.5'),
        browser_profile=profile,
        sensitive_data={'https://*.example.com': {'password': 'secret'}},
        initial_actions=[{'navigate': {'url': 'https://example.com/pricing'}}],
        max_actions_per_step=3,
        max_failures=3,
        step_timeout=120,
        calculate_cost=True,
    )
    history = await agent.run(max_steps=20)
    print(history.final_result())
    print(history.number_of_steps(), history.urls())

asyncio.run(main())

Trois paramètres de cet exemple méritent un commentaire. allowed_domains est la seule vraie barrière qui empêche l'agent de suivre un lien du pied de page et de commencer à agir hors de votre service. sensitive_data substitue les valeurs uniquement à l'intérieur du navigateur, de sorte que le modèle reçoit un nom symbolique à la place du mot de passe. L'argument max_steps passé à run est le dernier fusible de coût et n'a aucune valeur par défaut raisonnable que l'on puisse laisser sans y réfléchir.

L'objet d'historique renvoyé par run expose final_result, is_done, errors, urls, model_actions, number_of_steps et structured_output. Si vous passez output_model_schema avec un modèle Pydantic, le résultat revient sous forme d'objet plutôt que de texte à analyser avec une expression régulière.

Coût en tokens et comment le réduire

Le mécanisme de coût est simple et désagréable. Chaque étape est un appel de modèle distinct qui transporte l'instruction système, le texte de la tâche, l'historique et la représentation complète de la page courante, plus une image quand use_vision est activé. Une tâche de dix étapes représente dix appels de ce type. Une page très chargée en navigation peut produire à elle seule bien plus de dix mille tokens de description d'état, et cela se répète à chaque étape.

La bibliothèque offre plusieurs leviers, et tous sont de vrais paramètres du constructeur. Mettre flash_mode à true retire les champs de raisonnement du schéma de réponse et désactive la planification, ce qui raccourcit la réponse du modèle. Mettre use_thinking à false donne une variante plus douce. Mettre use_vision à false supprime l'image, généralement la plus grosse économie à elle seule. max_history_items limite le nombre d'étapes précédentes conservées dans le contexte, et message_compaction active le repliement de l'historique plus ancien. Abaisser max_clickable_elements_length à quelques milliers de caractères limite la description de la page, au prix d'une moindre visibilité sur les éléments plus bas. Réduire include_attributes à trois ou quatre entrées supprime le reste.

Python
from browser_use import Agent, ChatOpenAI

agent = Agent(
    task='Collect the names and prices of the first ten products in the list.',
    llm=ChatOpenAI(model='gpt-5.5'),
    page_extraction_llm=ChatOpenAI(model='gpt-5.5-mini'),
    use_vision=False,
    use_thinking=False,
    use_judge=False,
    flash_mode=True,
    max_history_items=8,
    max_actions_per_step=5,
    max_clickable_elements_length=8000,
    include_attributes=['id', 'name', 'role', 'aria-label'],
    calculate_cost=True,
)

Deux actions décrites dans le code source comme ne coûtant rien côté modèle fonctionnent séparément de tout cela. search_page cherche un motif dans le texte de la page, éventuellement sous forme d'expression régulière et limité par un sélecteur CSS, tandis que find_elements renvoie les éléments correspondant à un sélecteur avec les attributs choisis. Les deux s'exécutent dans le navigateur et renvoient un court résultat au lieu de la page entière. Si la tâche se résume à vérifier qu'une chaîne donnée apparaît sur la page, indiquez dans le texte de la tâche que l'agent doit utiliser search_page, plutôt que de le laisser faire défiler à l'aveugle.

L'action extract est coûteuse par nature, car elle fait passer le markdown de la page par un modèle. C'est pourquoi page_extraction_llm existe : vous pouvez substituer un modèle moins cher, pour la seule extraction de données, à celui qui pilote l'agent. Par défaut les deux sont le même modèle, ce qui est la configuration la plus chère possible. Il est aussi utile de savoir que use_judge est activé par défaut et ajoute un appel qui évalue le résultat, tandis que calculate_cost est désactivé par défaut, donc sans l'activer vous ne voyez jamais dans le résumé ce que l'exécution a réellement coûté.

Des actions personnalisées plutôt que des clics

Le moyen le plus efficace de réduire le coût et d'augmenter la fiabilité est de retirer au modèle les parties de la tâche qui ne demandent aucune compréhension. Le registre d'outils permet d'ajouter votre propre action, que le modèle appelle par son nom et sa description, et dont le corps est du code Python ordinaire.

Python
from pydantic import BaseModel
from browser_use import Agent, ChatOpenAI, Tools

tools = Tools()

class OrderQuery(BaseModel):
    order_id: str

@tools.action(
    'Fetch the order status from the internal API by order number.',
    param_model=OrderQuery,
    domains=['*.example.com'],
)
async def order_status(params: OrderQuery) -> str:
    import httpx
    async with httpx.AsyncClient() as client:
        r = await client.get(f'https://api.example.com/orders/{params.order_id}')
        return r.json()['status']

agent = Agent(
    task='Check the status of order 88421 and describe it in one sentence.',
    llm=ChatOpenAI(model='gpt-5.5'),
    tools=tools,
)

Le décorateur accepte une description, un modèle de paramètres Pydantic optionnel, une liste de domaines limitant où l'action est disponible, et terminates_sequence, qui arrête les actions suivantes dans la même étape. Six clics transformés en un seul appel HTTP, ce sont six appels de modèle de moins et six occasions de se tromper en moins. Le même principe s'applique à l'action evaluate, qui exécute du JavaScript sur la page : si vous connaissez le sélecteur, un script déterministe est moins cher et plus fiable que de décrire au modèle ce qu'il doit cliquer.

Browser-use face aux alternatives

OutilFonctionnementQuand le choisir
browser-usele modèle pilote le navigateur via CDP, état sous forme d'arbre textueltâches ponctuelles, sites sans API, mises en page changeantes
Playwrightscript déterministe avec des sélecteursparcours répétables, tests, pipelines CI
Firecrawlrécupère une page et la convertit en markdowncollecte de contenu à grande échelle, sans clics
computer use chez OpenAI et Claudele modèle pilote un curseur par coordonnées sur une imageapplications sans DOM, bureau, cas limites
l'API officielle du serviceun appel HTTP avec un contrattoujours, quand une telle API existe

La dernière ligne n'est pas une plaisanterie. Un agent de navigateur est la réponse aux situations où une API manque ou n'est pas accessible. Là où il en existe une, l'agent perd sur tous les plans : coût, latence, répétabilité et testabilité. Browser-use fonctionne aussi bien comme outil de transition : vous laissez d'abord l'agent effectuer la tâche quelques fois, vous observez quelles actions il choisit, puis vous réécrivez le parcours stable sous forme de script.

Entre ces deux extrêmes se trouve Stagehand, qui permet de mélanger les deux dans un même script : là où un sélecteur est connu, vous l'écrivez, et vous gardez les instructions en langage naturel pour les parties qui changent. Cela répond exactement au problème de transition décrit plus haut, car il n'est pas nécessaire de tout réécrire d'un coup. Deux choses valent toutefois d'être connues : la mise en cache des actions, qui réduit le nombre d'appels au modèle, ne fonctionne qu'avec un navigateur hébergé par l'éditeur, et la version quatre a abandonné Playwright au profit de son propre client CDP et d'une extension Chrome, donc le code écrit pour la version trois ne se transpose pas à l'identique.

Erreurs courantes

Traiter l'agent comme une fonction. Le même modèle, la même tâche et la même page peuvent produire trois exécutions différentes. Si le résultat alimente un système de production, il vous faut un schéma de sortie, une vérification du résultat et une politique de nouvelle tentative, plutôt que de supposer que cette fois ça marchera.

Lancer sans allowed_domains. Une page peut contenir du texte adressé au modèle lui demandant d'aller ailleurs ou de faire autre chose. Avec un agent qui détient une session connectée, c'est un vrai vecteur d'attaque, et la liste de domaines autorisés, avec prohibited_domains et block_ip_addresses, est la première barrière et la moins chère.

Coller des mots de passe dans le texte de la tâche. Tout ce qui est placé dans le champ task voyage vers le fournisseur du modèle et finit dans les journaux. Les identifiants doivent aller dans sensitive_data, où les valeurs sont substituées uniquement à l'intérieur du navigateur.

Installer à côté du code de votre application. Les versions épinglées de openai, anthropic, pydantic et httpx finiront tôt ou tard par entrer en collision avec ce qu'utilise le reste du projet.

Laisser les valeurs par défaut du coût. Prêt à l'emploi, vous avez la vision activée, le raisonnement activé, le juge activé et le calcul du coût désactivé. C'est une configuration réglée pour la qualité de démonstration, pas pour la facture de fin de mois.

Aucune limite d'étapes. Sans max_steps, un agent qui tombe dans une boucle peut continuer à générer des appels de modèle aussi longtemps que le quota de votre fournisseur le permet.

FAQ

Browser-use va-t-il remplacer Playwright ?

Pas dans les cas où Playwright est le bon outil. Pour les tests et pour les parcours dont la mise en page ne change pas, un script déterministe est plus rapide, moins cher et donne des résultats répétables. Browser-use gagne là où la page est inconnue, changeante, ou si étendue que l'écriture des sélecteurs prendrait plus de temps que d'effectuer la tâche une fois.

Les index d'éléments sont-ils stables d'une étape à l'autre ?

Non. Les index sont attribués lors de la sérialisation de l'état courant et reconstruits après chaque action. C'est pourquoi cliquer sur un index qui n'existe plus renvoie un message indiquant que la page a peut-être changé et incite le modèle à rafraîchir l'état. Ne construisez pas votre propre logique sur l'idée que l'index 12 pointe toujours vers le même bouton.

Combien coûte une étape d'agent ?

Cela dépend de la page et de la configuration, donc citer un chiffre serait de la devinette. On peut toutefois le mesurer : activez calculate_cost=True, lancez la tâche sur votre page cible et comparez le résultat avec la même exécution en use_vision=False et avec un max_clickable_elements_length abaissé. Cette mesure prend un quart d'heure et vous donne un chiffre pour votre propre cas.

Puis-je utiliser browser-use sans clé du cloud browser-use ?

Oui. Passez votre propre modèle, par exemple ChatOpenAI, ChatAnthropic, ChatGoogle, ChatOllama ou ChatOpenRouter. La BROWSER_USE_API_KEY n'est nécessaire que si vous laissez en place le fournisseur par défaut ChatBrowserUse, ce qui arrive automatiquement si vous omettez le paramètre llm.

L'agent est-il sûr sur des pages avec du contenu généré par les utilisateurs ?

Pas tout seul. Le contenu de la page parvient au modèle comme partie du contexte, donc un commentaire de forum peut contenir une instruction visant l'agent. Restreignez les domaines, restreignez l'ensemble des actions au nécessaire, ne donnez pas à l'agent une session avec des droits que la tâche n'exige pas, et n'autorisez pas d'actions irréversibles sans confirmation de votre côté.

Peut-il fonctionner dans un conteneur sans affichage ?

Oui, BrowserProfile(headless=True) démarre le navigateur sans fenêtre, et cdp_url permet de se connecter à un navigateur qui tourne ailleurs. La liste complète des paramètres du profil est couverte par la documentation du projet, et le code source du registre d'actions se trouve dans le dépôt GitHub.

À lire aussi