Notte: a Python framework for web agents that mixes scripting with LLM steps

The problem Notte targets: brittle selectors versus expensive LLM loops

Most web automation breaks for one of two reasons. A hand-written script depends on selectors that change without notice, or an agent driven entirely by a language model re-reasons its way through every click, which costs tokens and adds latency to steps that never needed intelligence in the first place. Notte's README frames its answer as a hybrid: script the deterministic parts and use the model only where the page is unpredictable. The repository describes this as cutting costs by 50%+ while improving reliability, a claim the project makes about its own approach rather than a number verified here.

The audience is developers who already think in Playwright terms. The README lists Playwright-compatible primitives alongside natural language commands, so the intended user is someone comfortable with browser automation who wants an agent layer on top rather than a chatbot that happens to click things. Python 3.11 or newer is required, per pyproject.toml. If your team writes automation in TypeScript, the repository does contain a node-sdk directory, but the README documents only the Python path, and the quickstart examples are all Python.

How the framework splits local execution from hosted sessions

The architecture visible in the repository is a workspace of separate packages: notte-core, notte-sdk, notte-browser, notte-agent and notte-llm, wired together in pyproject.toml under a uv workspace. The top-level notte package depends on the first four at matching versions, so the pieces move together rather than being independently versioned. That is a reasonable choice for a fast-moving project and an annoying one if you wanted to pin only the browser layer.

The runtime shape is a session object that owns the browser, and an agent object that owns the reasoning loop. In the local example, notte.Session and notte.Agent come from the open source package and you supply your own LLM keys. In the hosted example, NotteClient from notte_sdk wraps the same concepts, and the README says you can drop-in replace the import and prefix objects with the client to switch to hosted browser sessions. That symmetry is the central design decision: the same task string and the same reasoning_model argument work in both modes, and the difference is who runs the browser.

What stays on the hosted side is stated plainly. Stealth browser sessions with CAPTCHA solving, proxies and anti-detection are listed under the API service, not the open source core. So are vaults, personas and hybrid workflows. The environment file confirms the boundary: NOTTE_API_URL points at https://api.notte.cc and NOTTE_API_KEY is the credential for that service, while the local section lists provider keys for OpenAI, Anthropic, Groq, Cerebras, DeepSeek, Gemini and OpenRouter.

Installing Notte and running a first agent locally

The README gives two install commands. The first pulls the Python package from PyPI, the second installs the Chromium build the framework drives. Both are required before any example runs.

pip install notte
patchright install --with-deps chromium

The local quickstart needs an LLM key in the environment. The README's example calls load_dotenv() and reads keys through it, and .env.example lists the accepted provider variables. Copy that file to .env and fill in at least one, for example GEMINI_API_KEY, since the sample below uses a Gemini model.

import notte
from dotenv import load_dotenv
load_dotenv()

with notte.Session(headless=False) as session:
    agent = notte.Agent(session=session, reasoning_model='gemini/gemini-2.5-flash', max_steps=30)
    response = agent.run(task="doom scroll cat memes on google images")

With headless=False you should see a browser window open and the agent take actions in it. max_steps=30 caps how many steps the agent may take before stopping, which is the practical guard against a runaway loop and a runaway bill. The repository also ships examples/quickstart.py and an examples/README.md, so the fastest way to confirm your environment works is to run the packaged example rather than retype the snippet.

Switching to hosted sessions changes two lines. Install the SDK package, create an API key in the Notte Console, and the same task runs against a remote browser.

from notte_sdk import NotteClient
import os

client = NotteClient(api_key=os.getenv("NOTTE_API_KEY"))

with client.Session(open_viewer=True) as session:
    agent = client.Agent(session=session, reasoning_model='gemini/gemini-2.5-flash', max_steps=30)
    response = agent.run(task="doom scroll cat memes on google images")

open_viewer=True is what lets you watch the remote session, and the README notes you need a free API key from the console first. The examples directory covers more realistic ground than the quickstart: scraping Nike products, solving a CAPTCHA, ordering on Uber Eats, and an auth vault agent.

Structured output is the feature that makes results usable

Free-text answers from an agent are hard to put in a pipeline. Notte's response_format parameter takes a Pydantic model and returns data in that shape, which is the difference between a demo and something you can write to a table. The README's Hacker News example defines a HackerNewsPost model with title, url, points, author and comments_count, wraps a list of them in TopPosts, and passes TopPosts as response_format. The agent then returns response.answer in that structure.

The trade-off is that the schema becomes part of your prompt surface. A model asked to fill five typed fields per item has more ways to fail than one asked to summarise a page, and the framework does not document a retry or repair policy for malformed structured output in the README. If your extraction target has optional fields or inconsistent formatting on the source page, expect to design the model defensively rather than trusting the first pass. The README also does not document what happens when the agent cannot satisfy the schema within max_steps, so treat that path as something to test against your own sites.

Vaults and personas, and why they are not open source

Two features are aimed squarely at logged-in workflows. A vault stores credentials against a URL and attaches to an agent, which then uses them when a login form appears. The README's example opens client.Vault() and client.Session() together, calls vault.add_credentials with url, username and password, and passes vault=vault into client.Agent. The agent's task is then simply to log in and read messages, with the credential handling out of the task text.

Personas go further: client.Persona(create_phone_number=False) creates a digital identity with a unique email address, and optionally a phone number, plus automated 2FA handling for account creation flows. The README lists both under the API service rather than the open source core, which means the local mode you install with pip does not include them. That is a real constraint, not a detail. If your use case is account creation or authenticated scraping, the open source package gets you the agent loop and the browser, and the credential and identity machinery lives on the hosted side behind an API key.

There is a defensible reason for the split. Storing credentials and provisioning phone numbers are operational services with ongoing cost and abuse risk, and pushing them into a pip package would make the project responsible for secrets on machines it does not control. The cost is that the boundary is not obvious from the quickstart, which shows local and hosted examples side by side without marking which features exist only in one.

The licence is SSPL-1.0, and that decides more than the benchmarks do

The README badge and pyproject.toml both say SSPL-1.0, while the repository metadata reports the licence as NOASSERTION, which usually means the licence file does not match a recognised SPDX template exactly. The two sources agree on the name, so treat SSPL-1.0 as the intended licence and read the LICENSE and COPYRIGHT.md files directly before you build on it.

SSPL is not a permissive licence. It is a copyleft licence written for service providers, and its obligations trigger when you offer the software to third parties as a service. For an internal automation tool that never leaves your company, that distinction rarely matters. For a product where Notte is part of what your customers use, it matters a great deal. This is not legal advice; the point is that the licence, not the feature list, is the first thing to resolve if you plan to ship anything.

The README's benchmark table is the project's own comparison, published in a repository the project links to as open-operator-evals, and it ranks Notte above Browser-Use and Convergence on self-reported success, LLM evaluation, time per task and task reliability. Those numbers come from an evaluation the project maintains. They are a reason to run the eval harness on your own tasks, not a reason to skip it.

Where Notte is the wrong tool, and what to use instead

Notte is the wrong choice when the task is a fixed, well-understood flow against a stable page. If you know the three form fields and the submit button, an LLM in the loop adds cost and a new failure mode for no benefit, and plain Playwright is faster to write and easier to debug. Notte's own framing agrees: script the deterministic parts. If everything in your flow is deterministic, the framework is overhead.

It is also the wrong choice if you need a permissive licence. Browser-Use is the closest alternative named in the README's benchmark table, and the difference in approach is worth stating: Browser-Use is a browser agent, where the model drives the browsing, whereas Notte positions itself as a framework where scripting and agent steps coexist in one session, with the agent reserved for the parts that need it. If your mental model is "give the model a browser and a goal", Browser-Use matches it more directly. If your mental model is "my script, but with an agent for the hard steps", Notte is built for that. Convergence's proxy-lite appears in the same table as a third point of comparison.

One more boundary: the hosted features that make Notte attractive for logged-in workflows are exactly the ones not in the open source package, so a team that wants vaults and personas without a hosted dependency will not find them here. The README does not document a self-hosted path for those services.

Editorial conclusion

Adopt Notte if you already write Playwright-style automation and want an LLM to handle only the brittle steps, and you can accept SSPL-1.0. Do not adopt it if you need a permissive licence for a hosted product, or if you want a framework with no hosted tier at all. Before committing, check whether the local path really covers your target sites, since CAPTCHA solving, proxies and anti-detection are described as API-service features rather than open source core, and confirm the licence terms in the LICENSE file rather than the badge.

Frequently asked questions

Official sources

1. Issues
2. nottelabs/notte on GitHub
3. Project website
4. README
5. Releases