Skip to content

Requirements and Use Cases

Jump to bottom
swisherae edited this page Sep 25, 2026 · 13 revisions

Requirements (FURPS+)

  • Functional: System shall take a task written in English, carry it out in a real browser then return a final answer.
  • Usability: Provides error message if something is set up wrong. The error message shall diagnose what the problem is and how to fix the problem.
  • Reliability: Failing AI providers don’t hang. The agent retries a set number of times if there are consecutive failures
  • Performance: No step will run forever, each task has a time limit.
  • Supportability: It is possible to add new AI providers without changing the Agent.

Actors

  • Primary actor: A developer writes a short python script giving the agent a task in English and wants the answer back. In my project this is me.
  • Supporting actor: Often another system, such as a database server, an authentication provider, a payment service, or a third-party API. The supporting actor is the AI agent which in my case is the google gemini API
  • Offstage actor: One possible offstage actor is a manager viewing the saved run history of the Agent. They may never use the agent but can see the input and output of the AI interactions.

Brief Use Cases

Collect data:
Developer asks for the first five quotes on quotes.toscrape.com, each with its author and tags, in a set format. The system opens the site and has the AI model pull those items out of the page content. It lays them out as "Quote 1: … – Author: … – Tags: …" and returns the finished list as its final answer.

Implemented in:

examples/getting_started/03_data_extraction.py. The extract action (line 1063 of browser_use/tools/service.py) sends the page content and the request to the AI model, and done returns the formatted list.

Submit Web Form: The developer gives the system details to enter such as customer name, telephone, pizza size, toppings, delivery time, and a comment. They ask it to submit the order form and report the website’s response. The system opens the page, identifies which field is which, types each value into the correlated box. It fills it out then clicks the submit button and returns the confirmation data the website sends back.

Implementation:

examples/getting_started/02_form_filling.py. The input and click actions in browser_use/tools/service.py send TypeTextEvent or ClickElementEvent for each field.

Looking up information online: Developer may task the agent in English such as “Go to Wikipedia and search for ‘unified process’ and tell me the first sentence”. The system will then open up chrome, read the current page, and ask the AI model what to do next. Following the models decisions, it goes to Wikipedia, types in the search term at the search box, submits it. After this the agent reads off the opening sentence and marks the task as done. The system prints the answer and closes the browser.
_Implemented in: _ Examples/getting_start/01_basic_search.py which calls agent.run() in browser_use/agent/service.py. The steps use the navigate, input, and done actions in browser_use/tools/service.py.

Fully-Dressed Use Cases

Use Case: Look Up Information Online Primary Actor: Developer Stakeholders and Interests:

  • Developer: wants a correct answer without writing any browsing code, and wants the run to end on its own instead of hanging.
  • AI model provider (Google Gemini): wants requests to stay within the account's rate limits and quota.
  • Reviewer (offstage): wants a complete record of what the agent did. Preconditions: browser-use is installed, Chrome is available, and .env holds a valid API key for the chosen model. Success Guarantee: The agent's history records every step, final_result() returns the answer, and the browser is closed. Main Success Scenario:
  1. Developer runs a script that creates an Agent with a question in plain English ("Search for 'what is browser automation' and tell me the top 3 results") and calls run().
  2. System starts Chrome and connects to it.
  3. System captures the current page: a numbered list of every element it can click or type into, plus a screenshot.
  4. System sends the task, the captured page, and its notes from earlier steps to the AI model.
  5. AI model replies with an evaluation of the previous step, a memory note, a next goal, and up to five actions.
  6. System performs the actions in the browser, such as a web search with the search action (DuckDuckGo by default), and records each result.
  7. Steps 3-6 repeat until the answer is on the page.
  8. AI model calls the done action with the answer and marks the task successful.
  9. System closes the browser and returns the history; the script prints final_result(). Extensions: 1a. The task contains exactly one URL:
    1. System opens that URL as an initial navigate action before the first model call. 5a. The model provider returns an error (429, 5xx, 401 or 402) and a fallback_llm is configured:
    2. System switches to the backup model for the rest of the run.
    3. System sends the same request to the backup model. 5b. The model call fails and no backup model is configured:
    4. System records the failure and starts the next step.
    5. After 5 consecutive failures (max_failures), System gives the model one last try with only the done action available.
    6. That try also fails, so System stops and final_result() returns None. (Seen in my DeepSeek 402 run: "Stopping due to 5 consecutive failures.") 6a. The search engine shows a CAPTCHA:
    7. AI model switches to another search engine.
    8. When every engine is blocked, the run reaches its step limit and the model calls done with success set to false. (Seen with a hidden browser: Google, then DuckDuckGo, then Bing were all blocked.) 7a. The agent keeps repeating actions, or pages stop changing:
    9. System adds a warning to the model's context. (Seen in my logs as "Loop detection nudge injected.") 7b. The step limit (max_steps, default 500) is nearly used up:
    10. System warns the model how many steps remain.
    11. On the last step only done is available; the model reports what it found, with success set to false if the task isn't finished. Special Requirements: Each step times out after 180 seconds (step_timeout). Implemented in:
  • examples/getting_started/01_basic_search.py
  • Agent, browser_use/agent/service.py: run() (line 2503); get_model_output fallback retry (lines 1974-1980); _try_switch_to_fallback_llm (line 1983); _force_done_after_failure (line 1580); _inject_loop_detection_nudge (line 1496); step-budget warning (lines 1552-1572); start-URL shortcut (line 462)
  • search action default engine, browser_use/tools/views.py (line 52)
  • DOMWatchdog.on_BrowserStateRequestEvent, browser_use/browser/watchdogs/dom_watchdog.py (line 244)
  • MessageManager, browser_use/agent/message_manager/service.py
  • ActionLoopDetector, browser_use/agent/views.py (line 157)

Use Case Diagram

image

Clone this wiki locally