agent-ops-patterns / gallery / browser-use map / how it decides

How browser-use decides

In browser-use, the AI model chooses the actions on each of its steps (code may first open a web address named in the task) and decides the task is finished by calling done. Among the decisions this map shows, nobody is asked before an action runs, so a form submit or a script the model writes goes ahead on its own, and code clicks OK on alerts and confirm dialogs. The built-in limits on how long a run goes are counts, not judgments (500 steps, or 5 failed steps in a row), and the run's success flag is the model's value when it gives one and true when it does not; a second model call grades the run without changing that flag.

From browser-use/browser-use at source version b49a68e4, mapped 2026-10-29. Each answer links the code where that decision is made.

What it does without asking you

• Before the agent submits, buys, sends, deletes or runs page JavaScript, does anyone approve it?

  Decided by plain code Nobody is asked: the model's actions run as soon as they are parsed. An integrator can add a check in their own code through the step callback, which sees the proposed actions before they run.

  service.py:1201-1217 · decision D17 in the full map

• Which actions is the model offered this step?

  Decided by plain code Every built-in action on every page, including evaluate, which runs JavaScript the model writes, except screenshot at the default vision setting and any the integrator excluded, plus custom actions whose site filter matches. On the last step or after repeated failures, only done.

  service.py:4049-4068 · decision B10 in the full map

• When a page opens a JavaScript dialog, who decides OK or Cancel?

  Decided by plain code Code clicks OK on every alert, confirm and leave-page dialog the moment it opens, and Cancel on every text prompt, before the model sees it; the model is told afterwards.

  popups_watchdog.py:62-123 · decision D7 in the full map

• Which browser permissions are granted to the sites the agent visits?

  Decided by plain code When the browser connects, code grants clipboard read/write and notifications to every site; any other permission a page asks for is left to Chrome.

  permissions_watchdog.py:23-43 · decision D8 in the full map

• When a page offers a file, is it saved to disk?

  Decided by plain code Yes. Downloads are always allowed, into a fresh temporary folder, and by default PDFs and attachments are also saved without a click.

  downloads_watchdog.py:500-513 · decision D9 in the full map

How it decides it is done

• Is the task finished?

  Decided by an AI model The model decides by calling done; code ends the run on that call without checking whether the answer is right, and the judge only grades it afterwards.

  service.py:2049-2090 · decision G1 in the full map

• Did the task succeed, by the agent's own report?

  Decided by an AI model The success flag is whatever the model puts in done. If the model leaves it out, code records success, and with an output schema the field is hidden from the model.

  views.py:100 · decision G2 in the full map

• Does an independent judge think the task succeeded?

  Decided by an AI model On by default: after a done, a second call through the agent's own model client grades the run against the task and the last 10 screenshots. The verdict is logged; the agent's own success flag stands.

  service.py:1594-1627 · decision G3 in the full map

Limits and memory

• When has the run used up its step budget?

  Decided by plain code After 500 steps by default; code records "Failed to complete task in maximum steps" and returns with no answer.

  service.py:2620 · decision F1 in the full map

• When does the agent give up after repeated failures?

  Decided by plain code After 5 failed steps in a row (the default), the model gets one step that may only call done; if that fails too, the run ends.

  service.py:2629-2635 · decision F5 in the full map

• While the agent runs, may a person at the terminal halt it, and how does it resume?

  Decided by a person On Mac and Linux, Ctrl+C pauses the run and a second press quits; on Windows the first press quits. Pressing Enter does not resume, despite the printed hint: only code calling agent.resume() does.

  utils.py:324-360 · decision D18 in the full map

Other judgments

• What should the agent do next?

  Decided by an AI model Every step, the model (by default Browser Use's hosted bu-2-0) reads the task, the page and the history and returns up to five actions; code runs them in order.

  service.py:1953 · decision C1 in the full map

Three problems in the code

1. 1. A run can be reported successful when the model never said so

   A program reads the success flag in the model's done call at the end of a run. If the model leaves the flag out, code records success. When the developer asks for a structured result, that field is hidden from the model, so such a run normally reads as successful unless the model sets it anyway. An open pull request in browser-use's tracker proposes a fix.

   Reported; a fix is proposed, not merged (#6178), checked 2026-11-01.

   Where: views.py:100, views.py:107-117. How we checked: the code was re-read at the source version named above; the sentences were checked by an independent AI reviewer from another company (OpenAI Codex, read-only) on 2026-11-01; every sentence it found too wide was rewritten or removed, and every rewrite was checked again.

2. 2. After a step times out, the model is not told which of its actions already ran

   A whole step gets 180 seconds by default. If it runs over, it is cut off, the record of which of the step's actions finished is dropped, and the step's result is only a timeout error. If the run takes another step, the model sees the page as it now is, which may show some effects, but it is not told which of its actions already ran. We found no report of this in browser-use's tracker.

   Not reported upstream, checked 2026-11-01.

   Where: service.py:2487-2493, service.py:1217-1218. How we checked: the code was re-read at the source version named above; the sentences were checked by an independent AI reviewer from another company (OpenAI Codex, read-only) on 2026-11-01; every sentence it found too wide was rewritten or removed, and every rewrite was checked again.

3. 3. Pressing Enter does not resume a paused run, though the message says it will

   On Mac and Linux, pressing Ctrl+C pauses the run and prints "Press [Enter] to resume or [Ctrl+C] again to quit". Pressing Enter does not resume it; only code that calls agent.resume() does, so a person at the terminal can quit with a second Ctrl+C but cannot continue the run from there. We found no report of this in browser-use's tracker.

   Not reported upstream, checked 2026-11-01.

   Where: service.py:3942-3946, utils.py:399-437. How we checked: the code was re-read at the source version named above; the sentences were checked by an independent AI reviewer from another company (OpenAI Codex, read-only) on 2026-11-01; every sentence it found too wide was rewritten or removed, and every rewrite was checked again.

This card was taken from the published map of browser-use at one commit and covers only decisions shown there; it did not look at the beta agent, the sandbox runner, the MCP server, the command line, Browser Use's cloud browsers or features that are off until a setting turns them on, and no browser-use code was run to make it.

Map: edition with 5 of 90 cards left out (published 2026-10-31) · taken from the full map · card data: gallery/cards/browser-use.json. Found something wrong? Use the correction form.