Browser agents fail in quiet ways. The run “finishes”, but the form was never submitted, a CAPTCHA blocked the agent, or a page tried to inject instructions. Browser Use 1.0.5, released on 14 November 2026, adds a built-in judge that checks every run and tells you what actually happened. This tutorial shows how to read the judgement in Python, how to give the judge your own success criteria, what it costs, and how to use its “gotchas” to make the next run better.

What changed in Browser Use 1.0.5

According to the 1.0.5 release notes and pull request #6398, every Agent.run() that took at least one step is now judged by the same model the agent uses. It is one extra, low-effort request that compares the run’s trace with your task and fills result.judgement with six fields:

  • success: whether the task looks done
  • failure_reason: why it failed, if it did
  • description: a short summary of what happened
  • prompt_injection_detected: whether a page tried to steer the agent
  • bot_block_or_captcha_detected: whether the site blocked the agent
  • gotchas: up to five short, general lessons about the sites, such as rate limits or a field’s required format

Release 1.0.5 also made the judge see more context. Unless you set use_vision=False, it gets the trace, the run’s last screenshots and the final page. It writes gotchas whenever a site rejected input, errored, blocked or rate-limited the agent, even when the run succeeded. The release notes give an example: “The form requires phone numbers in (###) ###-#### format.”

The project tested this on 13 real runs, judging each one three times. Gotchas appeared on 15 of 15 verdicts where the site pushed back (up from 6 of 15), and on 2 of 24 verdicts for clean runs, with success verdicts unchanged. That is the project’s own small sample, not an independent benchmark, but it shows what the change is aiming for.

Install or upgrade

Browser Use 1.0 needs Python 3.11 or newer. With uv:

uv init --python 3.12 my-agent && cd my-agent
uv add 'browser-use==1.0.5'

Or with pip inside a virtual environment:

pip install 'browser-use==1.0.5'

Coming from 0.x? Version 1.0 is a big rewrite (the agent writes Python against raw CDP in a persistent REPL, built on Pydantic AI), so read the project’s MIGRATING.md before you upgrade a production script.

Your first judged run

Here is a minimal script that uses a local Chromium browser and an OpenAI-compatible model, following the patterns in the project README. Replace the model name with one you have access to.

from browser_use import Agent, Browser, ChatOpenAI

agent = Agent(
    "Open https://github.com/browser-use/browser-use and report the star count",
    llm=ChatOpenAI("your-model-name"),   # reads OPENAI_API_KEY
    browser=Browser("chromium"),         # fresh local Chrome with a temp profile
)

result = agent.run_sync()
print("Answer:", result.final_result())

j = result.judgement
if j is None:
    print("No judgement (judge off or the judge request failed)")
else:
    print("Success:", j.success)
    print("Summary:", j.description)
    if not j.success:
        print("Why it failed:", j.failure_reason)
    print("Prompt injection seen:", j.prompt_injection_detected)
    print("Blocked / CAPTCHA:", j.bot_block_or_captcha_detected)
    for tip in j.gotchas:
        print("Gotcha:", tip)

In async code, use result = await agent.run() instead of run_sync().

Two details from the PR are worth remembering:

  • result.judgement is None when judging is turned off or the judge request failed. The judge never changes the run’s own result.
  • A malformed judge answer is not retried, so a run costs exactly one judge request.

Give the judge your success criteria

By default the judge only knows your task text. If you know what “done” looks like, pass it with judge_context:

agent = Agent(
    "Fill in the contact form on https://example.com/contact with my test details",
    llm=ChatOpenAI("your-model-name"),
    browser=Browser("chromium"),
    judge_context=(
        "Success means the page shows a confirmation message after submit. "
        "Typing into the fields without submitting is a failure."
    ),
)

This is the most useful setting for automated pipelines. A vague task plus a clear judge_context gives you a much more honest success flag than the agent’s own claim that it is finished.

If you are porting 0.x code, the old use_judge and ground_truth options work again as aliases, according to the release notes.

Turn the judge off when you don’t need it

For quick experiments, or when you already verify results yourself, turn it off:

agent = Agent("Search for today's weather in Delhi", judge=False)

What the judge costs

The judge uses your model, so it costs tokens. The PR says the judge’s tokens and cost, including a failed judge’s, are added to result.usage and result.cost_usd, so your totals stay accurate:

print(result.usage)
print("Total cost (USD):", result.cost_usd)

The trace sent to the judge is text only with secrets redacted and capped at 120,000 characters (the task and context are capped at 20,000 characters each). Screenshots and the final page are added unless use_vision=False. If your model rejects images, the README says the library sends one more text-only request.

Privacy and telemetry

If usage statistics are on, the judgement is sent with the run’s event, scrubbed like the result (no emails, secrets or credentials). With usage stats off, nothing is sent. For sensitive work, also use the library’s sensitive_data option so passwords are replaced with placeholders in traces:

agent = Agent(
    "Log in to https://example.com and download the latest invoice",
    sensitive_data={"https://*.example.com": {"password": "..."}},
    browser=Browser("chromium"),
)

The README is clear that this is not a sandbox: model-written Python can still read the value, so use test accounts and containers for untrusted tasks.

A practical pattern: feed gotchas into the next run

The gotchas are written as lessons “for the next agent”. A simple way to use them is to save them per site and add them to the next task:

import json
from pathlib import Path

NOTES = Path("site_notes.json")

def load_notes() -> list[str]:
    return json.loads(NOTES.read_text()) if NOTES.exists() else []

def save_notes(new: list[str]) -> None:
    notes = load_notes()
    for n in new:
        if n not in notes:
            notes.append(n)
    NOTES.write_text(json.dumps(notes[-20:], indent=2))

task = "Submit the signup form on https://example.com/signup with test data"
tips = load_notes()
if tips:
    task += "\nKnown site rules:\n- " + "\n- ".join(tips)

result = Agent(task, browser=Browser("chromium")).run_sync()
if result.judgement:
    save_notes(result.judgement.gotchas)
    if result.judgement.bot_block_or_captcha_detected:
        print("Blocked: retry later or use a different browser setup")

Review the saved notes now and then. They come from a model, so treat them as hints, not facts.

When to trust the verdict

  • Use success as a filter, not as proof. For money, accounts or data changes, still verify the outcome with your own check (an API call, a database row, a confirmation email).
  • Treat prompt_injection_detected=True as a stop signal for automated runs and log the page URL.
  • If bot_block_or_captcha_detected keeps appearing, slow down, reduce parallel runs or respect the site’s terms instead of fighting it.

Takeaway

Browser Use 1.0.5 makes every agent run self-reporting: one cheap extra request tells you whether the task really succeeded, why it failed, and what the site expects next time. Upgrade, print result.judgement in your scripts, add a clear judge_context for anything automated, and start saving the gotchas. The full details are in the release notes and README.