Python SDK

Explore the open-source repository https://github.com/nottelabs/notte and star us 🌟

Overview

The Notte Python SDK provides a comprehensive set of tools for interacting with the Notte API. This guide will walk you through the steps to install the SDK, configure your API key, and start using the SDK to manage your browser sessions, web agents, and page interactions.

We strongly recommend using the Python SDK for all your automation needs. It is the most efficient way to interact with the Notte API.

Quickstart

Install the latest version of the SDK (requires `python >= 3.11`)

pip install --upgrade notte-sdk

Configure your API key as an environment variable

You can request a free key directly from our console

export NOTTE_API_KEY=<your-api-key>

Run your first agent

import os
from notte_sdk import NotteClient

notte = NotteClient(api_key=os.getenv("NOTTE_API_KEY"))
response = notte.agents.run(
    task="Find the latest job openings on notte.cc", 
    max_step=5
)

Explore what the Notte Python SDK can do for you

The SDK provides a comprehensive set of tools for interacting with the Notte API.

Learn more about web agents in the web agents guide.

Run a Web Agent

from notte_sdk import NotteClient

notte = NotteClient()
agent = notte.Agent()
response = agent.run(task="Find the best italian restaurant in SF and book a table for 2 at 7pm today")
status = agent.status()

you can also get more control over the session and agent lifecycle by running an agent in a session explicitly:

session_control.py
with notte.Session(proxies=True) as session:  
	_ = notte.agents.run(
		task="<YOUR_TASK_PROMPT>",
		session_id=session.session_id
	)
	...

Learn more about web agents in the web agents guide.

Run a Web Agent

from notte_sdk import NotteClient

notte = NotteClient()
agent = notte.Agent()
response = agent.run(task="Find the best italian restaurant in SF and book a table for 2 at 7pm today")
status = agent.status()

you can also get more control over the session and agent lifecycle by running an agent in a session explicitly:

session_control.py
with notte.Session(proxies=True) as session:  
	_ = notte.agents.run(
		task="<YOUR_TASK_PROMPT>",
		session_id=session.session_id
	)
	...

Learn more about browser sessions in the browser sessions guide.

Manage your browser sessions

The recommended way to use the SDK is to use the statefull session API (but you can also use the stateless session API to manage the session lifecycle yourself (i.e., start/stop)).

from notte_sdk import NotteClient

notte = NotteClient()
# The session is automatically stopped when the context manager is exited
with notte.Session(timeout_minutes=2) as session:  
	status = session.status()
	print(status)

you can also always list all your sessions using the sessions.list method:

from notte_sdk import NotteClient

notte = NotteClient()

# list only active sessions
sessions = notte.sessions.list(active=True)

# list all sessions
sessions = notte.sessions.list()

Learn more about page interactions in the page interactions guide.

Take control and execute actions in a session

The Notte SDK also allows you to observe a web page and its actions, scrape the page content, as well as execute actions in a running session:

Observe: observe the actions available on a webpage
Step: take an action on the page (e.g., click a button, fill in a form, etc.)
Scrape: scrape a page in markdown format (or in a structured format using BaseModel from pydantic)

from notte_sdk import NotteClient

notte = NotteClient()
with notte.Session() as session:  
	# Observe the state of a webpage
	obs = session.observe(url="https://google.com/travel/flights")
	print("Page Title:", obs.metadata.title)
	print("Available Actions:", obs.space.actions())
	# # Example Output:
	# # Flight Search
	# * I1: Enter departure location (departureLocation: str = "San Francisco")
	# * I3: Select departure date (departureDate: date)
	# * I6: Select trip type (tripType: str = "round-trip", allowed=["round-trip", "one-way", "multi-city"])
	# 
	# # Website Navigation
	# * B5: Open Google apps menu
	# ...

	# Then you can take actions on the page
	obs = session.step(action_id="I1", value="San Francisco")

	# You scrape the final page data
	obs = session.scrape()
	print("Scraped Data:", obs.data)
	# Example Output:
	# Flight Search inputs
	# - Where from?: Paris
	# - Where to?: London
	# - Departure: Tue, June 14
	# 
	# Flight Search Results
	# | Airline       | Departure  | Arrival  | Duration   | Stops     | Price |
	# |---------------|------------|----------|------------|-----------|-------|
	# | easyJet       | 10:15 AM   | 10:35 AM | 1 hr 20 min| Nonstop   | $62   |
	# | Air France    | 4:10 PM    | 4:35 PM  | 1 hr 25 min| Nonstop   | $120  |
    # ...

Learn more about vaults and secrets in the vaults and secrets guide.

Manage your credentials in a secure vault

The Notte SDK allows you to securely store and access your credentials in a secure vault.

agent_with_vault.py
from notte_sdk import NotteClient

notte = NotteClient()
# Create a new secure vault
vault = notte.vaults.create()
# Add your credentials securely
_ = vault.add_credentials(
	url="https://github.com/",
	email="<your-email>",
	password="<your-password>",
	mfa_secret="<your-mfa-secret>",
)
# Run an agent with secure credential access
agent = notte.Agent(vault=vault)
response = agent.run(task="Go to the nottelabs/notte repo and star it. If it's already starred don't unstar it.")

Notte makes it super easy to scrape a webpage and extract structured data from it using pydantic models.

scrape.py
from pydantic import BaseModel
from notte_sdk import NotteClient

class JobPosting(BaseModel):
  jobTitle: str

notte = NotteClient()
job_title =  notte.scrape(
  url="https://linkedin.com",
  instruction="Extract the job title from the job posting",
  response_format=JobPosting,
)

How to get visual insights about your sessions & agents

At any time during the execution of a session or an agent, you can retrieve a replay of the execution so far as a WebP image.

from notte_sdk import NotteClient

notte = NotteClient()
# Get the replay of the session so far
replay = notte.sessions.replay(session_id="<your-session-id>")
# Or the agent's execution
replay = notte.agents.replay(agent_id="<your-agent-id>")

# Save the replay to a file
replay.save("replay.webp")
# Uncomment to display the replay in a Jupyter notebook
# replay.display()

Introduction

Concepts

Session Features

Use Cases

Integrations

Overview

Quickstart

Explore what the Notte Python SDK can do for you

Run a Web Agent

Run a Web Agent

Manage your browser sessions

Take control and execute actions in a session

Manage your credentials in a secure vault

How to get visual insights about your sessions & agents

Introduction

Concepts

Session Features

Use Cases

Integrations

​Overview

​Quickstart

​Explore what the Notte Python SDK can do for you

​Run a Web Agent

​Run a Web Agent

​Manage your browser sessions

​Take control and execute actions in a session

​Manage your credentials in a secure vault

​How to get visual insights about your sessions & agents

Overview

Quickstart

Explore what the Notte Python SDK can do for you

Run a Web Agent

Run a Web Agent

Manage your browser sessions

Take control and execute actions in a session

Manage your credentials in a secure vault

How to get visual insights about your sessions & agents