browser-use is an open-source Python library that connects AI agents to a real web browser, letting them navigate websites, fill forms, click buttons, extract information, and interact with web applications through natural language instructions. Unlike web scraping libraries that parse static HTML, browser-use controls an actual browser — it handles JavaScript-rendered content, authentication flows, multi-step interactions, and dynamic pages that change after the initial load. This guide covers what browser-use does, how to set it up, and the patterns that make it reliable for practical automation tasks.
What browser-use Does
browser-use wraps Playwright (Microsoft’s browser automation library) with an AI agent layer. Playwright handles the low-level browser control — opening tabs, clicking elements, typing text, reading page content. The AI layer handles the high-level reasoning — understanding what the page contains, deciding which element to interact with, extracting the information that is relevant to the task, and deciding what to do next. You describe a task in natural language; browser-use translates that into a sequence of browser actions until the task is complete or fails.
The result is web automation that can handle pages it has never seen before. Traditional web automation with Playwright requires writing selectors for specific elements on specific pages — when the page changes, the selectors break. browser-use reasons about the page content semantically, so it adapts to layout changes, different versions of a page, and variations between similar pages without requiring selector updates.
Installation and Setup
Install browser-use and its dependencies, then install the Playwright browser binaries. browser-use supports multiple LLM providers — Claude, GPT-4o, Gemini — through LangChain’s model abstraction. You need an API key for whichever model you choose; Claude and GPT-4o are the most commonly used and produce the most reliable results for browser tasks.
The basic usage pattern is straightforward: create an Agent with a task description and a language model, then call run() to execute it. browser-use opens a browser window (visible by default, headless optional), performs the necessary actions, and returns the result. Watching the browser window during development is useful for understanding what the agent is doing and debugging when it gets stuck.
Figure 1 — browser-use: how the AI-browser loop works
What Tasks Work Well
browser-use performs reliably on tasks with clear success criteria and well-structured web pages. Tasks that work well:
- Information extraction — “go to this product page and extract the price, availability, and specifications” — the agent navigates to the page and returns structured data
- Form filling — “fill in this contact form with these details and submit it” — the agent finds the form fields, fills them, and submits
- Multi-step research — “search for the top five results for this query, visit each page, and summarise what each says about the topic”
- Account interactions — logging into a service and performing a specific action, such as downloading a report or updating a setting
- Comparison tasks — “check the pricing page of these three services and compare their plans in a table”
What Tasks Are Unreliable
Some task types consistently produce unreliable results and are better handled with specialised tools:
- CAPTCHAs — browser-use cannot solve CAPTCHAs and will get stuck on sites that use them aggressively
- Highly dynamic SPAs — pages that rely heavily on WebSocket updates or complex client-side state sometimes confuse the agent’s page reading
- Tasks requiring precise timing — clicking a button that only appears for a few seconds, or interacting with real-time auction or booking systems where timing matters
- Multi-factor authentication — tasks requiring MFA codes from a phone or authenticator app cannot be completed autonomously
Providing Good Task Descriptions
The quality of browser-use’s execution depends significantly on how clearly the task is described. Vague tasks produce wandering behaviour; specific tasks with clear success criteria produce direct execution. Include the starting URL rather than relying on the agent to find the right site. Specify what to do with the extracted information — “return as a JSON object with these fields” or “save to a CSV file.” If the task involves authentication, include the credentials in the task description or provide them through a separate mechanism rather than expecting the agent to find them.
For multi-step tasks, describing the steps explicitly is better than describing the outcome alone. “Navigate to the reports section, select the monthly summary for September, and download the PDF” is more reliable than “download the September report” — the agent has a clearer path to follow and is less likely to explore incorrect routes through the site.
Handling Authentication
Many practical automation tasks require logging into a service. browser-use handles login flows reliably when credentials are provided — it finds the login form, fills the fields, submits, and waits for the redirect. For services with complex authentication flows (OAuth redirects, SSO, two-step verification without MFA), browser-use typically handles the standard parts and fails gracefully at steps requiring human interaction.
For repeated tasks on the same service, saving the browser’s authenticated session state between runs avoids re-logging in every time. Playwright supports saving and restoring browser storage state, which browser-use exposes through its BrowserConfig. Loading a saved session state at startup means the agent starts already authenticated, skipping the login flow entirely for subsequent runs.
Running Headless for Production
During development, running with a visible browser window is useful for watching what the agent does and debugging failures. For production automation, run headless — no visible browser window, lower resource usage, compatible with server environments. Set headless mode through the BrowserConfig when creating the agent. In headless mode, browser-use takes screenshots at each step that you can review after the fact for debugging — these screenshots are the equivalent of the visible browser window in development and are often sufficient to understand why a task failed without needing to rerun it visibly.
Combining browser-use with Other Tools
browser-use works well as one tool among several in a broader agent. A research agent might use web search MCP to find relevant URLs, then browser-use to visit and extract detailed information from each page — the search tool returns current, relevant URLs; browser-use extracts structured data from pages that require JavaScript rendering or interaction to access. Combined with a database tool, the agent can extract data from a web source and write it directly to a database in the same session. This composability is one of browser-use’s practical strengths: it fills the browser interaction gap in agent pipelines that are otherwise well-served by simpler tools.
browser-use lowers the barrier to web automation significantly — tasks that previously required writing and maintaining brittle CSS selectors can be described in plain language and executed reliably on pages the agent has never seen before. Its reliability on well-structured pages with clear task descriptions is high; its limitations on CAPTCHAs, complex SPAs, and timing-sensitive interactions are real but affect a small fraction of practical automation use cases. For developers who need to automate web interactions as part of a larger agent workflow, browser-use is the most practical open-source option currently available.
Custom Actions and Extending browser-use
browser-use supports custom actions that extend what the agent can do beyond the built-in browser interactions. A custom action is a Python function decorated with the browser-use action decorator, which makes it available to the agent as a callable tool alongside the standard browser actions. Custom actions are useful for tasks that require non-browser work as part of a browser workflow: saving extracted data to a specific format, calling an internal API with scraped data, or applying business logic to classify extracted content. For example, a price monitoring workflow might use a custom action to compare a newly extracted price against a stored threshold and trigger an alert if the price has changed significantly. The custom action runs in Python while the browser actions run in Playwright, and the agent orchestrates both as part of the same task loop. This extensibility makes browser-use composable with the rest of your Python infrastructure rather than a standalone tool.
Rate Limiting and Respectful Automation
Automated browser agents can make requests at a rate that strains web servers, triggers rate limiting, or violates a site’s terms of service. A few practices for responsible browser automation: add deliberate delays between page loads, especially when processing many pages from the same domain; check the site’s robots.txt before automating interactions with it; avoid automating interactions that the site explicitly prohibits in its terms of service; and run automation during off-peak hours when possible for high-volume tasks. browser-use does not enforce rate limits automatically — you are responsible for configuring delays and respecting site policies. For tasks involving many pages from the same domain, a delay of one to two seconds between page loads is a reasonable default that prevents triggering rate limits while keeping automation fast enough to be practical.