项目概述

Notte 是一款面向互联网原生代理系统（Internet-native Agentic Systems）的软件套件，旨在为大型语言模型（LLM）代理提供强大的浏览器自动化和网页交互能力。Notte 将互联网转化为一个结构化、可导航的空间，使每个网站都成为智能代理可以精确解读和操作的地图。

资料来源：README.md:1

核心定位

Notte 的核心价值主张在于创建一个可编程的抽象层，覆盖在真实网页之上。通过该技术栈，AI 代理能够：

• 精确解读网页内容结构
• 执行复杂的浏览器交互操作
• 实现端到端的自动化工作流

资料来源：README.md:1

技术架构

包结构

Notte 采用多包架构设计，包含以下核心组件：

资料来源：packages/notte-core/src/notte_core/actions/actions.py:1 资料来源：packages/notte-core/src/notte_core/errors/processing.py:1

架构分层图

graph TD
    A[用户/外部系统] --> B[notte-sdk]
    B --> C[notte-agent]
    C --> D[notte-llm]
    D --> E[notte-core]
    E --> F[浏览器/Playwright]
    F --> G[网页 DOM]

核心功能模块

浏览器动作系统

Notte 定义了一套完整的浏览器动作类型，支持多种交互场景：

# 示例：导航动作
class GotoAction(BrowserAction):
    type: Literal["goto"] = "goto"
    url: str
    description: str = "Goto to a URL"

资料来源：packages/notte-core/src/notte_core/actions/actions.py:1-20

会话管理

Notte SDK 提供了灵活的会话管理能力，支持快速感知和深度感知两种模式：

# 快速感知模式（默认）
obs = session.observe(perception_type='fast')

# 深度感知模式（使用 LLM）
obs = session.observe(perception_type='deep')

# 带指令的感知（自然语言过滤）
actions = session.observe(instructions="Fill the email input")

资料来源：packages/notte-sdk/src/notte_sdk/endpoints/sessions.py:1-30

文档分类与提取

Notte LLM 模块提供了文档分析能力，支持对网页内容进行结构化处理：

资料来源：packages/notte-llm/src/notte_llm/prompts/document-category/base/user.md:1

代理决策系统

Notte Agent 模块实现了基于 LLM 的代理决策引擎，支持：

• 元素识别：通过 ID 系统标识可交互元素（I=输入、B=按钮、L=链接、F=图形、O=选项、M=杂项）
• 动作序列：支持表单填写、导航提取等常见操作序列
• 验证码处理：内置 CAPTCHA 检测和解决机制

graph LR
    A[网页状态] --> B[元素识别]
    B --> C[动作规划]
    C --> D[执行验证]
    D -->|成功| E[下一状态]
    D -->|失败| F[错误处理]

资料来源：packages/notte-agent/src/notte_agent/gufo/system.md:1-40

错误处理机制

Notte 建立了完善的错误处理体系，涵盖内部检查和运行时异常：

资料来源：packages/notte-core/src/notte_core/errors/processing.py:1-40

使用方式

安装

Notte 通过 Python 包管理器分发，可通过标准方式安装。

基本工作流

graph TD
    A[创建会话] --> B[执行动作]
    B --> C[观察状态]
    C --> D{任务完成?}
    D -->|否| B
    D -->|是| E[返回结果]

# 完整示例
obs = session.observe(perception_type='deep')
print(obs.space.description)

资料来源：packages/notte-sdk/src/notte_sdk/endpoints/sessions.py:20-25

项目信息

资料来源：README.md:1-15

引用格式

如需在学术场合引用 Notte，请使用以下 BibTeX 格式：

@software{notte2025,
  author = {Pinto, Andrea and Giordano, Lucas and {nottelabs-team}},
  title = {Notte: Software suite for internet-native agentic systems},
  url = {https://github.com/nottelabs/notte},
  year = {2025},
  publisher = {GitHub},
  license = {SSPL-1.0},
  version = {1.4.4},
}

资料来源：README.md:5-14

环境要求

在开始之前，请确保您的开发环境满足以下要求：

环境配置

获取 API 密钥

1. 访问 notte.cc 并注册账户
2. 在仪表板中生成您的 API 密钥
3. 将密钥安全存储，避免泄露

配置环境变量

创建 .env 文件，参考 .env.example 中的配置模板：

# Notte API 配置
NOTTE_API_KEY=your_api_key_here
NOTTE_API_BASE_URL=https://api.notte.cc  # 可选，默认为官方 API 地址

环境变量说明：

资料来源：.env.example

安装 SDK

使用 pip 安装

pip install notte-sdk

从源码安装

git clone https://github.com/nottelabs/notte.git
cd notte
pip install -e .

核心概念

在深入实践之前，理解以下核心概念有助于更好地使用 Notte SDK：

graph TD
    A[Notte Session] --> B[观察页面]
    A --> C[执行动作]
    A --> D[抓取数据]
    B --> E[获取交互元素]
    C --> F[点击/输入/提交]
    D --> G[结构化输出]
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#fff3e0
    style D fill:#e8f5e9

资料来源：docs/sdk_tutorial.md

基本使用流程

1. 初始化客户端

from notte_sdk import NotteClient

client = NotteClient()

2. 创建会话

session = client.sessions.create()
print(f"会话ID: {session.id}")

3. 导航到目标页面

session.execute(type="goto", url="https://notte.cc")

4. 观察页面元素

# 快速感知模式
obs = session.observe(perception_type="fast")

# 深度感知模式（使用 LLM 格式化）
obs = session.observe(perception_type="deep")

5. 执行动作

# 点击元素
session.execute(type="click", id="B1")

# 输入文本
session.execute(type="fill", id="I1", value="search term")

# 提交表单
session.execute(type="submit", id="B2")

资料来源：docs/sdk_tutorial.md

常见任务示例

网页抓取

Notte 提供强大的网页抓取功能，支持结构化数据提取：

from notte_sdk import NotteClient, NotteScrapeResponse

client = NotteClient()

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

# 带自定义指令的结构化抓取
from pydantic import BaseModel

class Article(BaseModel):
    title: str
    content: str
    date: str

response = client.scrape(
    url="https://example.com/blog",
    response_format=Article,
    instructions="Extract only the title, date and content of the articles"
)

抓取参数说明：

动作观察与过滤

使用自然语言指令快速定位交互元素：

session.execute(type="goto", url="https://console.notte.cc")

# 使用自然语言过滤动作空间
actions = session.observe(instructions="Fill the email input")
print(actions[0].model_dump())

使用 cURL 直接调用 API

如果您偏好使用 HTTP 直接调用：

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,
  }'

错误处理

常见错误及解决方案

重试机制

Notte SDK 支持自动重试机制，您可以在执行动作时配置：

session.execute(
    type="click",
    id="B1",
    raise_on_failure=True  # 失败时抛出异常
)

下一步

• 阅读完整的 SDK 教程 深入了解高级功能
• 查看 API 参考文档 了解完整的 API 接口
• 探索 示例代码库 获取更多实践案例

相关资源

• 官方文档：https://docs.notte.cc
• API 密钥管理：https://console.notte.cc
• 搜索演示：https://search.notte.cc

概述

Notte 是一个面向互联网原生代理系统（Internet-native Agentic Systems）的软件套件，采用模块化架构设计。整个项目由多个独立的功能包组成，通过清晰的依赖关系组织，形成一套完整的浏览器自动化与LLM交互解决方案。

项目根目录下包含 packages/ 子目录，其中包含六个核心包：

架构层次

graph TD
    subgraph "notte-llm"
        LLM_Prompts["提示词模板"]
        LLM_Output["输出解析"]
    end
    
    subgraph "notte-core"
        Core_Actions["动作定义"]
        Core_Observation["观察数据模型"]
        Core_Errors["错误处理"]
    end
    
    subgraph "notte-browser"
        Browser_Control["浏览器控制"]
        Page_Scraping["页面抓取"]
    end
    
    subgraph "notte-agent"
        Agent_Executor["Agent执行器"]
        Agent_Gufo["Gufo系统"]
    end
    
    subgraph "notte-sdk"
        SDK_Client["客户端封装"]
        Session_Management["会话管理"]
    end
    
    subgraph "notte-mcp"
        MCP_Server["MCP服务器"]
        MCP_Tools["工具定义"]
    end
    
    LLM_Prompts --> Core_Actions
    Core_Actions --> Browser_Control
    Agent_Executor --> Core_Actions
    Agent_Executor --> LLM_Prompts
    SDK_Client --> Session_Management
    SDK_Client --> Agent_Executor
    MCP_Server --> SDK_Client
    MCP_Tools --> MCP_Server

各包详细分析

notte-core

功能定位：基础层，提供整个项目的基础数据类型、动作定义、观察结果模型和错误处理机制。

源码结构：

notte-core/src/notte_core/
├── actions/
│   └── actions.py          # 动作类型定义（goto、click、fill等）
├── observation/
│   └── data models         # 页面观察数据结构
├── errors/
│   └── processing.py       # 错误类定义
└── pruning.py              # 树剪枝算法

核心模块：

关键类型定义（来源：packages/notte-core/src/notte_core/actions/actions.py）：

• ScrapeAction：页面数据抓取，支持指令过滤、选择器范围限定
• GotoAction：页面导航
• ClickAction：元素点击
• FillAction：表单填充

notte-browser

功能定位：浏览器控制层，基于Playwright实现浏览器自动化操作。

依赖关系：

[project.dependencies]
playwright = ">=1.41.0"

核心功能：

notte-agent

功能定位：智能代理层，实现LLM驱动的自动化决策和执行。

源码结构：

notte-agent/src/notte_agent/
├── gufo/
│   └── system.md           # Gufo系统提示词
└── 执行器                  # Agent核心逻辑

核心能力：

Agent执行流程（来源：packages/notte-sdk/src/notte_sdk/endpoints/sessions.py）：

# 会话创建
with client.Session() as session:
    session.execute(type="goto", url="https://example.com")
    obs = session.observe(perception_type='deep')
    # Agent决策循环...

notte-sdk

功能定位：Python客户端SDK，封装所有API调用和会话管理。

核心组件：

会话管理（来源：packages/notte-sdk/src/notte_sdk/endpoints/sessions.py）：

class Session:
    """会话上下文管理器"""
    
    def __init__(self, cookie_file=None):
        self._cookie_file = cookie_file
    
    def __enter__(self):
        self.start()
        return self
    
    def __exit__(self, exc_type, exc_val, exc_tb):
        self.stop()
    
    def observe(self, perception_type='fast', instructions=None):
        """观察页面可用动作"""
        
    def execute(self, type, **kwargs):
        """执行动作"""

观察类型：

notte-llm

功能定位：LLM交互层，处理提示词模板和响应解析。

源码结构：

notte-llm/src/notte_llm/prompts/
├── action-listing/         # 动作列表生成
├── data-extraction/        # 数据提取
├── document-category/      # 文档分类
├── extract-without-json-schema/  # 无schema提取
└── debug-failing-action-exec/    # 调试失败动作

提示词模板：

文档分类类别（来源：packages/notte-llm/src/notte_llm/prompts/document-category/base/user.md）：

notte-mcp

功能定位：Model Context Protocol服务器集成，提供标准化工具接口。

工具列表（来源：packages/notte-mcp/README.md）：

使用方式：

pip install notte-mcp
export NOTTE_API_KEY="your-api-key"
python -m notte_mcp.server

依赖关系

graph LR
    SDK["notte-sdk"] --> Agent["notte-agent"]
    SDK --> Browser["notte-browser"]
    Agent --> LLM["notte-llm"]
    Agent --> Core["notte-core"]
    Browser --> Core
    MCP["notte-mcp"] --> SDK

依赖矩阵：

入口点设计

SDK入口

from notte_sdk import NotteClient

client = NotteClient()

MCP服务器入口

python -m notte_mcp.server

CLI入口

项目提供命令行接口进行快速操作：

notte <command> [options]

错误处理体系

Notte采用分层错误处理机制（来源：packages/notte-core/src/notte_core/errors/processing.py）：

许可证

整个项目采用 Server Side Public License v1.0 (SSPL-1.0) 许可证发布。

引用信息

如需在学术场合引用本项目，请使用以下BibTeX格式：

@software{notte2025,
  author = {Pinto, Andrea and Giordano, Lucas and {nottelabs-team}},
  title = {Notte: Software suite for internet-native agentic systems},
  url = {https://github.com/nottelabs/notte},
  year = {2025},
  publisher = {GitHub},
  license = {SSPL-1.0},
  version = {1.4.4},
}

1. 模块概述

Notte 项目的核心模块实现涵盖了浏览器自动化代理系统的关键组件，包括动作执行系统、页面观察机制、DOM 树处理、快照管理和凭证安全系统。这些模块共同构成了一个完整的网页自动化框架，使 AI 代理能够精确地与网页元素进行交互。

核心模块的架构设计遵循分层职责原则，将浏览器操作、页面解析、状态管理和安全控制分离到不同的子模块中，每个模块专注于特定的功能域，通过标准化的接口进行通信和数据交换。

2. 动作执行系统

2.1 动作类型体系

动作执行系统是 Notte 自动化框架的核心，负责定义和管理所有可执行的浏览器操作。系统采用类继承结构，通过基类 BrowserAction 定义通用接口，具体动作类实现各自的业务逻辑。

基类 BrowserAction 定义了动作执行的通用接口，包括执行消息生成、参数规范和示例数据提供。每个具体动作类都实现了这些抽象方法，确保动作执行的标准化和可预测性。

2.2 动作执行流程

动作执行采用统一的调用模式，通过 execute() 方法触发。执行流程首先验证动作参数的有效性，然后调用底层的 Playwright 或类似浏览器自动化引擎执行实际操作，最后返回执行结果。

graph TD
    A[创建动作实例] --> B[验证参数]
    B --> C{参数有效?}
    C -->|是| D[执行动作]
    C -->|否| E[抛出验证错误]
    D --> F{执行成功?}
    F -->|是| G[返回 ExecutionResult]
    F -->|否| H[记录错误信息]
    G --> I[更新会话状态]
    H --> I

2.3 动作参数定义

每个动作类通过 param 属性提供参数规范，包括参数名称、数据类型和约束条件。这种设计使动作系统具备自描述能力，便于 LLM 代理理解和使用。

@property
@override
def param(self) -> ActionParameter | None:
    return ActionParameter(name="url", type="str")

参数规范采用强类型定义，支持字符串、整数、布尔值和复杂对象类型。系统自动进行类型检查和转换，减少运行时错误的发生。

3. 页面观察机制

3.1 观察类型

页面观察机制负责分析当前页面状态并生成可交互元素列表。系统支持多种观察深度，以适应不同场景的性能和精度需求。

快速感知模式使用简化的页面解析逻辑，直接从浏览器的可访问性树中提取元素信息，适用于需要快速响应的场景。深度感知模式则调用 LLM 对页面进行更深入的分析，生成更结构化的交互空间表示。

3.2 观察响应结构

观察结果通过 ObserveResponse 类型封装，包含当前页面 URL、可交互元素列表和空间描述信息。这种结构化输出便于代理理解页面状态并规划后续动作。

graph LR
    A[页面 HTML] --> B[DOM 树解析]
    B --> C[可访问性树生成]
    C --> D{观察类型}
    D -->|fast| E[快速元素提取]
    D -->|deep| F[LLM 结构化分析]
    E --> G[ObserveResponse]
    F --> G

3.3 指令过滤机制

观察系统支持通过自然语言指令过滤可交互元素。当提供 instructions 参数时，系统会解析指令语义，仅返回符合条件的目标元素，显著减少动作空间大小，提高代理决策效率。

actions = session.observe(instructions="Fill the email input")
print(actions[0].model_dump())

这种设计使开发者能够用自然语言描述交互意图，系统自动完成元素筛选和动作空间构建，降低了自动化脚本的编写难度。

4. DOM 树处理

4.1 树结构设计

DOM 树模块负责将原始 HTML 文档解析为可编程访问的树形数据结构。树节点包含元素类型、属性、内容和层级关系，支持高效的遍历和查询操作。

graph TD
    A[HTML 文档] --> B[解析器]
    B --> C[根节点]
    C --> D[head 节点]
    C --> E[body 节点]
    E --> F[交互元素]
    E --> G[文本节点]
    D --> H[元数据节点]

每个树节点关联唯一的标识符，用于在观察响应中引用具体元素。节点同时记录可访问性属性，如角色、名称和状态，这些属性决定了元素的交互方式。

4.2 可访问性树

Notte 使用可访问性树（Accessibility Tree）作为页面元素的主要表示形式，相比原始 DOM 树提供了更丰富的语义信息。可访问性树去除了装饰性元素，保留功能性内容，使代理能够更准确地理解页面结构。

4.3 节点遍历与查询

DOM 树模块提供多种遍历和查询方法，支持按标签名、类名、ID 或 XPath 表达式定位节点。查询结果可进一步用于动作生成或内容提取。

5. 快照管理

5.1 快照概念

快照（Snapshot）是 Notte 系统记录页面状态的机制，每次页面变化后系统自动生成新的快照。快照包含完整的页面 DOM 结构、可访问性树和元数据，支持历史回溯和状态对比。

快照管理器维护快照的历史记录，通过版本号或时间戳标识不同状态的快照。代理可以查询历史快照以了解页面变化过程，或在执行操作前保存当前状态以便回滚。

5.2 快照数据结构

class Snapshot:
    id: str
    url: str
    dom_tree: DOMTree
    accessibility_tree: A11yTree
    timestamp: datetime
    metadata: dict

快照数据存储为只读对象，确保历史状态的完整性和一致性。系统支持快照的序列化和反序列化，便于分布式环境下的状态共享。

5.3 快照与观察的关系

观察操作基于当前快照执行，每次观察都会创建新的快照记录。观察结果中的元素标识符与快照中的节点一一对应，保证动作执行的精确性。

graph LR
    A[执行动作] --> B[页面更新]
    B --> C[生成新快照]
    C --> D[新快照 ID]
    D --> E[观察结果引用新元素]

6. 凭证管理系统

6.1 凭证架构

凭证管理系统（Vault）负责安全存储和管理敏感信息，如登录凭据、API 密钥和认证令牌。系统采用分层架构，将凭证存储与业务逻辑分离，支持多种后端存储实现。

graph TD
    A[代理请求凭证] --> B[Vault 接口]
    B --> C{凭证类型}
    C -->|API 密钥| D[KeyVault]
    C -->|用户名密码| E[CredentialVault]
    C -->|OAuth 令牌| F[TokenVault]
    D --> G[安全存储]
    E --> G
    F --> G

6.2 凭证基类设计

class NotteBaseError(Exception):
    def __init__(
        self,
        agent_message: str,
        user_message: str,
        dev_message: str,
    ) -> None:
        self.agent_message = agent_message
        self.user_message = user_message
        self.dev_message = dev_message

凭证系统定义统一的异常类型，包含面向代理、用户和开发者的不同错误消息，便于问题的诊断和修复。当凭证操作失败时，系统根据上下文选择合适的错误消息返回。

6.3 占位符机制

代理通过占位符（Placeholder）引用凭证，系统在动作执行时自动替换占位符为实际凭证值。这种设计避免敏感信息硬编码在动作参数中，提高系统的安全性。

7. AST 抽象语法树

AST 模块提供网页内容的结构化表示能力，将无结构的 HTML/CSS/JavaScript 转换为可编程访问的语法树。该模块是高级自动化能力的基础，支持复杂页面结构的理解和操作。

7.1 AST 与 DOM 的关系

AST 与 DOM 树既有联系又有区别。DOM 树侧重于文档结构表示，AST 则更关注代码语义的表达。对于 JavaScript 代码，AST 能够解析变量声明、函数调用和控制流结构，为代码级别的自动化操作提供可能。

7.2 节点类型系统

AST 定义了丰富的节点类型，覆盖 JavaScript 语言的各种语法结构。常见节点类型包括：

• 声明节点：变量声明、函数声明、类声明
• 表达式节点：二元表达式、函数调用、成员访问
• 控制流节点：条件语句、循环语句、异常处理
• 结构节点：对象字面量、数组字面量

节点类型系统支持 Visitor 模式遍历，代理可以实现自定义的节点处理器来执行特定的代码分析或转换任务。

8. 错误处理机制

8.1 错误分类体系

Notte 定义了完善的错误分类体系，根据错误来源和性质分为不同类别：

8.2 错误消息设计

每个错误类型包含面向不同角色的消息：

• 开发消息（dev_message）：详细的调试信息和修复建议
• 代理消息（agent_message）：代理可理解的错误描述和替代建议
• 用户消息（user_message）：面向终端用户的友好提示

这种多层次的消息设计确保错误信息在开发、调试和生产环境中都能发挥作用。

9. 模块间协作

9.1 会话生命周期

会话（Session）是 Notte 系统的核心概念，贯穿所有模块的协作过程。会话管理器的实现整合了动作执行、页面观察和快照管理功能：

with client.Session() as session:
    session.execute(type="goto", url="https://example.com")
    obs = session.observe()
    markdown = session.scrape()

会话提供上下文管理器支持，自动处理资源清理和状态同步。当会话结束时，系统自动保存 Cookie 状态并释放浏览器资源。

9.2 数据流总览

graph TD
    A[用户请求] --> B[会话管理器]
    B --> C[动作系统]
    C --> D[浏览器引擎]
    D --> E[页面快照]
    E --> F[DOM 树]
    F --> G[可访问性树]
    G --> H[观察服务]
    H --> I[代理决策]
    I --> C
    E --> J[凭证系统]
    J --> C

数据流展示了从用户请求到代理决策的完整链路。各模块通过标准化的数据结构和接口进行交互，保证系统的可扩展性和可维护性。

9.3 状态同步机制

会话维护当前的页面快照引用，当页面发生变化时自动更新。观察操作返回的是基于最新快照的元素列表，动作执行后触发新的快照生成，形成闭环的状态同步机制。

10. 总结

核心模块实现构成了 Notte 自动化框架的技术基础，通过动作系统、页面观察、DOM 处理、快照管理和凭证安全五大支柱，为 AI 代理提供完整的网页交互能力。这些模块相互协作，形成了一套从页面解析到动作执行的完整工作流，支持复杂场景下的自动化任务。

概述

Notte Agent 是一个精确的浏览器自动化代理系统，通过结构化命令与网站进行交互。该系统能够分析网页元素和结构，规划动作序列，并以JSON格式响应动作执行结果和状态评估。Agent架构支持多种底层浏览器自动化引擎（包括Falco和Gufo），并通过统一的接口提供网页浏览、内容提取、表单填写等核心功能。

资料来源：packages/notte-agent/src/notte_agent/falco/system.md

架构设计

整体架构

Notte Agent采用分层架构设计，核心组件包括：

资料来源：packages/notte-agent/src/notte_agent/falco/prompt.py

引擎抽象层

系统通过抽象层支持多种浏览器自动化引擎：

graph TD
    A[Agent基类] --> B[Falco Agent]
    A --> C[Gufo Agent]
    B --> D[Falco引擎]
    C --> E[Gufo引擎]
    D --> F[Playwright/CDP]
    E --> G[浏览器实例]

Falco和Gufo作为两种独立的Agent实现，共同继承自基础Agent接口，提供一致的外部行为但使用不同的底层浏览器控制机制。

资料来源：packages/notte-agent/src/notte_agent/agent.py

元素标识系统

ID编码规范

Agent使用标准化的元素标识系统，每个可交互元素的ID遵循特定编码规则：

graph LR
    A[ID格式] --> B[角色前缀]
    A --> C[索引号]
    A --> D[分隔符]
    
    B --> E[I: 输入字段]
    B --> F[B: 按钮]
    B --> G[L: 链接]
    B --> H[F: 图片/图表]
    B --> I[O: 选择选项]
    B --> J[M: 杂项元素]

角色前缀对照表

ID的完整格式为<角色前缀><索引号>，例如B1表示第一个按钮，I2表示第二个输入字段。

资料来源：packages/notte-agent/src/notte_agent/falco/system.md

动作系统

动作类型

Agent支持多种类型的浏览器自动化动作：

表单填写动作格式

{
  "type": "form_fill",
  "value": {
    "address1": "<地址>",
    "city": "<城市>",
    "state": "<州/省份>"
  }
}

CAPTCHA处理规则

Agent对验证码处理有严格的规范：

• 禁止行为：直接点击验证码元素（按钮、复选框、图片等），或对验证码元素执行"click"、"type"等动作
• 正确处理：检测到验证码（reCAPTCHA、hCaptcha、图像验证等）时，必须使用CaptchaSolveAction并指定正确的验证码类型
• 支持类型：包括"我不是机器人"复选框、图像选择网格、文本验证挑战等

资料来源：packages/notte-agent/src/notte_agent/falco/system.md

Agent生命周期

创建与启动

使用NotteClient创建Agent实例：

from notte_sdk import NotteClient

notte = NotteClient()

with notte.Session(open_viewer=True) as session:
    agent = notte.Agent(session=session)
    agent.start(
        task="Summarize the content of the page",
        url="https://www.google.com"
    )

状态管理

Agent具有完整的状态管理机制：

列表与停止操作

# 列出所有活跃的Agent
agents = notte.agents.list()

# 停止指定的Agent
agent.stop()

# 获取Agent状态
status = agent.status()

资料来源：packages/notte-sdk/README.md

工作流编排

Workflow组件

Workflow用于编排复杂的多步骤自动化任务，支持：

• 步骤序列定义
• 条件分支处理
• 错误恢复机制
• 结果状态传递

graph TD
    A[开始] --> B[步骤1: 页面导航]
    B --> C[步骤2: 元素观察]
    C --> D{条件判断}
    D -->|成功| E[步骤3: 表单填写]
    D -->|失败| F[备用方案]
    E --> G[步骤4: 内容提取]
    F --> G
    G --> H[完成]

Fallback机制

Agent支持降级（Fallback）机制，当主要实现无法完成任务时自动切换到备用方案：

# agent_fallback.py 提供了降级策略定义

资料来源：packages/notte-agent/src/notte_agent/workflow.py

对话管理

Conversation组件

Conversation模块管理Agent与用户之间的交互历史：

class Conversation:
    def __init__(self):
        # 初始化对话历史记录
        pass
    
    def add_message(self, role: str, content: str):
        # 添加消息到历史
        pass
    
    def get_history(self):
        # 获取完整对话历史
        pass

对话历史对于维护Agent状态上下文、支持多轮交互任务至关重要。

资料来源：packages/notte-agent/src/notte_agent/common/conversation.py

输入结构规范

页面信息格式

Agent接收的页面信息包含以下核心字段：

元素列表格式

# 主导航菜单
* `B1`: 提交表单按钮
* `I1`: 用户名输入框
* `I2`: 密码输入框

# 内容区域
* `L1`: 文章链接
* `F1`: 特色图片

响应格式规范

JSON响应结构

Agent必须始终以有效的JSON格式响应：

{
  "action": {
    "type": "click",
    "id": "B1"
  },
  "reasoning": "点击提交按钮以完成表单提交",
  "state_assessment": "表单已填写完毕，可以提交"
}

动作执行结果

每个动作执行后返回的结果包含：

最佳实践

元素ID稳定性

重要提示：ID会在每个步骤发生变化，不要假设历史记录中的ID仍然存在或对应相同的元素。每次观察页面时都应重新获取当前的元素ID。

动作序列规划

1. 观察页面结构，获取可用元素
2. 分析任务需求，规划动作序列
3. 按顺序执行动作，每次观察页面变化
4. 验证动作结果，必要时调整后续动作

错误处理

Agent内置了完善的错误处理机制：

• InvalidInternalCheckError：内部检查失败
• InvalidA11yTreeType：无障碍树类型错误
• InvalidPlaceholderError：占位符处理错误
• ScrapeFailedError：内容提取失败

资料来源：packages/notte-core/src/notte_core/errors/processing.py

概述

结构化输出是 Notte 框架中用于将网页内容转换为机器可读格式的核心能力。该功能允许用户通过自然语言指令或 JSON Schema 定义，从非结构化的网页文档中提取结构化数据，并将其用于后续的 AI Agent 工作流中。

Notte 的结构化输出系统包含以下几个核心组成部分：

资料来源：packages/notte-core/src/notte_core/actions/actions.py:1-100

工作原理

流程架构

graph TD
    A[用户发起请求] --> B[配置输出格式]
    B --> C{输出类型}
    C -->|JSON Schema| D[使用 extract-json-schema]
    C -->|自然语言| E[使用 extract-without-json-schema]
    C -->|分类| F[使用 document-category]
    D --> G[调用 LLM]
    E --> G
    F --> G
    G --> H[LLM 返回 Markdown/JSON]
    H --> I[解析引擎提取数据]
    I --> J{格式验证}
    J -->|通过| K[返回结构化数据]
    J -->|失败| L[抛出 LLMParsingError]

核心机制

Notte 的结构化输出依赖于 LLM 解析引擎的标签解析能力。引擎通过识别特定的 XML 风格标签来提取内容：

# packages/notte-llm/src/notte_llm/engine.py
class SomeParser:
    def parse(self, text: str) -> str:
        # 支持外层标签解析
        if self.outer_tag:
            pattern = f"<{self.outer_tag}>(.*?)</{self.outer_tag}>"
            match = re.search(pattern, content, re.DOTALL)
            
        # 支持内层代码块解析
        if self.inner_tag:
            pattern = f"```{self.inner_tag}(.*?)```"
            match = re.search(pattern, content, re.DOTALL)

引擎支持两层解析：

1. 外层标签解析：提取 <document-analysis> 等 XML 标签内的内容
2. 内层代码块解析：从 markdown 代码块中提取具体数据

资料来源：packages/notte-llm/src/notte_llm/engine.py:1-50

输出格式配置

使用 JSON Schema

通过 response_format 参数指定 JSON Schema 定义输出结构：

from notte_sdk import NotteClient

client = NotteClient()
response = client.scrape(
    url="https://example.com/blog",
    response_format={
        "type": "object",
        "properties": {
            "title": {"type": "string"},
            "content": {"type": "string"},
            "date": {"type": "string"}
        }
    }
)

使用 Pydantic 模型

通过 Pydantic BaseModel 定义数据结构，实现类型安全的结构化输出：

from pydantic import BaseModel
from notte_sdk import NotteClient

class Article(BaseModel):
    title: str
    content: str
    date: str

client = NotteClient()
response = client.scrape(
    url="https://example.com/blog",
    response_format=Article,
    instructions="Extract only the title, date and content of the articles"
)

资料来源：README.md:1-100

ScrapeAction 参数详解

主要内容提取

当 only_main_content=True 时，系统会自动排除导航栏、页脚等非核心内容：

session.execute(
    type="scrape",
    only_main_content=True  # 排除导航栏和页脚
)

选择器作用域

使用 Playwright 选择器将提取范围限定在特定 DOM 元素内：

session.execute(
    type="scrape",
    selector="#main-content"  # 仅提取 main-content 内的内容
)

资料来源：packages/notte-core/src/notte_core/actions/actions.py:1-100

Prompt 模板系统

数据提取模板

数据提取模板定义了从网页文档中提取结构化信息的指导原则：

# 数据提取输出规范

## <document-analysis> 部分
- 逻辑分解网页文档为有意义的章节
- 描述每个部分的内容，聚焦文本元素
- 为重复或结构化数据包含子章节

## <data-extraction> 部分
- 使用 Markdown 标题、表格、列表格式化数据
- 重复数据使用 Markdown 表格展示
- 所有原始字段必须包含在表格中

资料来源：packages/notte-llm/src/notte_llm/prompts/data-extraction/user.md:1-50

文档分类模板

Notte 支持自动识别网页类型，可分类为：

<document-category>
[文档分类理由的详细分析，包括引用和论证...]
<document-category-answer>search-results</document-category-answer>
</document-category>

资料来源：packages/notte-llm/src/notte_llm/prompts/document-category/base/user.md:1-50

使用示例

示例：Nike 产品抓取

完整的结构化输出工作流示例：

from notte_sdk import NotteClient
from pydantic import BaseModel

class Product(BaseModel):
    name: str
    price: str
    sizes: list[str]
    colors: list[str]

client = NotteClient()
with client.Session() as session:
    session.execute(type="goto", url="https://www.nike.com")
    
    response = session.execute(
        type="scrape",
        response_format=Product,
        instructions="Extract product name, price, available sizes and colors"
    )

示例：分类与数据提取结合

graph LR
    A[访问网页] --> B[document-category]
    B --> C{分类结果}
    C -->|search-results| D[提取列表数据]
    C -->|item| E[提取详情数据]
    C -->|other| F[提取导航信息]
    D --> G[返回结构化JSON]
    E --> G
    F --> G

错误处理

LLMParsingError

当 LLM 返回格式不符合预期时，引擎会抛出解析错误：

# packages/notte-llm/src/notte_llm/engine.py
if self.fail_if_outer_tag:
    raise LLMParsingError(
        f"No content found within <{self.outer_tag}> tags in the response: {text}"
    )

if self.fail_if_inner_tag:
    raise LLMParsingError(
        f"No content found within ```{self.inner_tag}``` blocks in the response: {text}"
    )

常见错误场景

最佳实践

1. 优先使用 Pydantic 模型：通过类型提示获得更好的 IDE 支持和验证
2. 明确的提取指令：使用自然语言清晰描述需要提取的字段
3. 合理设置作用域：使用 selector 减少无关内容的干扰
4. 启用主要内容提取：设置 only_main_content=True 排除噪音

相关链接

• ScrapeAction API 文档
• LLM 解析引擎
• Prompt 模板目录

概述

会话管理系统（Session Management System）是 Notte 项目中负责管理浏览器会话的核心模块。该系统提供了创建、控制、监控和终止浏览器会话的完整生命周期管理功能。Notte 的会话管理基于 Playwright 浏览器自动化框架，支持 Chrome 等多种浏览器的自动化控制。

会话管理系统的主要职责包括：

• 创建和管理浏览器会话实例
• 处理会话的启动和停止
• 管理会话级别的 Cookie 和浏览器状态
• 提供页面观察（Observe）和动作执行（Execute）能力
• 支持 CDP（Chrome DevTools Protocol）集成
• 提供隐匿性功能（Stealth），包括代理配置和 CAPTCHA 处理

资料来源：packages/notte-sdk/src/notte_sdk/endpoints/sessions.py

核心架构

系统组件关系

graph TD
    A[NotteClient] --> B[Session]
    B --> C[BrowserController]
    C --> D[PlaywrightBrowser]
    C --> E[CDPSession]
    B --> F[Cookie管理]
    B --> G[Proxy配置]
    B --> H[观察与执行]

Notte 会话管理系统采用分层架构设计：

资料来源：packages/notte-browser/src/notte_browser/controller.py

关键模块

会话生命周期

状态机模型

stateDiagram-v2
    [*] --> Created: 初始化
    Created --> Starting: session.start()
    Starting --> Running: 浏览器就绪
    Running --> Executing: 执行动作
    Executing --> Running: 动作完成
    Running --> Stopping: session.stop()
    Stopping --> Stopped: 清理完成
    Stopped --> [*]
    
    Running --> Error: 异常发生
    Error --> Stopped: 错误处理

创建会话

会话可以通过 NotteClient 的 Session() 方法创建，支持上下文管理器（with语句）自动管理生命周期。

from notte_sdk import NotteClient

client = NotteClient()
with client.Session() as session:
    session.execute(type="goto", url="https://example.com")

资料来源：packages/notte-sdk/src/notte_sdk/endpoints/sessions.py:50-60

会话配置参数

浏览器控制器

BrowserController 抽象

BrowserController 是浏览器控制的核心抽象类，定义了浏览器操作的统一接口。

资料来源：packages/notte-browser/src/notte_browser/controller.py

PlaywrightBrowser 实现

PlaywrightBrowser 是基于 Playwright 框架的浏览器实现，负责底层的浏览器启动、页面导航、元素交互等操作。

# Playwright 浏览器核心功能
- 启动浏览器实例
- 创建新页面/标签页
- 执行页面导航
- 元素定位和交互
- 截图和页面内容抓取

资料来源：packages/notte-browser/src/notte_browser/playwright.py

CDP Session 实现

CDP（Chrome DevTools Protocol）会话提供了与 Chrome 浏览器的深层集成能力，适用于高级自动化场景。

from notte_integrations.sessions.cdp_session import CDPSession

# CDP 会话功能
- 实时网络监控
- JavaScript 执行拦截
- 性能分析
- 控制台日志捕获

资料来源：packages/notte-integrations/src/notte_integrations/sessions/cdp_session.py

会话观察与动作执行

观察机制（Observe）

观察机制用于获取当前页面的可交互元素列表，生成动作空间（Action Space）。

# 快速观察（简单页面感知）
obs = session.observe(perception_type='fast')

# 深度观察（LLM格式化）
obs = session.observe(perception_type='deep')

# 带指令的观察
actions = session.observe(instructions="填写邮箱输入框")

资料来源：packages/notte-sdk/src/notte_sdk/endpoints/sessions.py:100-120

动作执行（Execute）

执行机制支持多种浏览器操作类型：

资料来源：packages/notte-core/src/notte_core/actions/actions.py

Cookie 管理

自动Cookie保存

会话停止时自动保存Cookie到指定文件：

with client.Session(_cookie_file="cookies.json") as session:
    # 访问需要登录的网站
    session.execute(type="goto", url="https://example.com")
# 退出时会话自动保存Cookie

Cookie持久化机制

sequenceDiagram
    participant Session
    participant Client
    participant Browser
    participant CookieFile
    
    Session->>Browser: 执行操作
    Session->>Session: session.stop()
    Session->>Browser: get_cookies()
    Browser->>Session: cookies_data
    Session->>CookieFile: create_or_append_cookies_to_file()
    CookieFile->>CookieFile: 保存Cookie

资料来源：packages/notte-sdk/src/notte_sdk/endpoints/sessions.py:40-48

隐匿性功能（Stealth）

代理配置

Notte 支持内置代理配置，用于增强自动化任务的匿名性：

with client.Session(
    proxies=True,  # 启用内置代理（默认美国节点）
    browser_type="chrome",
    open_viewer=True
) as session:
    agent = client.Agent(session=session, max_steps=5)
    response = agent.run(
        task="执行任务",
        url="https://example.com"
    )

自定义代理

from notte_sdk import NotteClient, ExternalProxy

client = NotteClient()

proxy_settings = ExternalProxy(
    server="http://your-proxy-server:port",
    username="your-username",
    password="your-password"
)

with client.Session(proxy=proxy_settings) as session:
    pass

CAPTCHA处理

Notte 内置CAPTCHA自动解决功能：

with client.Session(
    solve_captchas=True,
    browser_type="chrome"
) as session:
    # 系统会自动检测和处理CAPTCHA
    session.execute(type="goto", url="https://example.com/recaptcha")

API 参考

NotteClient.Session()

创建新的浏览器会话。

签名：

def Session(
    self,
    browser_type: str = "chrome",
    open_viewer: bool = False,
    proxies: bool = False,
    solve_captchas: bool = False,
    timeout_minutes: int = 5,
    _cookie_file: str | None = None,
) -> Session:

返回值： Session 实例

Session.execute()

执行浏览器动作。

签名：

def execute(
    self,
    type: Literal["goto", "goto_new_tab", "close_tab", "scrape", ...],
    **kwargs
) -> ExecutionResult:

Session.observe()

观察当前页面，生成动作空间。

签名：

def observe(
    self,
    perception_type: Literal["fast", "deep"] = "fast",
    instructions: str | None = None,
    **kwargs
) -> ObserveResponse | list[InteractionActionUnion]:

最佳实践

1. 使用上下文管理器

始终使用 with 语句管理会话，确保资源正确释放：

# 推荐写法
with client.Session() as session:
    session.execute(type="goto", url="https://example.com")

# 不推荐：需要手动调用stop()
session = client.Session()
try:
    session.start()
    session.execute(type="goto", url="https://example.com")
finally:
    session.stop()

2. Cookie复用

对于需要登录的网站，使用Cookie持久化避免重复登录：

# 首次登录并保存Cookie
with client.Session(_cookie_file="session.json") as session:
    session.execute(type="goto", url="https://example.com/login")
    # 执行登录操作...

# 后续请求复用Cookie
with client.Session(_cookie_file="session.json") as session:
    session.execute(type="goto", url="https://example.com/protected")

3. 合理选择感知类型

错误处理

常见错误

错误恢复

from notte_sdk import NotteClient

client = NotteClient()

try:
    with client.Session() as session:
        session.execute(type="goto", url="https://example.com")
except Exception as e:
    # 错误日志记录
    print(f"会话执行错误: {e}")
    # 重新创建会话

相关文档

• Agent 系统
• 动作系统
• 观察系统
• MCP 集成

概述

动作执行系统是 Notte 项目中负责与网页进行交互的核心模块。该系统定义了 Agent 可以执行的所有浏览器操作类型，包括页面导航、表单填充、元素点击、数据提取等。动作执行系统通过结构化的动作定义和统一的执行接口，使 AI Agent 能够以编程方式控制浏览器行为。

系统架构遵循模块化设计原则，核心动作定义位于 notte_core 包中，而具体执行逻辑则在 notte_browser 和 notte_agent 包中实现。SDK 层提供了面向用户的简洁 API，隐藏了底层复杂性。

动作类型体系

Notte 的动作系统采用类型字面量（Literal Types）定义所有支持的浏览器操作。每一类动作都有明确的类型标识符、参数定义和执行消息。

基础动作类型

导航动作

#### GotoAction

导航到指定 URL 是最基础的浏览器操作。GotoAction 接收一个 URL 参数，并将当前页面导航至该地址。

class GotoAction(BrowserAction):
    type: Literal["goto"] = "goto"
    description: str = "Navigate to a URL"
    url: str

    def execution_message(self) -> str:
        return f"Navigated to '{self.url}'"

示例：

session.execute(type="goto", url="https://www.example.com")

#### GotoNewTabAction

在新的浏览器标签页中打开 URL。此动作不影响当前页面的状态。

示例：

session.execute(type="goto_new_tab", url="https://www.example.com")

#### CloseTabAction

关闭当前活跃的浏览器标签页。如果关闭的是最后一个标签页，浏览器会话将保持但显示空白页面。

交互动作

#### ClickAction

点击页面上的可交互元素，如按钮、链接等。元素通过系统分配的 ID 标识。

#### HoverAction

将鼠标悬停在指定元素上，通常用于触发下拉菜单或显示隐藏内容。

#### SelectOptionAction

从 <select> 下拉列表中选择选项。需要指定目标元素 ID 和要选择的选项值。

表单处理

#### FormFillAction

表单填写是网页交互中最常见的操作之一。FormFillAction 支持批量填写多个字段，支持多种输入类型。

# 示例：填写地址表单
form_values = {
    "address1": "123 Main St",
    "city": "San Francisco",
    "state": "CA"
}
session.execute(type="form_fill", value=form_values)

系统会自动识别目标元素并进行相应的输入操作，支持文本框、文本域、下拉选择等多种表单控件。

数据提取

#### ScrapeAction

从当前页面提取结构化数据。通过自然语言指令指定要提取的内容。

obs = session.observe()
scrape_result = session.execute(
    type="scrape",
    instructions="提取所有搜索结果的标题和链接"
)

验证码处理

#### CaptchaSolveAction

处理页面上的验证码挑战。系统支持多种验证码类型，包括 reCAPTCHA、hCaptcha、图像验证等。

关键规则：

• 绝对不要直接点击验证码相关元素
• 必须使用 captcha_solve 专用动作
• 检测到验证码时应立即使用此动作

# 解决 reCAPTCHA
session.execute(type="captcha_solve", captcha_type="recaptcha")

动作执行流程

graph TD
    A[用户/Agent 调用 execute] --> B[Session 接收动作请求]
    B --> C{验证动作类型}
    C -->|有效| D[构建动作对象]
    C -->|无效| E[抛出 ValidationError]
    D --> F[发送到 notte_browser 执行]
    F --> G{执行结果}
    G -->|成功| H[返回 ExecutionResult]
    G -->|失败| I{错误类型}
    I -->|可重试| J[执行重试逻辑]
    I -->|不可重试| K[抛出异常]
    J --> F

执行结果处理

ExecutionResult

每次动作执行都会返回 ExecutionResult 对象，包含执行状态和相关信息：

错误处理

系统在 notte_core/errors/processing.py 中定义了丰富的错误类型：

动作选择机制

在 Agent 决策过程中，动作选择器（Action Selector）负责从页面的可交互元素中生成候选动作列表。

graph LR
    A[页面 DOM/Accessibility Tree] --> B[Perception 模块]
    B --> C[生成交互元素列表]
    C --> D[动作选择器 Pipe]
    D --> E[过滤/排序候选动作]
    E --> F[返回 ActionSpace]

元素标识符规范

系统使用统一的前缀标识不同类型的可交互元素：

SDK 使用示例

基本执行流程

from notte_sdk import NotteClient

client = NotteClient()
with client.Session() as session:
    # 导航
    session.execute(type="goto", url="https://console.notte.cc")
    
    # 观察页面
    obs = session.observe()
    print(obs.space.description)
    
    # 执行交互
    session.execute(type="click", id="B1")

带指令的观察

使用 instructions 参数可以快速定位特定意图的交互元素：

actions = session.observe(instructions="Fill the email input")
print(actions[0].model_dump())

感知类型

# 快速感知
obs = session.observe(perception_type='fast')

# 深度感知
obs = session.observe(perception_type='deep')

动作定义源码结构

核心动作类继承自 BrowserAction 基类，每个动作实现以下关键方法：

class BrowserAction(BaseModel):
    type: str
    description: str
    
    def execution_message(self) -> str:
        """返回动作执行后的状态消息"""
        ...
    
    @staticmethod
    def example() -> Self:
        """返回动作的示例实例"""
        ...
    
    @property
    def param(self) -> ActionParameter | None:
        """返回动作参数定义"""
        ...

资料来源：packages/notte-core/src/notte_core/actions/actions.py:1-100

最佳实践

1. 使用上下文管理器：始终使用 with 语句管理 Session，确保资源正确释放
2. 选择合适的感知类型：简单操作使用 fast，复杂页面使用 deep
3. 验证元素存在性：页面元素 ID 可能在不同步骤间变化，不要依赖历史 ID
4. 处理验证码：发现验证码时立即使用专用处理动作
5. 检查执行结果：始终检查 ExecutionResult.success 字段

# 推荐做法
with client.Session() as session:
    result = session.execute(type="goto", url="https://example.com")
    if not result.success:
        print(f"Navigation failed: {result.error}")

相关模块

功能概述

凭证保险库的主要职责包括：

凭证保险库与 Agent 系统紧密集成，当 Agent 执行需要认证的任务时（如登录网站），系统会从保险库中获取相应凭证，而不是让 Agent 直接处理敏感数据。资料来源：packages/notte-core/src/notte_core/errors/processing.py:31-38

核心架构

组件关系图

graph TD
    A[Agent] --> B[Vault]
    B --> C[Credentials Store]
    B --> D[Placeholder Resolver]
    C --> E[BaseCredential]
    D --> F[InvalidPlaceholderError]
    G[Session] --> B
    H[Action Execution] --> B

凭证类型体系

Notte 框架定义了多种凭证类型，通过 credentials/types.py 中的类型系统进行管理：

• BaseCredential：所有凭证类型的基类
• CredentialsPlaceholder：用于在代码中引用保险库中的凭证
• AgentCredentials：专门用于 Agent 认证场景的凭证

资料来源：packages/notte-core/src/notte_core/credentials/types.py

使用方式

基本使用流程

graph LR
    A[创建 Vault] --> B[添加凭证]
    B --> C[Agent 执行任务]
    C --> D[解析占位符]
    D --> E[注入凭证]

在 Agent 中使用保险库

以下示例展示了如何在 Agent 中集成凭证保险库：

from notte_sdk import NotteClient

client = NotteClient()

# 创建保险库并添加凭证
with client.Vault() as vault:
    vault.add_credential(name="github_token", value="ghp_xxxxx")
    vault.add_credential(name="email", value="[email protected]")
    
    with client.Session() as session:
        agent = client.Agent(session=session, vault=vault, max_steps=10)
        response = agent.run(
            task="登录 GitHub 并访问我的仓库列表"
        )

资料来源：examples/auth-vault-agent/agent.py

占位符机制

在任务描述中使用占位符引用保险库中的凭证：

# 占位符格式
vault.add_credential(name="github_password", value="mypassword")

# 在任务中使用
task = "使用凭证 {github_password} 登录 GitHub"

当 Agent 执行时，系统会自动将 {placeholder_name} 格式的占位符替换为保险库中对应的实际值。

API 参考

Vault 类

占位符错误处理

当占位符未被正确处理时，系统会抛出 InvalidPlaceholderError：

资料来源：packages/notte-core/src/notte_core/errors/processing.py:31-38

最佳实践

安全建议

1. 敏感信息隔离：所有敏感凭证应存储在 Vault 中，避免硬编码
2. 环境变量分离：生产环境中使用环境变量配置凭证，而非代码仓库
3. 最小权限原则：仅为 Agent 提供完成任务所需的最少凭证

性能优化

与其他组件的集成

与 Session 集成

保险库可以与浏览器会话配合使用，实现自动登录：

with client.Vault() as vault:
    vault.add_credential(name="username", value="[email protected]")
    vault.add_credential(name="password", value="secret123")
    
    with client.Session() as session:
        agent = client.Agent(session=session, vault=vault)
        # Agent 会自动使用 vault 中的凭证进行登录

与 Agent Persona 集成

保险库可与 Agent Persona 结合使用，提供完整的数字身份认证能力：

with client.Vault() as vault:
    with client.Persona() as persona:
        with client.Session() as session:
            agent = client.Agent(
                session=session,
                persona=persona,
                vault=vault,
                max_steps=15
            )

资料来源：README.md

实现细节

凭证存储层

凭证保险库的存储实现位于 packages/notte-browser/src/notte_browser/vault.py，该模块负责：

• 本地凭证的安全存储
• 与浏览器上下文的集成
• 跨会话的凭证持久化

核心基类

packages/notte-core/src/notte_core/credentials/base.py 定义了凭证管理的抽象接口，包括：

• 凭证的创建和销毁
• 占位符的注册和解析
• 凭证的验证和刷新

资料来源：packages/notte-core/src/notte_core/credentials/base.py

总结

凭证保险库是 Notte 框架安全架构的重要组成部分，它通过以下方式保护敏感信息：

• 集中管理所有凭证
• 使用占位符避免敏感信息暴露
• 与 Agent 系统无缝集成
• 提供完善的错误处理机制

通过正确使用凭证保险库，开发者可以在保持安全性的同时，让 Agent 自动化执行需要认证的复杂任务。

概述

Notte 的文件存储系统是整个平台的核心模块之一，负责管理文件上传、下载、存储和检索功能。该系统与 Notte 的会话管理和浏览器交互功能紧密集成，为 AI Agent 提供持久化的文件存储能力。

文件存储系统的主要职责包括：

• 支持会话期间的文件上传与持久化
• 提供文件元数据管理
• 存储截图、图片等多媒体数据
• 与 Vault 凭证管理系统集成

核心架构

数据模型

文件存储系统的核心数据模型为 FileData，定义在 packages/notte-core/src/notte_core/storage.py 中：

存储层级

┌─────────────────────────────────────────────┐
│              NotteClient                    │
│  (packages/notte-sdk/src/notte_sdk)         │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│         FilesEndpoint                       │
│  (packages/notte-sdk/src/notte_sdk/         │
│   endpoints/files.py)                       │
└─────────────────┬───────────────────────────┘
                  │
┌─────────────────▼───────────────────────────┐
│         StorageService                      │
│  (packages/notte-core/src/notte_core/       │
│   storage.py)                               │
└─────────────────────────────────────────────┘

API 接口

FilesEndpoint 类

FilesEndpoint 是 SDK 层面的文件操作入口，提供以下核心方法：

端点路由

文件存储 API 的基础端点为：

POST /api/files/upload
GET  /api/files/{file_id}
GET  /api/files/{file_id}/download
DELETE /api/files/{file_id}
GET  /api/files

资料来源：packages/notte-sdk/src/notte_sdk/endpoints/files.py:1-100

存储类型

Notte 支持多种类型的文件存储：

用户上传文件

用户通过 SDK 上传的自定义文件，如文档、配置文件等。

截图数据

浏览器截图自动存储为文件，便于 Agent 回溯和调试：

class ScreenshotData(BaseModel):
    id: str
    timestamp: datetime
    data: bytes
    session_id: str

图片数据

ImageData 类封装了从网页抓取的图片资源：

class ImageData(BaseModel):
    url: str | None
    alt_text: str | None
    id: str
    
    def bytes(self) -> bytes:
        """获取图片字节数据"""

资料来源：packages/notte-core/src/notte_core/data/space.py:50-70

与会话系统集成

文件存储与 Notte 的会话管理系统深度集成。在会话运行期间：

1. 会话启动时：可以指定 cookies_file 参数自动保存会话 cookie 到指定文件
2. 会话运行中：截图和图片自动关联到当前会话
3. 会话结束时：文件保持持久化，可供后续会话访问

# 会话文件存储示例
with client.Session(cookies_file="./cookies.json") as session:
    session.execute(type="goto", url="https://example.com")
    # 截图自动保存为文件
    screenshot = session.screenshot()

资料来源：packages/notte-sdk/src/notte_sdk/endpoints/sessions.py:80-95

快速开始

安装与配置

确保已安装 notte-sdk：

pip install notte-sdk

上传文件

from notte_sdk import NotteClient

client = NotteClient()
files = client.files

# 上传本地文件
with open("document.pdf", "rb") as f:
    file_data = files.upload(
        name="document.pdf",
        content=f.read(),
        mime_type="application/pdf"
    )
    print(f"文件已上传，ID: {file_data.id}")

下载文件

# 通过文件 ID 下载
content = files.download(file_id="abc123")
with open("output.pdf", "wb") as f:
    f.write(content)

列出文件

# 列出所有已存储的文件
all_files = files.list()
for file in all_files:
    print(f"{file.id}: {file.name} ({file.size} bytes)")

资料来源：docs/src/snippets/file-storage/quickstart.mdx:1-50

错误处理

文件存储系统定义了以下专用错误类型：

StorageError

基础存储错误类，所有存储相关异常都继承于此。

FileNotFoundError

当请求的文件不存在时抛出：

class FileNotFoundError(NotteBaseError):
    def __init__(self, file_id: str) -> None:
        super().__init__(
            dev_message=f"File with id {file_id} not found in storage",
            agent_message=f"Unable to access file",
            user_message="The requested file could not be found"
        )

StorageQuotaExceededError

存储配额超限时的异常。

资料来源：packages/notte-core/src/notte_core/storage.py:30-60

最佳实践

文件管理策略

1. 定期清理：定期调用 delete 方法清理不再需要的文件
2. 批量操作：使用 list 方法获取文件列表后进行批量筛选
3. 命名规范：为文件指定清晰的 name 便于识别

性能优化

• 大文件建议分块上传
• 图片资源优先使用 url 引用而非直接存储 content
• 敏感文件使用 Vault 加密存储

相关模块

Pitfall Log / 踩坑日志

项目：nottelabs/notte

摘要：发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：v1.8.8。

1. 安装坑 · 来源证据：v1.8.8

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.8.8
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_5224b46e2312471c976888e8a2f8f4a6 | https://github.com/nottelabs/notte/releases/tag/v1.8.8 | 来源类型 github_release 暴露的待验证使用条件。

2. 配置坑 · 来源证据：v1.8.13

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.13
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_56505da48cd74758ab7a9a1d82092e18 | https://github.com/nottelabs/notte/releases/tag/v1.8.13 | 来源类型 github_release 暴露的待验证使用条件。

3. 配置坑 · 来源证据：v1.8.14

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.14
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8f78a2591cea4f5aad8bfa0cb0ea15a0 | https://github.com/nottelabs/notte/releases/tag/v1.8.14 | 来源类型 github_release 暴露的待验证使用条件。

4. 配置坑 · 来源证据：v1.8.15

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.15
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f611f1d0dd2440af8e84e9544ab1bdb6 | https://github.com/nottelabs/notte/releases/tag/v1.8.15 | 来源类型 github_release 暴露的待验证使用条件。

5. 配置坑 · 来源证据：v1.8.6

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.6
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_0ed3c86ff7a34e5896a4daeb75552d4d | https://github.com/nottelabs/notte/releases/tag/v1.8.6 | 来源类型 github_release 暴露的待验证使用条件。

6. 配置坑 · 来源证据：v1.8.9

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.9
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6195971390e8494f88083c862aef7eb6 | https://github.com/nottelabs/notte/releases/tag/v1.8.9 | 来源类型 github_release 暴露的待验证使用条件。

7. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:900152988 | https://github.com/nottelabs/notte | README/documentation is current enough for a first validation pass.

8. 运行坑 · 来源证据：v1.8.7

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v1.8.7
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ab102ac99c2441118475601c34ab0ee9 | https://github.com/nottelabs/notte/releases/tag/v1.8.7 | 来源类型 github_release 暴露的待验证使用条件。

9. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:900152988 | https://github.com/nottelabs/notte | last_activity_observed missing

10. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:900152988 | https://github.com/nottelabs/notte | no_demo; severity=medium

11. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | github_repo:900152988 | https://github.com/nottelabs/notte | No sandbox install has been executed yet; downstream must verify before user use.

12. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:900152988 | https://github.com/nottelabs/notte | no_demo; severity=medium

13. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:900152988 | https://github.com/nottelabs/notte | issue_or_pr_quality=unknown

14. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:900152988 | https://github.com/nottelabs/notte | release_recency=unknown