Browser Use in Python: Build Your First Browser Agent and Keep It Safe

A browser agent is an AI agent whose tool is a web browser. An AI agent is a program in which a language model (an LLM, the kind of model behind chatbots) picks its own next step and acts through tools, such as a document search for retrieval-augmented agents; a browser agent opens pages, clicks and types.

This guide builds a first one with Browser Use in Python.

In our theme AI agent architecture, browser agents build on an agent that already plans and calls tools, and give it hands for websites that have no API.

A plain browser script (browser automation) fixes every click in advance, as a workflow fixes its steps. A browser agent works in a loop: it looks at the page, decides, acts and looks again, until it has an answer or gives up. How a computer use agent sees a page, and why the loop fails covers that loop.

In Browser Use 1.0, each step is one request to the model, which writes a short piece of Python that the library runs against Chrome.

What you need before you start

• Python 3.11 or newer.
• Browser Use 1.0.2, the latest on 11 November 2026. Version 1.0 is a rewrite, so code written for earlier versions can break.
• A model: the Browser Use hosted model, a hosted model with your own key, or a local model on your own computer behind an OpenAI-compatible server (a program that accepts the same requests as OpenAI’s API, such as Ollama or llama.cpp’s llama-server).
• A browser: Chrome, Chromium or Edge, or one command that downloads Chromium.
• Docker, for Step 4.

Why first browser agents fail

The answer looks right and is wrong. The library’s success signal, result.success, is the agent’s own verdict on its work, not a check. In an independent study (OSU NLP and UC Berkeley, 2025), Browser Use answers sometimes did not match the pages the agent had seen, for example cars far from the zip code asked for.

It takes too many steps. A step is one model request, and the defaults allow 100 of them, or 1,700 seconds (about 28 minutes). In the same study, failed runs of Browser Use and two other agents took nearly twice as many steps as successful ones, mostly through repeated actions and pop-ups. A long run is a warning sign.

The model’s code runs as you. The model writes Python, and the library runs it as your user. That makes it a code execution agent with no sandbox of its own: the project says to run untrusted tasks in a container or virtual machine. A model misled by text on a page can run code you did not want.

If you only wanted to know what building a browser agent involves, you can stop here. The rest is for the person who types the commands.

The path from install to a locked-down agent

Step 1: Install the library in a clean environment

Use a fresh virtual environment (an isolated folder of Python packages) and pin the exact version:

python3 -m venv .venv && source .venv/bin/activate
pip install 'browser-use==1.0.2'
browser-use install

The project says to pin with ==, never >=: releases move fast and can break things. Version 1.0 pins every dependency exactly too, so a project that needs other versions of packages such as pydantic cannot install it alongside; use a fresh environment.

browser-use install is only for machines with no Chrome, Chromium or Edge. It downloads Chromium.

Step 2: Connect a model and run the minimal script

With no model and no browser set, Browser Use uses its hosted model (bu-fast) and a cloud browser, both billed to a Browser Use account key (BROWSER_USE_API_KEY); a cloud browser cannot reach localhost. This guide uses your own model and a local browser.

For a local model, start an OpenAI-compatible server on a port you choose. The model must support tool calling (it asks the program to run a function). With llama.cpp, add --jinja:

llama-server -m <your model file> -a qwen2.5-7b-instruct-q4_k_m --port 8081 --jinja

Save this as agent.py:

import asyncio
from browser_use import Agent, Browser, ChatOpenAI

llm = ChatOpenAI(
    "qwen2.5-7b-instruct-q4_k_m",
    base_url="http://localhost:8081/v1",
    api_key="sk-no-key-required",
)
browser = Browser("chromium", allowed_domains=["books.toscrape.com"])
agent = Agent(
    "Go to https://books.toscrape.com/ and return the title and price of the cheapest book on the first page.",
    llm=llm,
    browser=browser,
)

async def main():
    result = await agent.run(max_steps=15, timeout=600)
    print(result.status)
    print(result.final_result())

asyncio.run(main())

The task runs on books.toscrape.com, a bookshop built for practice. Run python agent.py: the library logs one line per step (the first line of the code the model wrote), then the script prints the status and the answer.

For a hosted model, drop base_url and api_key, set OPENAI_API_KEY and write ChatOpenAI("gpt-6-luna"), the model in the project’s documentation.

Step 3: Check the result yourself

agent.run() returns a result object. Four things on it matter:

• result.status is completed, max_steps, timeout or error. At a limit the agent gets one last turn to hand in its work; if it does not, read result.partial.
• result.final_result() is the answer, None unless the run completed.
• result.success is the agent’s own verdict: True, False, or None when it gave none. The documentation says to verify important actions independently.
• result.steps, result.cost_usd and result.messages (the full transcript). Version 1.0 has no per-step history.

The table shows our runs of this exact script on 11 November 2026. One line changed: inside the container, base_url pointed at http://host.docker.internal:8081/v1. Setup: Browser Use 1.0.2 in Docker, Qwen2.5-7B-Instruct (4-bit q4_k_m) on llama.cpp on an Apple M3 Mac. Our own script, without a model, read the right answer: Starving Hearts (Triangular Trade Trilogy, #1) at £13.99.

What to take from the table:

• Run 2 ended completed with a book and a price that are not on the page; the cheapest there costs £13.99. A completed status is not a correct answer.
• Runs 1 and 3 stopped at the 600-second limit, and final_result() returned None.
• In all three runs the model’s code imported bs4 (Beautiful Soup), which the container does not have, and those steps failed. Model-written code can use only what is installed.
• In an earlier test of similar code on an easier question (the page title), all 3 answers were wrong too. For the two that looked plausible, success was None, not False.

Three runs are not a success rate, and we compared no models.

Treat a vendor’s headline number with care: Browser Use reported 89 % on WebVoyager, a set of tasks on live websites, in its own report of December 2024, and the independent study above found 30.0 % on 300 other live tasks (GPT-4o, 25 steps). Test your own task.

Step 4: Lock it down

Step and time limits. agent.run(max_steps=..., timeout=...) defaults to 100 steps and 1,700 seconds; we used 15 and 600. Pass them to run(): Agent(max_steps=...) is not an option.

Allowed sites. Browser("chromium", allowed_domains=["books.toscrape.com"]) blocks navigation to other sites. It is a guard for a well-behaved model, not a sandbox. Images, scripts, fetch calls and iframes that an allowed page loads from other hosts are not blocked, so it can still send data elsewhere, and model code can go around the library.

Secrets. The safest first agent has none. If a task needs a password, use Agent(task, sensitive_data={"password": "..."}): the model sees only the name and types the value with type_secret. Model-written Python can still read the value, and screenshots are not redacted.

Confirmation. We found no built-in setting that asks you before an action. You can add your own function as a tool (@tools.action), but the model decides when to call it. For anything you cannot undo, do not give the agent the means.

A container. The model’s code runs as your user, and Browser("chromium") opens a local debugging port with no authentication that any local account can attach to. A container (an isolated box for a program) limits both:

1. Start from a Python 3.12 image, python:3.12-slim.
2. Install libatomic1; our first build failed on the slim image without it.
3. Run pip install 'browser-use==1.0.2', then browser-use install.
4. Add a non-root user and run the script as that user.
5. Start it with docker run, mount only the folder the script writes to, and point base_url at your model server (ours: http://host.docker.internal:8081/v1).

When a hosted computer use model fits better

If the task needs a whole desktop, not just web pages, look at the computer use tools of Anthropic and OpenAI: with Anthropic’s tool and OpenAI’s computer tool, your own program runs the actions in an environment you control; OpenAI also offers a browser it hosts. For tasks inside web pages, Anthropic says its separate browser use tool fits better.

Mistakes that break a first Browser Use agent

Pick a first task whose answer you can check without the agent

Start with a task whose right answer you can compute without the model. In our test, a plain script found the cheapest book, so every wrong answer showed at once. If your task has no such answer, read the pages of a few runs by hand.

A prompt to set this up with a coding assistant

Paste this into your coding assistant (an agent that edits your project). Replace each bracketed part with your own value.

You are helping me build a first browser agent with the Browser Use Python library, version 1.0.x.

Setup:
- Python 3.11 or newer, in a new virtual environment.
- Install with an exact pin: pip install 'browser-use==1.0.2'. Never use >=.
- Use only Browser Use 1.0 names: Agent, Browser, ChatOpenAI. Do not use BrowserSession, BrowserProfile, use_vision, max_failures or ChatOllama: they were removed or are ignored in 1.0.

Script (one file, about 20 lines):
- Model: [a hosted model name and the environment variable that holds my key, OR my local server URL ending in /v1 and its model name]
- Browser: Browser("chromium", allowed_domains=["[the one site my task needs]"])
- Task: [one sentence; start with a task whose answer I can check without the agent]
- Run with: await agent.run(max_steps=[a small number], timeout=[seconds])
- Print result.status and result.final_result().

Safety:
- Put no passwords, cards or logged-in accounts in the first version.
- Write a Dockerfile that uses python:3.12-slim, installs libatomic1 (our first build on that image failed without it), installs the library, runs browser-use install, and runs the script as a non-root user. Give me the docker run command with memory and CPU limits and no mounted folder except one output folder.

Check:
- Tell me how to check the answer without the agent.
- Remind me that result.success is the agent's own verdict, not proof.

Rules for you: do not invent library options. If you are not sure that an argument exists in Browser Use 1.0, say so and leave a TODO instead of guessing.