Notte

https://docs.notte.cc/
Admin
Notte is a platform for building and deploying reliable Web AI Agents that automate web tasks and...
Tokens:231,891
Snippets:1,559
Trust Score:7.4
Update:8 months ago
Show doc for...
Tokens:
Raw
### Agent State: Running Example - Python

Source: https://docs.notte.cc/features/agents/lifecycle

Demonstrates how to start an agent and observe its 'Running' state. This code snippet initiates an agent task and implies that the agent is actively processing. It requires the 'notte_sdk' library.

```python
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    agent.start(task="Complete task")
    # Agent state: Running
```

--------------------------------

### Python Session Lifecycle Example

Source: https://docs.notte.cc/features/sessions/lifecycle

Demonstrates the creation, starting, active operations, and stopping of a session using Python. This example assumes the 'client' object is already initialized and configured.

```python
session = client.Session(timeout_minutes=10)
# Status: Not started (response = None)

with session:
    # Status: active
    # Creates remote browser
    # Opens viewer if headless=False
    # Loads cookies from cookie_file

    # Active operations
    session.execute(action)
    session.observe()
    session.scrape()
    session.page.goto(url)

# Or explicitly stop:
session.stop()
# Status: closed

# Cleanup happens automatically or after stop()
# Saves cookies to cookie_file
# Closes Playwright connections
# Releases cloud resources
```

--------------------------------

### File Storage Best Practices

Source: https://docs.notte.cc/concepts/file-storage

Examples demonstrating best practices for using the File Storage API, such as attaching storage before starting a session, using descriptive filenames, and checking downloads after a session.

```APIDOC
## File Storage Best Practices

### 1. Attach Storage Before Starting

Always create and attach storage before starting the session to ensure it's available.

```python
from notte_sdk import NotteClient

client = NotteClient()

# Correct usage
storage = client.FileStorage()
storage.upload("file.pdf")

with client.Session(storage=storage) as session:
    # Storage is available within the session
    pass
```

### 2. Use Descriptive Filenames

Employ descriptive filenames, potentially including timestamps, for better organization and identification.

```python
from datetime import datetime
from notte_sdk import NotteClient

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

timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
storage.upload("report.pdf", upload_file_name=f"report_{timestamp}.pdf")
```

### 3. Check Downloads After Session

Verify downloaded files after the session concludes to process or review them.

```python
from notte_sdk import NotteClient

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

with client.Session(storage=storage) as session:
    agent = client.Agent(session=session)
    agent.run(task="Download all invoices")

# Check what was downloaded
files = storage.list_downloaded_files()
if not files:
    print("No files were downloaded")
else:
    for f in files:
        storage.download(file_name=f, local_dir="./invoices")
```
```

--------------------------------

### Start Agent

Source: https://docs.notte.cc/sdk-reference/remoteagent/start

Initiates the agent execution with the provided configuration. The agent will begin processing the task immediately after starting.

```APIDOC
## POST /start

### Description
Starts the agent with the specified request parameters.

### Method
POST

### Endpoint
/start

### Parameters
#### Request Body
- **task** (str) - Required - The task description to execute.
- **url** (str | None) - Optional - Optional URL to process, defaults to None.
- **response_format** (type[pydantic.main.BaseModel] | None) - Optional - The response format to use for the agent answer. You can use a Pydantic model or a JSON Schema dict.
- **session_offset** (int | None) - Optional - [Experimental] The step from which the agent should gather information from in the session. If none, fresh memory.

### Request Example
```json
{
  "task": "Summarize the content of the given URL.",
  "url": "https://example.com",
  "response_format": null,
  "session_offset": null
}
```

### Response
#### Success Response (200)
- **AgentResponse** - The initial response from starting the agent.

#### Response Example
```json
{
  "output": "Agent started successfully.",
  "logs": [
    "Processing task..."
  ]
}
```
```

--------------------------------

### Install and Run Notte-MCP Server Locally (Bash)

Source: https://docs.notte.cc/integrations/mcp

This snippet shows how to install the notte-mcp package and start the MCP server locally. It requires setting the NOTTE_API_KEY environment variable before installation and server startup. The server listens on a default port, enabling local development and testing.

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

--------------------------------

### Install Notte and Kernel SDKs

Source: https://docs.notte.cc/integrations/kernel

Installs the necessary Python SDKs for Notte and Kernel using pip. Ensure you have Python and pip installed.

```bash
uv pip install notte-sdk
uv pip install kernel
```

--------------------------------

### Quick Start File Storage Upload and Download with Python

Source: https://docs.notte.cc/concepts/file-storage

Demonstrates a quick start for file storage operations. It uploads a file, creates a session with storage attached, runs an agent task, and then downloads files retrieved by the agent. Requires the 'notte_sdk' library.

```python
from notte_sdk import NotteClient

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

# Upload a file before the session
storage.upload("document.pdf")

# Create session with storage attached
with client.Session(storage=storage) as session:
    agent = client.Agent(session=session)

    result = agent.run(
        task="Upload document.pdf to the portal and download the receipt", url="https://example.com/upload"
    )

# Download files the agent retrieved
for file_name in storage.list_downloaded_files():
    storage.download(file_name=file_name, local_dir="./downloads")
```

--------------------------------

### Install notte-sdk using pip

Source: https://docs.notte.cc/sdk-reference/manual

Installs the notte SDK package using pip, the Python package installer. This is the first step to using the NotteClient and other functionalities.

```bash
pip install notte-sdk
```

--------------------------------

### Quick Start: Record Browser Session and Save Replay (Python)

Source: https://docs.notte.cc/features/sessions/recordings

This snippet demonstrates the basic usage of the Notte SDK to start a session, execute a series of browser actions (goto, click, fill), and then save the resulting session recording as an MP4 file. It requires the 'notte_sdk' library.

```python
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    session.execute(type="goto", url="https://example.com")
    session.execute(type="click", selector="button.submit")
    session.execute(type="fill", selector="input[name='email']", value="user@example.com")
    # All actions automatically recorded

# Get replay after session ends
replay = session.replay()
replay.save("session_recording.mp4")
```

--------------------------------

### Quick Start Browser Agent - Python

Source: https://docs.notte.cc/concepts/agents

Demonstrates how to quickly create and run a Browser Agent using the Notte SDK. It initializes a client, starts a session, configures an agent with a reasoning model and max steps, and executes a task to find a contact email on a website. Sessions are managed using a context manager for automatic cleanup.

```python
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    agent = client.Agent(session=session, reasoning_model="gemini/gemini-2.0-flash", max_steps=10)

    result = agent.run(task="Go to example.com and find the contact email")

    print(result.answer)
```

--------------------------------

### Install Notte SDK (Python/JavaScript)

Source: https://docs.notte.cc/quickstart

Installs the Notte SDK for Python and JavaScript. Python requires version 3.11 or higher.

```bash
pip install notte-sdk
```

```bash
npm install notte-sdk
```

--------------------------------

### POST /websites/notte_cc/sessions

Source: https://docs.notte.cc/api-reference/sessions/session-start

Starts a new browser session with specified configurations. You can customize arguments, viewport, and other session properties.

```APIDOC
## POST /websites/notte_cc/sessions

### Description
Starts a new browser session with specified configurations. You can customize arguments, viewport, and other session properties.

### Method
POST

### Endpoint
/websites/notte_cc/sessions

### Parameters
#### Request Body
- **chrome_args** (array of strings | null) - Optional - Overwrite the chrome instance arguments.
- **viewport_width** (integer | null) - Optional - The width of the viewport.
- **viewport_height** (integer | null) - Optional - The height of the viewport.
- **cdp_url** (string | null) - Optional - The CDP URL of another remote session provider.
- **use_file_storage** (boolean) - Optional - Whether FileStorage should be attached to the session. Defaults to false.
- **screenshot_type** (string) - Optional - The type of screenshot to use for the session. Allowed values: "raw", "full", "last_action". Defaults to "last_action".
- **profile** (object | null) - Optional - Browser profile configuration for state persistence.

### Request Example
```json
{
  "chrome_args": ["--disable-gpu", "--no-sandbox"],
  "viewport_width": 1920,
  "viewport_height": 1080,
  "use_file_storage": true,
  "screenshot_type": "full"
}
```

### Response
#### Success Response (200)
- **session_id** (string) - The ID of the session.
- **idle_timeout_minutes** (integer) - Session idle timeout in minutes.
- **max_duration_minutes** (integer) - Session max duration in minutes. Defaults to 15.
- **created_at** (string) - Session creation time.
- **closed_at** (string | null) - Session closing time.
- **last_accessed_at** (string) - Last access time.
- **duration** (string) - Session duration.
- **status** (string) - Session status. Allowed values: "active", "closed", "error", "timed_out".
- **steps** (array of objects) - Steps of the session.
- **error** (string | null) - Error message if the operation failed.
- **credit_usage** (number | null) - Credit usage for the session.
- **proxies** (boolean) - Whether proxies were used for the session. Defaults to false.
- **browser_type** (string) - The browser type. Defaults to "chromium". Allowed values: "chromium", "chrome", "firefox", "chrome-nightly", "chrome-turbo".
- **use_file_storage** (boolean) - Whether FileStorage was attached to the session. Defaults to false.
- **network_request_bytes** (integer) - Total byte usage for network requests. Defaults to 0.
- **network_response_bytes** (integer) - Total byte usage for network responses. Defaults to 0.
- **user_agent** (string | null) - The user agent to use for the session.
- **viewport_width** (integer | null) - The width of the viewport.

#### Response Example
```json
{
  "session_id": "sess_abcdef123456",
  "idle_timeout_minutes": 5,
  "max_duration_minutes": 30,
  "created_at": "2023-10-27T10:00:00Z",
  "closed_at": null,
  "last_accessed_at": "2023-10-27T10:05:00Z",
  "duration": "0:05:00",
  "status": "active",
  "steps": [],
  "error": null,
  "credit_usage": 0.1,
  "proxies": false,
  "browser_type": "chromium",
  "use_file_storage": true,
  "network_request_bytes": 1024,
  "network_response_bytes": 2048,
  "user_agent": "Mozilla/5.0...",
  "viewport_width": 1920
}
```
```

--------------------------------

### Start Live View Automatically (Python)

Source: https://docs.notte.cc/features/sessions/live-view

This snippet demonstrates how to automatically open the Live View viewer when a browser session starts. It requires the 'notte_sdk' library and initializes a NotteClient. The 'open_viewer=True' argument in the Session context manager ensures the viewer is launched.

```python
from notte_sdk import NotteClient

client = NotteClient()

# Live viewer opens automatically
with client.Session(open_viewer=True) as session:
    session.execute(type="goto", url="https://example.com")
    session.execute(type="click", selector="button.submit")
    # Watch it happen in your browser!
```

--------------------------------

### Simple Agent Example

Source: https://docs.notte.cc/features/agents/configuration

Minimal configuration for basic agent tasks.

```APIDOC
## Simple Agent

Minimal configuration for basic tasks:

```python
with client.Session() as session:
    agent = client.Agent(session=session)
    result = agent.run(task="Find contact email")
```
```

--------------------------------

### Start with 2-3 Parallel Agents for Balance

Source: https://docs.notte.cc/features/agents/batch

Recommends starting with 2-3 parallel agents in BatchRemoteAgent to effectively balance cost and reliability. This approach significantly increases the success rate for tasks with a moderate chance of success.

```python
import asyncio

from notte_sdk.agents import BatchRemoteAgent


async def main():
    batch_agent = BatchRemoteAgent(session=session, _client=client)

    # Good starting point
    result = await batch_agent.run(
        task="Task with ~70% success rate",
        n_jobs=3,  # 97% combined success
        strategy="first_success",
    )


asyncio.run(main())
```

--------------------------------

### Complete CAPTCHA Solving Example with Login (Python)

Source: https://docs.notte.cc/features/sessions/captcha-solving

This example shows a full workflow of using Notte's CAPTCHA solving feature during a login process. It includes setting up the session with `browser_type='firefox'` and `solve_captchas=True`, navigating to a login page, filling credentials, submitting the form (where the captcha is solved automatically), and waiting for successful redirection.

```python
from notte_sdk import NotteClient

client = NotteClient()

with client.Session(
    browser_type="firefox",
    solve_captchas=True,
    headless=False  # Watch it solve captchas
) as session:
    page = session.page

    # Navigate to a site with captcha
    page.goto("https://example.com/login")

    # Fill login form
    page.fill('input[name="email"]', "user@example.com")
    page.fill('input[name="password"]', "password")

    # Click submit - captcha will be solved automatically
    page.click('button[type="submit"]')

    # Wait for successful login
    page.wait_for_url("**/dashboard")
    print("Logged in successfully!")
```

--------------------------------

### Get Session Offset

Source: https://docs.notte.cc/sdk-reference/remotesession/offset

Fetches the trajectory offset of the session. This is useful to start an agent that remembers information about steps that happened before it started.

```APIDOC
## GET /session/offset

### Description
Get the trajectory offset of the session. This is useful to start an agent that remembers information about steps that happened before it started.

### Method
GET

### Endpoint
/session/offset

### Parameters
#### Query Parameters
- **session_id** (string) - Required - The ID of the session.

### Request Example
```
GET /session/offset?session_id=your_session_id
```

### Response
#### Success Response (200)
- **offset** (integer) - The session trajectory offset.

#### Response Example
```json
{
  "offset": 12345
}
```

#### Error Response (400)
- **error** (string) - Description of the error. For example, "Session not found."

#### Error Example
```json
{
  "error": "Session not found."
}
```
```

--------------------------------

### Get Session Status (Python)

Source: https://docs.notte.cc/sdk-reference/remotesession/status

Retrieves the current status of the session. This is useful for checking if a session is active, when it started, or when it stopped. It returns a SessionResponse object containing status information. Raises ValueError if the session has not been started.

```python
status = session.status()
```

--------------------------------

### Start Session with Built-in Proxies (Python)

Source: https://docs.notte.cc/features/sessions/proxies

Demonstrates how to start a session using Notte's built-in residential proxies. This is the simplest proxy option, requiring minimal setup. The `proxies=True` parameter attempts to use a US-based proxy, falling back to nearby countries if necessary.

```python
from notte_sdk import NotteClient

client = NotteClient()

# Start a session with built-in proxies
with client.Session(proxies=True) as session:
    _ = session.observe(url="https://www.notte.cc/")
```

--------------------------------

### Initialize and Run a Simple Agent

Source: https://docs.notte.cc/features/agents/configuration

Demonstrates the minimal configuration required to create and run an agent for basic tasks. It involves creating a session and then an agent instance within that session.

```python
with client.Session() as session:
    agent = client.Agent(session=session)
    result = agent.run(task="Find contact email")
```

--------------------------------

### Create Session with Storage and Run Agent

Source: https://docs.notte.cc/community/github

This snippet demonstrates how to create a session with attached storage, initialize an agent, and run a task. It then lists downloaded files from storage and downloads them to a local directory.

```python
from notte_sdk import NotteClient

client = NotteClient()
storage = client.Storage()

# Create session with storage attached
with client.Session(storage=storage) as session:
    agent = client.Agent(session=session, max_steps=5)
    response = agent.run(
        task="Upload the PDF document to the website and download the cat picture",
        url="https://example.com/upload"
    )

# Download files that the agent downloaded
downloaded_files = storage.list(type="downloads")
for file_name in downloaded_files:
    storage.download(file_name=file_name, local_dir="./results")
```

--------------------------------

### Content Monitoring Use Case

Source: https://docs.notte.cc/concepts/scraping

Track changes in content on a webpage. This example shows how to get the current content using specific instructions, and a comment indicates where to add logic for comparing with a previous version.

```python
from notte_sdk import NotteClient

client = NotteClient()

# Get current content
content = client.scrape("https://example.com/pricing", instructions="Extract all pricing tiers and their features")

# Compare with previous version
# ...
```

--------------------------------

### Create and Run a Simple Agent

Source: https://docs.notte.cc/sdk-reference/manual/agent

Demonstrates how to create a basic Notte agent and run a task. It initializes the Notte client and uses a session to execute a task, such as searching for images online. No external dependencies beyond the Notte SDK are required.

```python
from notte_sdk import NotteClient

client = NotteClient()
with client.Session() as session:
    agent = client.Agent(session=session)
    agent.run(task="go to google, and find cat pictures")
```

--------------------------------

### Get Session Offset (Python)

Source: https://docs.notte.cc/sdk-reference/remotesession/offset

Retrieves the trajectory offset for the current session. This offset is crucial for agents that need to maintain context from previous steps. It returns an integer representing the offset and raises a ValueError if the session has not been started.

```python
offset = session.offset()
```

--------------------------------

### Initialize and Run a Production Agent

Source: https://docs.notte.cc/features/agents/configuration

Provides a comprehensive example of configuring an agent for production use, including specifying reasoning models, vision capabilities, maximum steps, and integrating with vaults and personas. It also shows how to handle the agent's run result.

```python
from notte_sdk import NotteClient

client = NotteClient()

vault = client.Vault(vault_id="prod_vault")
persona = client.Persona(persona_id="prod_persona")

with client.Session(headless=True, proxies=True) as session:
    agent = client.Agent(
        session=session,
        reasoning_model="anthropic/claude-3.5-sonnet",
        use_vision=True,
        max_steps=30,
        vault=vault,
        persona=persona,
    )

    result = agent.run(task="Complete checkout process", url="https://store.example.com/cart")

    if result.success:
        print(f"Order completed: {result.answer}")
    else:
        print(f"Failed: {result.answer}")
```

--------------------------------

### Initialize and Run Agent for Structured Data Extraction

Source: https://docs.notte.cc/features/agents/configuration

Shows how to configure an agent specifically for extracting structured data using a Pydantic model. This example defines a `CompanyInfo` model and uses it to guide the agent's extraction process, then validates and prints the extracted information.

```python
from notte_sdk import NotteClient
from pydantic import BaseModel


class CompanyInfo(BaseModel):
    name: str
    email: str
    phone: str | None
    address: str | None


client = NotteClient()

with client.Session() as session:
    agent = client.Agent(session=session, reasoning_model="gemini/gemini-2.0-flash", max_steps=10)

    result = agent.run(
        task="Extract company contact information", url="https://example.com/contact", response_format=CompanyInfo
    )

    if result.success:
        company = CompanyInfo.model_validate_json(result.answer)
        print(f"Company: {company.name}")
        print(f"Email: {company.email}")
        print(f"Phone: {company.phone}")
```

--------------------------------

### FileStorage: Upload, Session, and Download Example (Python)

Source: https://docs.notte.cc/sdk-reference/manual/file_storage

Demonstrates how to use the FileStorage module to upload a file before a session, attach the storage to a session for an agent to process, and download files after the session. It requires the 'notte_sdk' library.

```python
from notte_sdk import NotteClient

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

# Upload files before the session
storage.upload("document.pdf")

# Attach storage to session
with client.Session(storage=storage) as session:
    agent = client.Agent(session=session)
    agent.run(task="Upload document.pdf and download the receipt")

# Download files after the session
for file_name in storage.list_downloaded_files():
    storage.download(file_name=file_name, local_dir="./downloads")
```

--------------------------------

### Complete Form Automation Example (Python)

Source: https://docs.notte.cc/features/sessions/selenium

This Python script demonstrates end-to-end form automation using Playwright and the Notte SDK. It navigates to a web page, fills in form fields, selects a dropdown option, checks a checkbox, submits the form, waits for a success message, prints the message, and takes a screenshot. Ensure you have the 'notte_sdk' installed.

```python
from notte_sdk import NotteClient

client = NotteClient()

def automate_form():
    with client.Session(headless=False) as session:
        page = session.page

        # Navigate to form
        page.goto("https://example.com/contact")

        # Fill form fields
        page.fill('input[name="name"]', "John Doe")
        page.fill('input[name="email"]', "john@example.com")
        page.fill('textarea[name="message"]', "Hello, this is a test message")

        # Select from dropdown
        page.select_option('select[name="topic"]', "support")

        # Check checkbox
        page.check('input[name="subscribe"]')

        # Submit form
        page.click('button[type="submit"]')

        # Wait for success message
        page.wait_for_selector("div.success")

        success_message = page.locator("div.success").inner_text()
        print(f"Success: {success_message}")

        # Take screenshot
        page.screenshot(path="success.png")

automate_form()

```

--------------------------------

### Persist Browser State to a Profile in Notte

Source: https://docs.notte.cc/features/sessions/browser-profiles

This Python example shows how to log in to a website and save the session's browser state (cookies, etc.) to a profile. By setting `persist=True` when creating the session, any changes, including authentication, are stored in the specified profile upon session completion. This is useful for subsequent sessions that need to start from an authenticated state.

```python
from notte_sdk import NotteClient

client = NotteClient()

# Create a new profile
profile = client.profiles.create(name="github-login")

# Use profile with persist=True to save browser state
with client.Session(
    profile={"id": profile.profile_id, "persist": True}
) as session:
    # Navigate and perform login
    session.execute(type="goto", url="https://github.com/login")
    session.execute(type="fill", selector='input[name="login"]', value="username")
    session.execute(type="fill", selector='input[name="password"]', value="password")
    session.execute(type="click", selector='input[type="submit"]')
    # Browser state is saved to profile when session ends
```

--------------------------------

### Initiate Agent Task from Specific URL with Python

Source: https://docs.notte.cc/concepts/agents

Demonstrates how to start an agent's task by providing a specific URL. This is useful for directing the agent to begin its process on a particular webpage.

```python
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    agent.run(task="Find pricing information", url="https://example.com/products")
```

--------------------------------

### Natural Language Task for Browser Agent - Python

Source: https://docs.notte.cc/concepts/agents

Illustrates how to use a Browser Agent to perform a task specified in natural language. This example shows initializing a client and session, then running an agent with a task to find the cheapest laptop under $1000 and add it to the cart. The agent autonomously handles the multi-step process.

```python
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    agent = client.Agent(session=session)
    agent.run(task="Find the cheapest laptop under $1000 and add it to cart")
```

--------------------------------

### Install Playwright and Notte SDK

Source: https://docs.notte.cc/features/sessions/playwright

Install the necessary libraries for Playwright integration with Notte. This command installs both the Notte SDK and Playwright, making them available for use in your Python project.

```bash
pip install notte-sdk playwright
```

--------------------------------

### Attach Storage Before Starting Session

Source: https://docs.notte.cc/concepts/file-storage

Illustrates the best practice of creating and attaching a FileStorage instance to the client before initiating a session. This ensures storage is available for operations within the session.

```python
from notte_sdk import NotteClient

client = NotteClient()

# Correct
storage = client.FileStorage()
storage.upload("file.pdf")

with client.Session(storage=storage) as session:
    # Storage is available
    pass
```

--------------------------------

### Python Function Handler Examples

Source: https://docs.notte.cc/features/functions/creating

Provides examples of correct and incorrect function handlers in Python for Notte Functions. The correct handler must be named `run()`. Incorrect examples show a different function name and a case where no function is defined, which will not be executed.

```python
# Correct
def run(param1, param2):
    return "result"


# Wrong - different name
def execute(param1, param2):
    return "result"


# Wrong - no function
result = perform_task()
```

--------------------------------

### POST /sessions/start

Source: https://docs.notte.cc/api-reference/sessions/session-start

Starts a new cloud browser session. This endpoint allows for customization of session parameters such as browser type, timeouts, and proxy configurations.

```APIDOC
## POST /sessions/start

### Description
Starts a new cloud browser session. This endpoint allows for customization of session parameters such as browser type, timeouts, and proxy configurations.

### Method
POST

### Endpoint
/sessions/start

### Parameters
#### Header Parameters
- **x-notte-request-origin** (string) - Optional - Origin of the request.
- **x-notte-sdk-version** (string) - Optional - Version of the SDK used.

#### Request Body
- **headless** (boolean) - Optional - Whether to run the session in headless mode. Defaults to true.
- **solve_captchas** (boolean) - Optional - Whether to attempt to automatically solve captchas. Defaults to false.
- **max_duration_minutes** (integer) - Optional - Maximum session lifetime in minutes. Defaults to 15.
- **idle_timeout_minutes** (integer) - Optional - Idle timeout in minutes. Session closes after this period of inactivity. Defaults to 3.
- **proxies** (array or boolean) - Optional - List of custom proxies to use for the session. If true, default proxies will be used. Defaults to false.
- **browser_type** (string) - Optional - The browser type to use. Can be 'chromium', 'chrome', 'firefox', 'chrome-nightly', 'chrome-turbo'. Defaults to 'chromium'.
- **user_agent** (string) - Optional - The user agent string to use for the session.
- **chrome_args** (array) - Optional - Additional arguments for Chrome browser.

### Request Example
```json
{
  "headless": true,
  "solve_captchas": false,
  "max_duration_minutes": 15,
  "idle_timeout_minutes": 3,
  "proxies": false,
  "browser_type": "chromium",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
  "chrome_args": [
    "--disable-gpu",
    "--no-sandbox"
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the session.
- **status** (string) - The current status of the session.
- **ws_url** (string) - The WebSocket URL for real-time communication with the session.

#### Response Example
```json
{
  "id": "sess_abcdef123456",
  "status": "running",
  "ws_url": "wss://us-staging.notte.cc/ws/sess_abcdef123456"
}
```

#### Error Response (422)
- **detail** (array) - A list of validation errors.

#### Error Response Example
```json
{
  "detail": [
    {
      "loc": [
        "body",
        "max_duration_minutes"
      ],
      "msg": "ensure this value is less than or equal to 15",
      "type": "value_error.number.max"
    }
  ]
}
```
```

--------------------------------

### Create Account with Persona using Python

Source: https://docs.notte.cc/guides/account_creation

This Python script demonstrates how to use the Notte SDK to create an account on a given URL using a persona. It handles credential creation and uses an agent to perform the account creation and API key retrieval. Ensure you have a persona ID or create a new one.

```python
from notte_sdk import NotteClient

client = NotteClient()
# retrieve the persona from the Notte console
# if you don't have a persona id, you can create a new persona using:
# persona = client.Persona(create_vault=True)
# print(f"Persona id: {persona.info.persona_id}")
persona = client.Persona("<your-persona-id>")

url = "https://console.notte.cc"
# create credentials for the persona (automatically generates a password and stores it in the vault)
persona.add_credentials(url=url)

with notte.Session(open_viewer=True) as session:
    agent = notte.Agent(session=session, persona=persona)
    response = agent.run(
        task=f"Go to {url} and create an account. Go create an API key and return the API key.", url=url
    )
    print(response.answer)
```

--------------------------------

### Install Notte and Chromium

Source: https://docs.notte.cc/community/github

Installs the Notte Python package and the Chromium browser with its dependencies. This is a prerequisite for running Notte in local mode.

```bash
pip install notte
patchright install --with-deps chromium

```

--------------------------------

### Asynchronously Create and Start a Function Run

Source: https://docs.notte.cc/features/functions/invocations

Separates the creation and starting of a function run for managing long-running processes. `create_run` initiates the run and returns a run ID immediately, while `run` (or a subsequent call) starts the actual execution. This is useful for non-blocking operations.

```python
from notte_sdk import NotteClient

client = NotteClient()
# Create a run (returns immediately)
run_response = client.functions.create_run(function_id="function_abc123", local=False)

run_id = run_response.function_run_id
print(f"Run created: {run_id}")

# Start the run
client.functions.run(function_run_id=run_id, function_id="function_abc123", variables={"url": "https://example.com"})
```

--------------------------------

### API Authentication Error (401) Example (JSON)

Source: https://docs.notte.cc/api-reference/errors

An example of a JSON response when authentication fails due to invalid or missing API credentials.

```json
{
  "message": "Authentication failed. Please check your credentials."
}
```

--------------------------------

### Run Notte Agent in Local Mode (Python)

Source: https://docs.notte.cc/community/github

Demonstrates how to spin up a Notte agent using open-source features in local mode. This requires setting up environment variables for LLM API keys. The example shows initializing a session, creating an agent with a specified reasoning model and maximum steps, and running a task.

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

```

--------------------------------

### Create Agent with Configuration Parameters (Python)

Source: https://docs.notte.cc/features/agents/configuration

Demonstrates how to create a Notte agent instance with various configuration parameters. This includes setting the reasoning model, enabling vision, defining maximum steps, and optionally providing a vault and persona. It requires the NotteClient and a session.

```python
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    agent = client.Agent(
        session=session,
        reasoning_model="gemini/gemini-2.0-flash",
        use_vision=True,
        max_steps=15,
        vault=vault,  # Optional
        persona=persona,  # Optional
    )
```

--------------------------------

### Install Puppeteer Core

Source: https://docs.notte.cc/features/sessions/puppeteer

Installs the `puppeteer-core` package, which is necessary for connecting to a remote browser instance like a Notte session, rather than launching a local one.

```bash
npm install puppeteer-core
```

--------------------------------

### API Execution Error Example (JSON)

Source: https://docs.notte.cc/api-reference/errors

An example of a JSON response when an API operation fails during execution. This error is typically accompanied by the 'x-error-class: NotteApiExecutionError' header.

```json
{
  "message": "Error executing the requested operation"
}
```

--------------------------------

### Initialize Session for Observation

Source: https://docs.notte.cc/concepts

Sets up a session which is a prerequisite for performing AI-powered analysis of web pages. This session will be used to extract meaningful information about the page's content and structure.

```python
session = client.Session()
```

--------------------------------

### Install Notte SDK and Selenium

Source: https://docs.notte.cc/features/sessions/selenium

Install the necessary Python packages for using Notte SDK and Selenium 4+. Selenium version 4.0.0 or higher is required for CDP support.

```bash
pip install notte-sdk selenium>=4.0.0
```

--------------------------------

### Upload and Download Files with File Storage

Source: https://docs.notte.cc/concepts/file-storage

Demonstrates uploading a local file to storage and then downloading files listed as downloaded by agents. It shows how to initiate a session, execute actions within it, and manage files post-session.

```python
storage.upload("data.csv")

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

    # Upload using the upload_file action
    session.execute(type="upload_file", selector='input[type="file"]', filename="data.csv")

    session.execute(type="click", selector="button.submit")

# Download any files
for file_name in storage.list_downloaded_files():
    storage.download(file_name=file_name, local_dir="./results")
```

--------------------------------

### Basic Structured Output Example

Source: https://docs.notte.cc/features/agents/structured-output

Illustrates a basic example of using Pydantic models for structured output. A `Product` model is defined and passed to the agent's `response_format` parameter.

```python
from notte_sdk import NotteClient
from pydantic import BaseModel

client = NotteClient()


class Product(BaseModel):
    name: str
    price: float
    in_stock: bool


with client.Session() as session:
    agent = client.Agent(session=session)

    result = agent.run(
        task="Extract product information",
        url="https://example.com/product/123",
        response_format=Product,
    )

    # Type-safe access
    product = result.answer
    print(f"{product.name}: ${product.price}")
    if product.in_stock:
        print("Available!")
```

--------------------------------

### Setting Agent Step Limits

Source: https://docs.notte.cc/features/agents/lifecycle

Demonstrates how to set `max_steps` when initializing an agent. This parameter should be adjusted to match the expected complexity and number of steps required for a given task, helping to prevent runaway processes.

```python
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    # Match max_steps to expected complexity
    agent = client.Agent(
        session=session,
        max_steps=10,  # For tasks requiring 5-8 steps
    )
```

--------------------------------

### Select Reasoning Model Based on Task Needs

Source: https://docs.notte.cc/features/agents/configuration

Demonstrates how to choose the `reasoning_model` for an agent based on the task's requirements and cost considerations. Cheaper, faster models are recommended for simpler tasks, while more powerful models are reserved for complex reasoning.

```python
# Simple navigation and extraction
reasoning_model = "gemini/gemini-2.0-flash"

# Complex reasoning and decision-making
reasoning_model = "anthropic/claude-3.5-sonnet"
```

--------------------------------

### Alternative: Get Agent Replay from Session (Python)

Source: https://docs.notte.cc/features/sessions/recordings

This Python snippet provides an alternative method to get an agent's replay by accessing it from the session object after the agent has completed its run. It requires the 'notte_sdk' library.

```python
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    # Alternative: get from session
    replay = session.replay()
    replay.save("agent_run.mp4")
```

--------------------------------

### Start Session with Notte SDK

Source: https://docs.notte.cc/sdk-reference/remotesession/start

Initiates a session using the Notte SDK. It sends a start request to the API and logs the session ID and request details. It is recommended to use a 'with' statement for proper session cleanup.

```python
from notte_sdk import NotteClient

client = NotteClient()
session = client.Session()
session.start()
```

```python
from notte_sdk import NotteClient

client = NotteClient()
with client.Session() as session:
    session.execute(type="goto", url="https://www.notte.cc")
```

--------------------------------

### Start Notte Session with Python and Connect Puppeteer

Source: https://docs.notte.cc/features/sessions/puppeteer

This approach involves starting a Notte session using the Python SDK and then connecting a Node.js script with Puppeteer to the exposed Chrome DevTools Protocol (CDP) URL.

```APIDOC
## Start Notte Session with Python and Connect Puppeteer

### Description
Start a Notte session in Python, obtain its CDP URL, and pass it to a Node.js script that uses Puppeteer to connect and interact with the browser.

### Method
Python script initiates session, Node.js script connects Puppeteer.

### Endpoint
N/A (Python SDK and Node.js script interaction)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from notte_sdk import NotteClient
import subprocess
import json

client = NotteClient()

with client.Session(timeout_minutes=10) as session:
    cdp_url = session.cdp_url()

    # Pass CDP URL to Node.js script
    result = subprocess.run(
        ["node", "puppeteer_script.js", cdp_url],
        capture_output=True,
        text=True
    )

    print(result.stdout)
```

```javascript
// puppeteer_script.js
const puppeteer = require('puppeteer-core');

async function main() {
  // Get CDP URL from command line argument
  const cdpUrl = process.argv[2];

  // Connect to Notte session
  const browser = await puppeteer.connect({
    browserWSEndpoint: cdpUrl
  });

  // Get the page (Notte sessions have one default page)
  const pages = await browser.pages();
  const page = pages[0];

  // Use Puppeteer API
  await page.goto('https://example.com');
  console.log('Title:', await page.title());

  await page.screenshot({ path: 'screenshot.png' });

  await browser.disconnect();
}

main().catch(console.error);
```

### Response
#### Success Response (200)
Output from the Node.js script, including page title and confirmation messages.

#### Response Example
```
Title: Example Domain
```
```

--------------------------------

### Start Session with Chrome Browser

Source: https://docs.notte.cc/features/sessions/browser-types

Starts a web automation session using the Chrome browser engine. This is useful for sites that specifically detect or require Google Chrome, offering maximum compatibility. The 'notte_sdk' library is a prerequisite.

```python
from notte_sdk import NotteClient

client = NotteClient()

with client.Session(browser_type="chrome") as session:
    page = session.page
    page.goto("https://example.com")
```

--------------------------------

### File Upload and Download with Python

Source: https://docs.notte.cc/features/sessions/browser-controls

Shows how to handle file uploads and downloads within a browser session using the Notte.cc SDK. The script navigates to an upload page, uploads a specified file, and then downloads a file identified by a selector. It also demonstrates how to list downloaded files. Requires `notte_sdk`.

```python
from notte_sdk import NotteClient

client = NotteClient()

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

    # Upload file
    session.execute(type="upload_file", selector="input[type='file']", file_path="/path/to/document.pdf")
    session.execute(type="click", selector="button.submit")

    # Wait for processing
    session.execute(type="wait", duration=3000)

    # Download result
    session.execute(type="download_file", selector="a.download")

    # Access downloaded files
    downloaded_files = session.storage.list_downloaded_files()
    for file in downloaded_files:
        print(f"Downloaded: {file.file_id}")
```

--------------------------------

### Return List Example (Python)

Source: https://docs.notte.cc/concepts/functions

A simple Python function that returns a list of strings. This demonstrates basic function output.

```python
def run():
    return ["item1", "item2", "item3"]
```

--------------------------------

### API Validation Error (422) Example (JSON)

Source: https://docs.notte.cc/api-reference/errors

An example of a JSON response indicating a validation error, often due to malformed requests or invalid parameters. The 'detail' field provides specific information about the validation failures.

```json
{
  "message": "Validation error",
  "detail": [
    {
      "loc": ["body", "url"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

--------------------------------

### Run Agent with Task Description (Python)

Source: https://docs.notte.cc/features/agents/configuration

Provides an example of running an agent with a specific task. The `task` parameter is a natural language string describing the desired outcome, such as finding a product and adding it to a cart.

```python
result = agent.run(task="Find the cheapest laptop under $1000 and add it to cart")
```

--------------------------------

### Start Notte Session via REST API and Connect Puppeteer

Source: https://docs.notte.cc/features/sessions/puppeteer

This method involves directly calling the Notte REST API from a Node.js application to start a session, then using Puppeteer to connect to the session's CDP endpoint.

```APIDOC
## Start Notte Session via REST API and Connect Puppeteer

### Description
Initiate a Notte session by making a POST request to the Notte API. The response contains the CDP URL, which Puppeteer then uses to connect.

### Method
POST (for starting session), POST (for stopping session)

### Endpoint
- `POST /sessions/start`
- `POST /sessions/{sessionId}/stop`

### Parameters
#### Path Parameters
- `sessionId` (string) - Required - The ID of the session to stop.

#### Query Parameters
None

#### Request Body
- `headless` (boolean) - Optional - Whether the browser should run in headless mode. Defaults to `true`.
- `timeout_minutes` (integer) - Optional - The duration for which the session should be active. Defaults to 10 minutes.
- `browser_type` (string) - Optional - The type of browser to launch. Defaults to `chromium`.

### Request Example
```javascript
const puppeteer = require('puppeteer-core');
const fetch = require('node-fetch');

async function createNotteSession() {
  const response = await fetch('https://api.notte.cc/sessions/start', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.NOTTE_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      headless: true,
      timeout_minutes: 10,
      browser_type: 'chromium'
    })
  });

  return await response.json();
}

async function main() {
  // Start Notte session
  const sessionData = await createNotteSession();
  const cdpUrl = sessionData.cdp_url;
  const sessionId = sessionData.session_id;

  console.log(`Session started: ${sessionId}`);

  try {
    // Connect Puppeteer
    const browser = await puppeteer.connect({
      browserWSEndpoint: cdpUrl
    });

    const pages = await browser.pages();
    const page = pages[0];

    // Use Puppeteer
    await page.goto('https://example.com');
    console.log('Title:', await page.title());

    await browser.disconnect();
  } finally {
    // Stop session
    await fetch(`https://api.notte.cc/sessions/${sessionId}/stop`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.NOTTE_API_KEY}`
      }
    });
  }
}

main().catch(console.error);
```

### Response
#### Success Response (200)
- `session_id` (string) - The unique identifier for the started session.
- `cdp_url` (string) - The WebSocket URL for the Chrome DevTools Protocol endpoint.

#### Response Example
```json
{
  "session_id": "sess_abcdef123456",
  "cdp_url": "wss://cdp.notte.cc/session/sess_abcdef123456?token=..."
}
```
```

--------------------------------

### Starting Simple with Pydantic Models

Source: https://docs.notte.cc/features/agents/structured-output

Advises starting with minimal Pydantic models and gradually adding fields as needed. This approach simplifies initial development and allows for iterative refinement of the data structure, as shown with the evolution from `Product` to `DetailedProduct`.

```python
from pydantic import BaseModel


# Start with minimal model
class Product(BaseModel):
    name: str
    price: float


# Add fields as needed
class DetailedProduct(BaseModel):
    name: str
    price: float
    description: str | None
    specs: dict[str, str] | None
```
Tokens:
Raw