Skip to content

BrowserUse: AI Browser Automation for Scraping and Multi-Step Tasks

BrowserUse lets a language model drive a real browser: it opens pages, types into fields, scrolls, reads content and then passes what it found to another web app. This guide walks through a working Python setup, two end-to-end examples (a product price summary emailed through Gmail, and a Wikipedia edit history turned into a Trello card), and the browser-based UI that lets people without coding experience write their own prompts. The emphasis is on prompt structure, because vague instructions are the most common reason an agent stalls partway through a task.

What an AI browser agent actually is

An AI agent is a program that observes a page and chooses its next action instead of replaying a fixed script. A classic automation script follows one track every run; an agent can react when a layout shifts, a cookie banner appears, or a page loads slowly.

In browser automation an agent can:

  • Navigate the way a person would — clicking, scrolling, reading text.
  • Dismiss pop-ups and cope with layout changes.
  • Pull information out of messy or complex pages.
  • Make a decision based on what it collected.

That flexibility has limits. Agents still need structured prompts that state the task and the steps, and they can misread a page just as easily as they can recover from one. Treat the agent as a capable but literal assistant, not an autonomous expert.

Where browser automation pays off

Automation is worth the setup cost when the work is repetitive and time-consuming rather than creative. Typical jobs:

  • Filling the same form repeatedly (applications, registrations, surveys).
  • Collecting prices, stock levels or news updates faster than manual copying.
  • Revisiting a page on a schedule and alerting you when something changes.
  • Handling routine social media tasks such as scheduling or filtering.
  • Downloading many files in one pass.
  • Extracting only the useful parts of a cluttered page.
  • Logging into several accounts across different sites with one script.

If a task happens once, doing it by hand is usually faster than writing a prompt for it.

How the browser is actually controlled

The model has no hands. It sends commands to a browser process, and that browser performs the clicks and keystrokes a person would. Browser automation has existed for years for testing: scripts open pages, submit forms, extract text and images, and check that a site behaves as expected. Agents extend that same machinery with decision-making on top.

In practice the stack for this guide is Playwright (the automation layer) plus BrowserUse (the agent layer) plus a language model (the reasoning layer).

Prerequisites and project setup

You need basic Python comfort — installing packages, running scripts, using a terminal. Specifically:

  • Python 3.9 or newer. Confirm with python --version or python3 --version.
  • A terminal or command-line tool.
  • A code editor; VS Code or PyCharm are fine choices.
  • Playwright installed and configured.
  • Poetry, optional, for dependency and environment management.

Create the project, then add the agent package. The exact commands are in the setup command module that accompanies this page. Either Poetry or pip works; the pip route also runs playwright install.

BrowserUse supports several model backends. This walkthrough uses ChatGPT from OpenAI, so you need an API key: open the OpenAI API keys page, create a new secret key owned by you, name it, and copy the value. Store it in a .env file at the project root as OPENAI_API_KEY. The boilerplate script — imports, the async main, the Agent construction with ChatOpenAI(model="gpt-4o"), await agent.run() — is provided verbatim in the accompanying code module.

Pointing the agent at your own Chrome

Playwright ships a default Chrome build. If you would rather use the Chrome already installed on your machine — which is regularly updated and may already hold your saved logins — pass its executable path to the agent through a Browser object with BrowserConfig(chrome_instance_path=...), then hand that browser to the Agent. The full snippet, including await browser.close(), is in the accompanying code module. Adjust the path to match your system.

Example 1: Summarize microphone prices and email the report

Goal: search a retailer for podcast microphones, summarize up to five results, and send the summary to yourself through Gmail.

The prompt is the whole job. It is broken into numbered steps with explicit stop conditions:

  1. Open the retailer site and wait for a full load; retry up to three times before failing.
  2. Find the search box (it has a magnifying-glass icon). If it is missing, log an error and stop.
  3. Type "podcast microphone", press Enter, and wait for results.
  4. Confirm at least one product exists; otherwise log an error and stop.
  5. Collect name, price, rating and availability for up to five microphones, one per paragraph, in readable prose rather than a raw dump.
  6. Verify the summary is non-empty before continuing.
  7. Open Gmail, log in with credentials from the environment, and stop on failure.
  8. Compose a new message, put your own address in the To field, and — this is the step that matters — click the suggested address below the field to confirm the recipient, then verify it appears.
  9. Enter the subject "Microcenter: available microphones", paste the summary into the body with real line breaks, and send, waiting for the confirmation message.

The captured walkthrough notes a real failure: when the prompt only said "enter this value into the To field", the agent did not confirm the recipient. Being explicit about the confirmation click fixed it. Credentials live in .env as GOOGLE_LOGIN and GOOGLE_PASSWORD; the full prompt text and the .env template are in the accompanying code modules.

Running the script

Run the entry point with poetry run python src\browser_demo\main.py (the exact command is in the accompanying code module). Close any active Chrome window first — the agent needs to launch its own instance. You should see the browser open, the agent navigate and scroll, and the email compose itself.

Example 2: Wikipedia edit history into a Trello card

Goal: read the last three revisions of the "Artificial intelligence" Wikipedia article and create a Trello card linking them, assigned to a reviewer.

Plan the steps before writing the prompt:

  1. Open English Wikipedia.
  2. Search for "Artificial intelligence" and open the article.
  3. Open "View history" and locate the last three revisions (date, username, change summary).
  4. Extract links to those revisions.
  5. Open Trello, log in if needed, and open the target board.
  6. Add a card titled "Artificial Intelligence Edits".
  7. Open the card and put a bulleted summary of the three revisions, with links, in the Description field.
  8. Use the Members button to assign the reviewer and confirm the avatar appears.
  9. Save.

Adjust the board name, member name and credentials to your own account. The complete prompt is in the accompanying code module.

The browser-based UI

Editing prompts inside a Python file gets tedious. The project's web UI gives you a form for the task and its settings.

Installation: clone the web-ui repository with Git, install requirements.txt, copy .env.example to .env, and paste your OpenAI key in as OPENAI_API_KEY. Other configuration values can be adjusted too. The exact commands are in the accompanying code modules.

Launch it locally on port 7788 with python webui.py --ip 127.0.0.1 --port 7788, then open http://127.0.0.1:7788/. The settings page lets you change the maximum number of steps the agent will attempt, and the LLM tab exposes model settings (defaults usually work). The Run agent tab holds the prompt box.

Example prompt: check a local cinema's schedule for tomorrow's showtimes of an animated film, switch to the English version of the site, open the film's page, and return a structured summary of times, hall and special formats — or a clear message if nothing is scheduled. Press Run Agent; the browser opens and the agent works through the steps. It also writes agent_history.gif to the project root, a recording of its reasoning and actions.

Prompt-quality checklist

Before you run an agent, check the prompt against these items:

  • Every step names the page or element it acts on.
  • Every step that can fail has an explicit stop-and-log instruction.
  • Confirmation clicks (recipient suggestion, member avatar, save button) are called out as separate steps.
  • Data extraction lists the exact fields you want and the maximum count.
  • Formatting instructions say what the output should look like to a human reader.
  • Credentials are read from environment variables, never hard-coded in the prompt text.
  • You have closed any conflicting browser instance before launch.

If a step fails, change the prompt wording rather than assuming the tool is broken. The captured walkthrough shows that a single missing confirmation instruction was enough to break the email step.

Conclusion

BrowserUse turns a plain-language task description into a sequence of real browser actions, and the same task can run from a Python script or from the web UI. The two examples here — a price summary emailed to yourself and a Wikipedia edit digest turned into a Trello card — show the pattern: plan the steps, write them explicitly, add stop conditions, and keep credentials out of the prompt body.

Failure modes and the prompt guard that catches them
SymptomPrompt guardWhat to do
Page never finishes loadingRetry up to 3 times, then failCheck the URL and whether the site is reachable
Search box not foundLog an error and stopConfirm the page layout matches the prompt description
No products listedVerify at least 1 product before proceedingAdjust the search term or check for a bot challenge
Summary empty or incompleteVerify the summary is not emptyRe-run with a narrower extraction scope
Recipient not confirmed in GmailClick the suggested address and verify it appearsAdd the confirmation step explicitly
Login failedLog an error and stopCheck the environment variables
Send failedWait for the confirmation messageInspect the account for blocks or rate limits

Derived from the prompt structure in the captured walkthrough; not a test matrix.

Web UI control map
AreaWhat it controlsDefault guidance
Settings pageMaximum number of steps the agent will attemptRaise it for longer multi-step tasks
LLM tabLanguage model configurationDefaults usually work
Run agent tabPrompt text box and Run Agent buttonPaste the full step-by-step prompt
Project rootagent_history.gif recordingReview it to see what the agent did

Reflects the UI as described in the walkthrough; the UI may have changed since.

Frequently asked questions

Do I need coding experience to use BrowserUse?

For the Python route, yes — basic Python and terminal skills are assumed. For the web UI, you install it once and then write prompts in a text box, so no coding is needed for day-to-day tasks.

Which model does the walkthrough use?

ChatGPT from OpenAI, configured as ChatOpenAI(model="gpt-4o"). BrowserUse supports other engines, but the setup steps here assume an OpenAI API key.

Why did the agent fail to enter the email recipient?

The prompt only said to type the address into the To field. Gmail requires clicking the suggested address below the field to confirm it. Adding an explicit click-and-verify step fixed the failure.

Can I use my own Chrome installation?

Yes. Pass the path to your Chrome executable via BrowserConfig(chrome_instance_path=...) and hand the resulting browser to the agent. Close any running Chrome window first.

Where do credentials go?

In a .env file at the project root, read into the script with os.getenv. Never paste real credentials into the prompt body.

What is agent_history.gif?

A recording the agent writes to the project root showing its reasoning and actions in real time, useful for debugging a failed run.