快速构建可靠的网页自动化代理

---

Notte 是什么？

Notte 提供了构建和部署能够与网页无缝交互的 AI 代理所需的所有核心工具。我们的全栈框架将 AI 代理与传统脚本相结合，以实现最高效率——允许您对确定性部分进行脚本化，并仅在必要时使用 AI，从而将成本降低 50% 以上，同时提高可靠性。我们让您只需通过一个 API 即可开发、部署和扩展自己的代理及网页自动化任务。更多内容请参阅我们的文档 这里 🔥

开源核心功能：

• 运行网页代理 → 向 AI 代理赋予自然语言任务，在网站上完成操作
• 结构化输出 → 使用 Pydantic 模型获取您所需的精确格式数据
• 站点交互 → 使用 Playwright 兼容原语和自然语言命令观察网站状态、抓取数据并执行操作

API 服务（推荐）

• 隐身浏览器会话 → 内置 CAPTCHA 解决、代理和反检测功能的浏览器实例
• 混合工作流 → 结合脚本和 AI 代理，降低成本并提高可靠性
• 密钥保险库 → 企业级凭据管理，用于存储电子邮件、密码、MFA 令牌、SSO 等
• 数字身份 → 创建具有唯一邮箱、电话和自动 2FA 的数字身份，适用于账户创建流程

快速入门

pip install notte
patchright install --with-deps chromium

在本地模式下运行

使用以下脚本启动一个基于开源功能的代理（您需要自己的 LLM API 密钥）：

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="在 Google 图片上疯狂刷猫 meme")

使用 Python SDK（推荐）

我们还提供了一个便捷的 API，为您托管浏览器会话，并提供丰富的高级功能。要运行代理，您需要先在 Notte 控制台 上注册，并创建一个免费的 Notte API 密钥 🔑

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="在 Google 图片上疯狂刷猫 meme")

我们的设置允许您先在本地进行实验，然后只需替换导入语句并将 notte 对象前缀改为 cli，即可切换到 SDK，获得托管浏览器会话以及高级功能！

基准测试

排名	提供者	代理自评	LLM 评估	每任务耗时	任务可靠性
🏆	Notte	86.2%	79.0%	47s	96.6%
2️⃣	Browser-Use	77.3%	60.2%	113s	83.3%
3️⃣	Convergence	38.4%	31.4%	83s	50%

完整报告请见： https://github.com/nottelabs/open-operator-evals

代理功能

结构化输出

结构化输出是代理运行函数中的一项功能，允许您通过 response_format 参数指定一个 Pydantic 模型。代理将按照指定的结构返回数据。

from notte_sdk import NotteClient
from pydantic import BaseModel

class HackerNewsPost(BaseModel):
    title: str
    url: str
    points: int
    author: str
    comments_count: int

class TopPosts(BaseModel):
    posts: list[HackerNewsPost]

client = NotteClient()
with client.Session(open_viewer=True, browser_type="chrome") as session:
    agent = client.Agent(session=session, reasoning_model='gemini/gemini-2.5-flash', max_steps=15)
    response = agent.run(
        task="前往 Hacker News (news.ycombinator.com)，提取前 5 篇帖子的标题、URL、积分、作者和评论数。",
        response_format=TopPosts,
    )
print(response.answer)

代理保险库

保险库是可以附加到您的代理实例上的工具，用于安全地存储和管理凭据。代理会在需要时自动使用这些凭据。

from notte_sdk import NotteClient

client = NotteClient()

with client.Vault() as vault, client.Session(open_viewer=True) as session:
    vault.add_credentials(
        url="https://x.com",
        username="your-email",
        password="your-password",
    )
    agent = client.Agent(session=session, vault=vault, max_steps=10)
    response = agent.run(
      task="前往 Twitter；登录并进入我的消息",
    )
print(response.answer)

代理角色

角色是您可以附加到代理实例的工具，用于提供具有唯一电子邮件地址、电话号码以及自动处理双因素认证（2FA）功能的数字身份。

from notte_sdk import NotteClient

client = NotteClient()

with client.Persona(create_phone_number=False) as persona:
    with client.Session(browser_type="chrome", open_viewer=True) as session:
        agent = client.Agent(session=session, persona=persona, max_steps=15)
        response = agent.run(
            task="打开 Google 表单并用您的姓名确认参加",
            url="https://forms.google.com/your-form-url",
        )
print(response.answer)

会话功能

隐蔽模式

隐蔽模式功能包括自动解决验证码和代理配置，以提高自动化可靠性和匿名性。

from notte_sdk import NotteClient

client = NotteClient()

# 内置代理与验证码解决功能
with client.Session(
    solve_captchas=True,
    proxies=True,  # 基于美国的代理
    browser_type="chrome",
    open_viewer=True
) as session:
    agent = client.Agent(session=session, max_steps=5)
    response = agent.run(
        task="尝试使用内部工具解决验证码",
        url="https://www.google.com/recaptcha/api2/demo"
    )

# 自定义代理配置
proxy_settings = ExternalProxy(
    server="http://your-proxy-server:port",
    username="your-username",
    password="your-password",
)

with client.Session(proxies=[proxy_settings]) as session:
    agent = client.Agent(session=session, max_steps=5)
    response = agent.run(task="访问某个网站")

文件下载/上传

文件存储允许您将文件上传到会话中，并下载代理在工作过程中获取的文件。这些文件仅限于当前会话范围，并且会在会话生命周期结束后继续保留。

from notte_sdk import NotteClient

client = NotteClient()
storage = client.FileStorage()

# 在代理执行前上传文件
storage.upload("/path/to/document.pdf")

# 创建附带存储的会话
with client.Session(storage=storage) as session:
    agent = client.Agent(session=session, max_steps=5)
    response = agent.run(
        task="将 PDF 文档上传到网站并下载猫的图片",
        url="https://example.com/upload"
    )

# 下载代理下载的文件
downloaded_files = storage.list(type="downloads")
for file_name in downloaded_files:
    storage.download(file_name=file_name, local_dir="./results")

Cookies / 认证会话

Cookies 提供了一种灵活的方式来认证您的会话。虽然我们建议使用安全保险库来管理凭据，但在某些情况下，Cookies 也是一种替代方案。

from notte_sdk import NotteClient
import json

client = NotteClient()

# 上传用于认证的 cookies
cookies = [
    {
        "name": "sb-db-auth-token",
        "value": "base64-cookie-value",
        "domain": "github.com",
        "path": "/",
        "expires": 9778363203.913704,
        "httpOnly": False,
        "secure": False,
        "sameSite": "Lax"
    }
]

with client.Session() as session:
    session.set_cookies(cookies=cookies)  # 或者使用 cookie_file="path/to/cookies.json"
    
    agent = client.Agent(session=session, max_steps=5)
    response = agent.run(
        task="前往 nottelabs/notte 获取仓库信息",
    )
    
    # 从会话中获取 cookies
    cookies_resp = session.get_cookies()
    with open("cookies.json", "w") as f:
        json.dump(cookies_resp, f)

CDP 浏览器兼容性

您可以插入任何您想要的浏览器会话提供商，并在其上使用我们的代理。通过 CDP 使用外部无头浏览器提供商，您可以在任何兼容 CDP 的浏览器上受益于 Notte 的代理能力。

from notte_sdk import NotteClient

client = NotteClient()
cdp_url = "wss://your-external-cdp-url"

with client.Session(cdp_url=cdp_url) as session:
    agent = client.Agent(session=session)
    response = agent.run(task="从 https://www.notte.cc/ 提取定价计划")

混合工作流

Notte 与 Playwright 的高度兼容性使您能够将 Web 自动化原语与代理相结合，针对需要推理和适应性的特定部分进行操作。这种混合方法可以降低 LLM 成本，并且由于对确定性部分使用脚本而仅在必要时使用代理，因此速度更快。

from notte_sdk import NotteClient

client = NotteClient()

with client.Session(open_viewer=True) as session:
    # 首先进行确定性导航
    session.execute(type="goto", url="https://duckduckgo.com/")
    session.execute(type="fill", selector="internal:role=combobox[name=\"Search with DuckDuckGo\"i]", value="nottelabs")
    agent = client.Agent(session=session, max_steps=3)
    # 使用代理来推理下一步
    agent.run(task="打开 nottelabs 的 GitHub 仓库")
    # 使用抓取端点提取数据
    data = session.scrape(instructions="提取星标数量")

代理回退

工作流是一种强大的方式，可以结合脚本和代理来降低成本并提高可靠性。然而，工作流中的确定性部分仍然可能失败。为了优雅地处理这些失败情况，您可以使用 AgentFallback 类：

import notte

with notte.Session() as session:
    _ = session.execute(type="goto", url="https://shop.notte.cc/")
    _ = session.observe()

    with notte.AgentFallback(session, "前往购物车"):
        # 强制执行失败 -> 触发代理回退以优雅地解决问题
        res = session.execute(type="click", id="INVALID_ACTION_ID")

数据抓取

为了快速提取数据，我们提供了一个专门的抓取端点，该端点会自动创建并管理会话。您可以传递自定义指令以生成结构化输出，并启用隐蔽模式。

from notte_sdk import NotteClient
from pydantic import BaseModel

client = NotteClient()

# 简单抓取
response = client.scrape(
    url="https://notte.cc",
    scrape_links=True,
    only_main_content=True
)

# 带有自定义指令的结构化抓取
class Article(BaseModel):
    title: str
    content: str
    date: str

response = client.scrape(
    url="https://example.com/blog",
    response_format=Article,
    instructions="仅提取文章的标题、日期和内容"
)

或者直接使用 cURL：

curl -X POST 'https://api.notte.cc/scrape' \
  -H 'Authorization: Bearer <NOTTE-API-KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://notte.cc",
    "only_main_content": false,
  }'

搜索： 我们构建了一个酷炫的演示，利用 MCP 服务器中的抓取端点，让 LLM 实现 LLM 聊天机器人中的实时搜索——效果非常好！可在以下网址查看：https://search.notte.cc/

许可证

该项目采用服务器端公共许可证 v1 许可。有关详细信息，请参阅 LICENSE 文件。

引用

如果您在研究或项目中使用 Notte，请引用：

@software{notte2025,
  author = {Pinto, Andrea 和 Giordano, Lucas 和 {nottelabs-team}},
  title = {Notte：面向互联网原生智能体系统的软件套件},
  url = {https://github.com/nottelabs/notte},
  year = {2025},
  publisher = {GitHub},
  license = {SSPL-1.0},
  version = {1.4.4},
}

版权所有 © 2025 Notte Labs, Inc.

Notte 快速上手指南

Notte 是一个专为速度、成本效益、可扩展性和可靠性打造的 Web AI Agent 框架。它结合了传统脚本的确定性与 AI 的灵活性，支持混合工作流，可显著降低 LLM 调用成本并提升任务成功率。

环境准备

• 操作系统：Linux, macOS, Windows
• Python 版本：3.11 或更高
• 依赖项：
  • patchright (Playwright 的兼容分支)
  • Chromium 浏览器内核
  • (可选) LLM API Key (如使用本地模式需自备，如 Gemini, OpenAI 等)

安装步骤

1. 安装 Python 包：

pip install notte

2. 安装浏览器依赖（推荐安装 Chromium）：

patchright install --with-deps chromium

💡 国内用户若遇下载慢，可配置环境变量使用国内镜像源加速浏览器下载：

export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright
patchright install --with-deps chromium

基本使用

模式一：本地运行（开源核心功能）

适用于本地测试，需自行配置 LLM API Key（通过 .env 文件或环境变量）。

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")

模式二：使用官方 SDK（推荐）

通过 Notte Console 注册获取 NOTTE_API_KEY，即可使用托管浏览器会话及高级功能（如自动验证码识别、代理、数字身份等）。

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")

✅ 提示：从本地模式切换到 SDK 模式只需替换导入语句和前缀（notte → client），代码结构几乎无需改动。

---

现在你已准备好使用 Notte 构建可靠的 Web 自动化 Agent！更多高级功能（结构化输出、凭证保险库、数字人格、混合工作流等）请参考官方文档。