Creating Functions

Write and deploy browser automation Functions

AI agent instructions

Read the Notte skill and follow its setup instructions when setting up Notte or building browser automation. This is the shared source for CLI setup, authentication, and the browser-to-code workflow.

Learn how to write Function scripts and deploy them to Notte’s serverless infrastructure.

Writing a Function

Functions are Python scripts with a run() function that serves as the entry point.

Basic Function

The minimal Function structure:

hello_function.py

def run():
    """A simple function that returns a greeting."""
    return "Hello from Notte Functions!"

Function with Parameters

Accept input parameters:

greet_function.py

def run(name: str, greeting: str = "Hello"):
    """
    Greet someone by name.

    Args:
        name: The person's name
        greeting: The greeting word (default: "Hello")

    Returns:
        A personalized greeting
    """
    return f"{greeting}, {name}!"

Browser Automation Function

Use Notte SDK for browser automation:

scraper_function.py

from notte_sdk import NotteClient


def run(url: str, selector: str):
    """
    Scrape data from a website.

    Args:
        url: The website URL
        selector: CSS selector for target element

    Returns:
        Extracted data
    """
    client = NotteClient()

    with client.Session() as session:
        session.execute(type="goto", url=url)
        data = session.scrape(instructions=f"Extract content from {selector}")

    return {"url": url, "data": data}

Deploying Functions

Via SDK

Deploy from Python:

deploy_sdk.py

from notte_sdk import NotteClient

client = NotteClient()

# Deploy function
function = client.Function(path="scraper_function.py", name="Website Scraper", description="Scrapes data from websites")

print(f"Function deployed: {function.function_id}")
print(f"Version: {function.response.latest_version}")

Deployment Options

deployment_options.py

from notte_sdk import NotteClient

client = NotteClient()

function = client.Function(
    path="my_function.py",
    name="My Function",  # Display name
    description="What this function does",  # Description
    shared=False,  # Private by default
)

Parameters:

• path (str, required): Path to your Python file
• name (str, optional): Function display name
• description (str, optional): What the function does
• shared (bool, default=False): Whether other users can view and fork the function. Listing in the marketplace is separate (the read-only published field).

Function Requirements

The Handler

Must have a run() function:

handler_examples.py

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


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


# Wrong - no function
result = perform_task()

Dependencies

Import the Notte SDK, the standard library, and common third-party libraries such as requests and pydantic:

dependencies.py

# Standard library
import json
import re
from datetime import datetime

# Common third-party libraries
import requests
from pydantic import BaseModel

# Notte SDK
from notte_sdk import NotteClient


def run():
    # Your code
    pass

Imports are checked when you upload the code. Standard library modules that give process, filesystem, or network-socket access (for example os, subprocess, pathlib, socket) are rejected by default, as are packages that are not available in the runtime. The upload error lists what is allowed.

Return Values

Return JSON-serializable data:

return_values.py

def valid_returns():
    # Valid return types (JSON serializable)
    return "string"
    return 123
    return {"key": "value"}
    return ["item1", "item2"]
    return None


def invalid_returns():
    # Invalid returns (not JSON serializable)
    # return datetime.now()  # datetime not serializable
    # return lambda x: x     # functions not serializable
    pass

Parameter Types

Supported Types

parameter_types.py

def run(
    text: str,  # String
    number: int,  # Integer
    decimal: float,  # Float
    flag: bool,  # Boolean
    items: list,  # List
    data: dict,  # Dictionary
    optional: str | None = None,  # Optional
    with_default: int = 10,  # Default value
):
    pass

Type Validation

Type hints document what each parameter expects. They are not enforced, so convert or validate values yourself:

type_validation.py

def run(count: int):
    # Type hints document the expected input but are not enforced:
    # convert explicitly if the caller may send a string
    count = int(count)
    for i in range(count):
        print(i)

Complex Types

Structured parameters arrive as plain JSON values (dicts and lists). Validate them with Pydantic inside run():

complex_types.py

from notte_sdk import NotteClient
from pydantic import BaseModel


class SearchParams(BaseModel):
    url: str
    query: str
    max_results: int = 10


def run(params: dict):
    # Variables arrive as plain JSON values: validate them yourself
    search = SearchParams.model_validate(params)
    client = NotteClient()
    # Use search.url, search.query, etc.

Secrets

Store API keys and tokens as Function Secrets, either in the Console under Settings > Function Secrets, or with POST /secrets using the function_env namespace (client.secrets.store(...) in TypeScript). Every run of your functions receives them as environment variables:

read_secrets.py

import os


def run(url: str):
    # Function secrets are available as environment variables during the run
    api_key = os.environ.get("MY_API_KEY")
    webhook_url = os.environ.get("WEBHOOK_URL")

    if not api_key:
        return {"error": "MY_API_KEY is not configured"}

    return {"url": url, "webhook_configured": webhook_url is not None}

Reading environment variables needs the os module, which the default code check rejects. Upload code that reads secrets with the check relaxed: function.update(path="read_secrets.py", restricted=False) in Python, or fn.update({ path: './read_secrets.py', restricted: false }) in TypeScript.

Error Handling

Graceful Errors

Return error information in results:

graceful_errors.py

from notte_sdk import NotteClient


def run(url: str):
    try:
        client = NotteClient()
        with client.Session() as session:
            session.execute(type="goto", url=url)
            data = session.scrape()

        return {"success": True, "data": data}

    except Exception as e:
        return {"success": False, "error": str(e), "error_type": type(e).__name__}

Raising Exceptions

Let Functions fail explicitly:

raising_exceptions.py

def run(url: str):
    if not url.startswith("https://"):
        raise ValueError("URL must use HTTPS")

    # Continue with automation

Testing Locally

Test Before Deploying

Run your function locally:

test_locally.py

# Define your function (from your scraper_function.py)
def run(url: str, selector: str) -> dict:
    # Your scraping logic here
    return {"url": url, "selector": selector}


# Test with sample parameters
result = run(url="https://example.com", selector=".content")

print(result)

Run a Deployed Function Locally

Run the uploaded code on your machine, for example to debug it:

local_run.py

from notte_sdk import NotteClient

client = NotteClient()

# Load an existing function (Notte-managed functions also need decryption_key="...")
function = client.Function(function_id="func_abc123")

# Run the deployed code on your machine instead of the cloud
result = function.run(local=True, url="https://example.com")

print(result.result)

Best Practices

1. Document Parameters

Use clear docstrings:

document_params.py

def run(url: str, max_retries: int = 3):
    """
    Fetch data from a website with retries.

    Args:
        url: The website URL to scrape
        max_retries: Number of retry attempts on failure (default: 3)

    Returns:
        Dict with 'success' (bool) and 'data' (any) keys
    """
    pass

2. Return Structured Data

Use consistent return formats:

return_structured.py

from datetime import datetime


def scrape_url(url: str) -> dict:
    return {"scraped": url}


def run(url: str):
    try:
        # Perform automation
        data = scrape_url(url)

        return {"success": True, "data": data, "url": url, "timestamp": datetime.now().isoformat()}

    except Exception as e:
        return {"success": False, "error": str(e), "url": url}

3. Add Logging

Log key steps for debugging:

add_logging.py

from loguru import logger
from notte_sdk import NotteClient


def run(url: str):
    logger.info(f"Starting scrape of {url}")

    client = NotteClient()
    with client.Session() as session:
        logger.info("Session created")
        session.execute(type="goto", url=url)
        logger.info("Page loaded")

        data = session.scrape()
        logger.info(f"Extracted {len(data)} characters of markdown")

    return data

4. Set Timeouts

Bound how long each browser session can stay open, so a stuck page does not keep the run alive:

set_timeouts.py

from notte_sdk import NotteClient


def run(url: str):
    client = NotteClient()

    # Close the browser session after 5 idle minutes and cap it at 15 minutes
    with client.Session(idle_timeout_minutes=5, max_duration_minutes=15) as session:
        session.execute(type="goto", url=url)
        data = session.scrape()

    return data

5. Validate Inputs

Check parameters before processing:

validate_inputs.py

def run(url: str, count: int):
    # Validate inputs
    if not url.startswith("http"):
        return {"error": "Invalid URL format"}

    if count < 1 or count > 100:
        return {"error": "Count must be between 1 and 100"}

    # Proceed with automation
    pass

Examples

Simple Scraper

simple_scraper.py

from notte_sdk import NotteClient


def run(url: str):
    """Scrape page content."""
    client = NotteClient()

    with client.Session() as session:
        session.execute(type="goto", url=url)
        content = session.scrape()

    return content

Form Submission

form_submission.py

from notte_sdk import NotteClient


def run(form_url: str, name: str, email: str, message: str):
    """Submit a contact form."""
    client = NotteClient()

    with client.Session() as session:
        session.execute(type="goto", url=form_url)
        session.execute(type="fill", id="name", value=name)
        session.execute(type="fill", id="email", value=email)
        session.execute(type="fill", id="message", value=message)
        session.execute(type="click", selector="button[type='submit']")

    return {"status": "submitted"}

Data Extraction

structured_extraction.py

from notte_sdk import NotteClient
from pydantic import BaseModel


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


def run(product_url: str):
    """Extract structured product data."""
    client = NotteClient()

    with client.Session() as session:
        session.execute(type="goto", url=product_url)

        product = session.scrape(response_format=Product, instructions="Extract product details")

    return product.model_dump()

Next Steps

Invocations

Learn how to call your Functions

Schedules

Schedule Functions to run automatically

Management

Update and manage Functions

Functions Concept

Back to Functions overview