browser-use: a library that turns a browser into an AI agent tool

browser-use is an open (MIT) library that gives an AI agent the ability to use a browser in the same way a person does: open pages, click on buttons, type text, fill out forms. You describe the task in words – the agent performs it himself, watching the page step by step and deciding what to do next.

The project was made by the Zurich team (Magnus Müller and Gregor Zunich) and as of September 2026 collected 111.7 thousand stars and 12.3 thousand forks on GitHub – that is, it is one of the most popular tools in the niche “give LLM browser”. Under the hood - Playwright to control Chromium.

“Tell your computer what to do and it will do it.” From the examples shown on the project page - filling out a questionnaire for work on a resume, uploading a list of subscribers to the CSV, comparing several products in a table.

## Two ways to use: CLI-skill vs Python library

The rule is simple: a one-time task through an already working agent → CLI-skill. Repetitive automation in code → Python library.**

### CLI Skill – If you already have an agent

If you are working with Claude Code, Codex, Cursor or another agent (including the already disassembled omp), you can once connect the browser-use as a skill and then just tell the agent what to do in the browser – “Put this video on YouTube”, “compare three laptops and make a table with prices”.

For installation, it is enough to insert such a prompt to the agent - he will set everything up himself:

Install or upgrade browser-use to the latest stable version with uv using
Python 3.12, run `browser-use skill install` to register the skill, and
connect it to my browser.

Python library – if you write your own code

For mass automation (scraping on a schedule, embedding a browser agent in your product, custom tools and system bumps, strict control over the response format), the library itself is used.

## Installation and first launch

You need Python 3.11+:

uv add browser-use
# или: pip install browser-use

The model API key is placed in .env:

# .env
BROWSER_USE_API_KEY=your-key
# GOOGLE_API_KEY=your-key
# ANTHROPIC_API_KEY=your-key

Minimum working agent:

import asyncio
from browser_use import Agent, ChatBrowserUse

async def main():
    agent = Agent(
        task="Find the number of stars of the browser-use repo",
        llm=ChatBrowserUse(model='openai/gpt-5.5'),
        # llm=ChatBrowserUse(model='bu-2-0-mini-preview'),  # своя оптимизированная модель
        # llm=ChatAnthropic(model='claude-opus-4-8'),
    )
    history = await agent.run()

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

## Which model to choose

The library itself is not a model - it connects any LLM through the ChatBrowserUse provider, which accepts a string of the form provider/model, and the same BROWSER_USE_API_KEY gives access to all of them - you do not need to enter separate OpenAI/Anthropic/Google keys:

from browser_use import Agent, ChatBrowserUse

llm = ChatBrowserUse(model='anthropic/claude-sonnet-4-6')
# или 'openai/gpt-5.5', 'google/gemini-3-pro'
agent = Agent(task='...', llm=llm)

Separately, the team has its own model ChatBrowserUse() (family bu-*), sharpened specifically for browser automation - according to their benchmarks, it passes tasks 3-5 times faster than competitors with comparable accuracy. There is also an open preview version - browser-use/bu-30b-a3b-preview; when using it, the library still substitutes its own system prompt for the agent, it is not necessary to prescribe it separately.

## Custom instruments

Any Python function can be turned into an action available to the agent through the @tools.action decorator:

from browser_use import Tools

tools = Tools()

@tools.action(description='Description of what this tool does.')
def custom_tool(param: str) -> str:
    return f"Result: {param}"

agent = Agent(
    task="Your task",
    llm=llm,
    browser=browser,
    tools=tools,
)

Description (description) is a must-see - it tells the model when to call the tool. In the function you can accept service objects runtime - for example, browser_session: BrowserSession (it is with this name of the parameter - otherwise the injection will not work), page_extraction_llm, file_system, available_file_paths. The result of the tool can be a simple string or object ActionResult with fields extracted_content, error, is_done, success and others.

## Structured conclusion

In order to obtain a failed object, rather than text, a Pydantic diagram is given via output_model_schema:

from pydantic import BaseModel

class Result(BaseModel):
    title: str
    price: float

agent = Agent(
    task="Extract the product title and price",
    llm=llm,
    output_model_schema=Result,
)
history = await agent.run()
result = history.structured_output  # Result | None

The final result in history is dealt with regardless of whether the agent reported a success: if the agent reported a failure, the response still returns - but is marked as an incomplete result, not a net successful result.

## Dealing with sensitive data

Logins and passwords can be transmitted so that the model will never see their real values - it receives only placeholder keys, and the library itself already at the browser level substitutes the real value:

agent = Agent(
    task="Log in and download the latest invoice",
    llm=llm,
    sensitive_data={
        "*.example.com": {
            "username": "my_user",
            "password": "my_pass",
        },
    },
)

The nested domain reference form ("*.example.com": {...}) is used if the permitted domains are not known in advance. Once sensitive_data is set, the library disables the processing of cross-domain iframes – this is a protection against the secret being accidentally entered into the field from another source.

## Permitted domains and other browser settings

You can limit what sites the agent can walk on through allowed_domains at the browser object:

from browser_use import Agent, Browser

browser = Browser(allowed_domains=["*.example.com"])
agent = Agent(task="...", llm=llm, browser=browser)

Of the other Agent(...) parameters that are often needed in practice:

• use_vision ("auto" by default) - mode of operation with screenshots: True - always attach a screenshot, False - never (and do not include the screenshot tool at all), "auto" - the tool is available, but the model refers to it as needed.
• vision_detail_level - Detailed screenshots: low/high/auto.
• **page_extraction_llm* is a separate (usually cheaper) model specifically for extracting content from a page.
• generate_gif - record the GIF with the debugging/demonstration agent actions.
• available_file_paths - a list of files on the disk that the agent can use (for example, a resume for a form).

## Open Source vs. Cloud

The library is completely free and runs on its own machine – but the team also has a paid cloud for production workload. Difference:

Open Agent (self-hosted)

• Free, working locally
• Deep Code Level Control: Any LLM, Behavior Customization
• Developers recommend for stealth, proxy rotation and scaling still connect cloud browsers

Cloud Agent (recommended for production)

• More powerful agent for complex tasks
• Proxy rotation and CAPTC solution out of the box
• 1000+ ready-made integrations (Gmail, Slack, Notion and others)
• Persistent file system and memory between launches
• Scripts can be restarted later, and they will pull up the actual data, even if the site managed to change

A cloud API call is just an HTTP request:

curl -X POST https://api.browser-use.com/api/v4/runs \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "Your task"}'

## Benchmark

The team runs the models through its own BU Bench - 100 realistic browser tasks, the benchmark itself is also open (browser-use/benchmark). According to them, the library also ranks ** first in the leaderboard of Odysseys** (200 “long” web tasks) with an average score of 87.4%, ahead of computer-use agents from OpenAI, Anthropic, Google and Microsoft.

## How to solve production problems

The FAQ of the project separately warns that Chrome is gluttonous in memory, and keeping many parallel agents on its infrastructure is not the most trivial task. For this, there is a cloud – with a scalable browser infrastructure, memory management, proxy rotation and stealth fingerprinting out of the box.

For authorization in the open version, in practice, there are three ways: reuse an existing Chrome profile with logins already saved, use temporary mailboxes (for example, AgentMail) for one-time accounts, or synchronize a local authorization profile with a remote browser through a separate utility profile-use.

## In Short: What You Need to Know

• browser-use is an open (MIT) library and CLI-skill on Playwright, which gives the LLM-agent to manage a real Chromium-browser: clicks, text input, forms.
• Two modes of use: a CLI-skill for an existing agent (Claude Code, Codex, Cursor and others) and a Python library for writing your automation.
• The model is connected via ChatBrowserUse(model='provider/model') - one key gives access to 15+ providers, or to its own optimized model bu-*.
• Out of the box - custom tools through @tools.action, structured output by Pydantic-scheme, secure work with logins / passwords through sensitive_data, domain restriction through allowed_domains.
• By its own benchmarks, it ranks first in the Odysseys leaderboard among agents for long web tasks.

*Source: official github.com/browser-use/browser-use repository, docs.browser-use.com documentation. *