# Agent Start
Source: https://docs.notte.cc/api-reference/agents/agent-start
https://api.notte.cc/openapi.json post /agents/start
# Agent Stop
Source: https://docs.notte.cc/api-reference/agents/agent-stop
https://api.notte.cc/openapi.json delete /agents/{agent_id}/stop
# Get Script
Source: https://docs.notte.cc/api-reference/agents/get-script
https://api.notte.cc/openapi.json get /agents/{agent_id}/workflow/code
# Anything Start
Source: https://docs.notte.cc/api-reference/anything/anything-start
https://api.notte.cc/openapi.json post /anything/start
# Authentication
Source: https://docs.notte.cc/api-reference/authentication
Authenticate with the Notte API
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
All API requests require a Bearer token in the `Authorization` header.
## Get your API key
1. Sign in to the [Notte Console](https://console.notte.cc)
2. Navigate to your account settings
3. Generate or copy your API key
## Using the API key
Set your API key locally before calling the REST API or using the Python SDK:
```bash theme={null}
export NOTTE_API_KEY=your_api_key_here
```
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient() # reads NOTTE_API_KEY automatically
```
If you want the full machine-readable API contract, the OpenAPI spec is available at:
```text theme={null}
https://api.notte.cc/openapi.json
```
```bash theme={null}
curl https://api.notte.cc/sessions \
-H "Authorization: Bearer $NOTTE_API_KEY"
```
## Request headers
| Header | Required | Description |
| --------------- | -------- | ------------------------------------------ |
| `Authorization` | Yes | Bearer token with your API key |
| `Content-Type` | Yes | `application/json` for POST/PATCH requests |
# API Error Codes
Source: https://docs.notte.cc/api-reference/errors
API error responses and status codes
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
The API uses standard HTTP status codes and returns structured error responses.
## HTTP status codes
| Status | Description |
| ------ | ---------------------------------------------------------- |
| `200` | Success |
| `401` | Authentication failed — invalid or missing API key |
| `422` | Validation error — malformed request or invalid parameters |
| `429` | Rate limit exceeded |
| `500` | Internal server error |
| `529` | Cluster overloaded - Too many sessions |
## Error response format
```json theme={null}
{
"message": "Description of what went wrong",
"detail": "Additional context about the error"
}
```
## Common errors
### Authentication (401)
```json theme={null}
{
"message": "Authentication failed. Please check your credentials."
}
```
### Validation (422)
```json theme={null}
{
"message": "Validation error",
"detail": [
{
"loc": ["body", "url"],
"msg": "field required",
"type": "value_error.missing"
}
]
}
```
### Execution errors
Returned when an operation fails. Includes the `x-error-class: NotteApiExecutionError` header.
```json theme={null}
{
"message": "Error executing the requested operation"
}
```
# Function Fork
Source: https://docs.notte.cc/api-reference/functions/function-fork
https://api.notte.cc/openapi.json post /functions/{function_id}/fork
# Function Run Start
Source: https://docs.notte.cc/api-reference/functions/function-run-start
https://api.notte.cc/openapi.json post /functions/{function_id}/runs/start
# Function Schedule Delete
Source: https://docs.notte.cc/api-reference/functions/function-schedule-delete
https://api.notte.cc/openapi.json delete /functions/{function_id}/schedule
# Function Schedule Set
Source: https://docs.notte.cc/api-reference/functions/function-schedule-set
https://api.notte.cc/openapi.json post /functions/{function_id}/schedule
# Persona Emails List
Source: https://docs.notte.cc/api-reference/personas/persona-emails-list
https://api.notte.cc/openapi.json get /personas/{persona_id}/emails
# Persona Get
Source: https://docs.notte.cc/api-reference/personas/persona-get
https://api.notte.cc/openapi.json get /personas/{persona_id}
# Persona Sms List
Source: https://docs.notte.cc/api-reference/personas/persona-sms-list
https://api.notte.cc/openapi.json get /personas/{persona_id}/sms
# Profile Cookies Get
Source: https://docs.notte.cc/api-reference/profiles/profile-cookies-get
https://api.notte.cc/openapi.json get /profiles/{profile_id}/cookies
# Profile Cookies Set
Source: https://docs.notte.cc/api-reference/profiles/profile-cookies-set
https://api.notte.cc/openapi.json post /profiles/{profile_id}/cookies
# Profile Create
Source: https://docs.notte.cc/api-reference/profiles/profile-create
https://api.notte.cc/openapi.json post /profiles/create
# Profile Delete
Source: https://docs.notte.cc/api-reference/profiles/profile-delete
https://api.notte.cc/openapi.json delete /profiles/{profile_id}
# Profile Duplicate
Source: https://docs.notte.cc/api-reference/profiles/profile-duplicate
https://api.notte.cc/openapi.json post /profiles/{profile_id}/duplicate
# Profile Get
Source: https://docs.notte.cc/api-reference/profiles/profile-get
https://api.notte.cc/openapi.json get /profiles/{profile_id}
# Profile List
Source: https://docs.notte.cc/api-reference/profiles/profile-list
https://api.notte.cc/openapi.json get /profiles
# Rate Limits
Source: https://docs.notte.cc/api-reference/rate-limits
API rate limiting and response headers
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
The API implements rate limiting to ensure fair usage and platform stability.
## Rate limit headers
Every response includes headers with your current rate limit status:
| Header | Description |
| ----------------------- | ------------------------------------- |
| `X-RateLimit-Limit` | Maximum requests allowed per window |
| `X-RateLimit-Remaining` | Requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the window resets |
## Rate limit exceeded (429)
```json theme={null}
{
"message": "Rate limit exceeded",
"detail": "Please wait before making more requests"
}
```
## Checking your limits
```bash theme={null}
curl -I https://api.notte.cc/health \
-H "Authorization: Bearer $NOTTE_API_KEY"
```
Response headers:
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704067200
```
## Increasing limits
Need higher limits? [Contact us](https://cal.com/team/notte/demo) to discuss enterprise options.
# Get Secret
Source: https://docs.notte.cc/api-reference/secrets/get-secret
https://api.notte.cc/openapi.json get /secrets/{name}
# List Secrets
Source: https://docs.notte.cc/api-reference/secrets/list-secrets
https://api.notte.cc/openapi.json get /secrets
# Store Secret
Source: https://docs.notte.cc/api-reference/secrets/store-secret
https://api.notte.cc/openapi.json post /secrets
# Get Session Script
Source: https://docs.notte.cc/api-reference/sessions/get-session-script
https://api.notte.cc/openapi.json get /sessions/{session_id}/workflow/code
# Page Execute
Source: https://docs.notte.cc/api-reference/sessions/page-execute
https://api.notte.cc/openapi.json post /sessions/{session_id}/page/execute
# Page Observe
Source: https://docs.notte.cc/api-reference/sessions/page-observe
https://api.notte.cc/openapi.json post /sessions/{session_id}/page/observe
# Page Scrape
Source: https://docs.notte.cc/api-reference/sessions/page-scrape
https://api.notte.cc/openapi.json post /sessions/{session_id}/page/scrape
# Page Screenshot
Source: https://docs.notte.cc/api-reference/sessions/page-screenshot
https://api.notte.cc/openapi.json post /sessions/{session_id}/page/screenshot
# Session Cookies Get
Source: https://docs.notte.cc/api-reference/sessions/session-cookies-get
https://api.notte.cc/openapi.json get /sessions/{session_id}/cookies
# Session Cookies Set
Source: https://docs.notte.cc/api-reference/sessions/session-cookies-set
https://api.notte.cc/openapi.json post /sessions/{session_id}/cookies
# Session Network Logs
Source: https://docs.notte.cc/api-reference/sessions/session-network-logs
https://api.notte.cc/openapi.json get /sessions/{session_id}/network/logs
# Session Replay
Source: https://docs.notte.cc/api-reference/sessions/session-replay
https://api.notte.cc/openapi.json get /sessions/{session_id}/replay
# Session Start
Source: https://docs.notte.cc/api-reference/sessions/session-start
https://api.notte.cc/openapi.json post /sessions/start
# Session Stop
Source: https://docs.notte.cc/api-reference/sessions/session-stop
https://api.notte.cc/openapi.json delete /sessions/{session_id}/stop
# File Download
Source: https://docs.notte.cc/api-reference/storage/file-download
https://api.notte.cc/openapi.json get /storage/{session_id}/downloads/{filename}
# File Download Uploaded File
Source: https://docs.notte.cc/api-reference/storage/file-download-uploaded-file
https://api.notte.cc/openapi.json get /storage/uploads/{filename}
# File Upload
Source: https://docs.notte.cc/api-reference/storage/file-upload
https://api.notte.cc/openapi.json post /storage/uploads/{filename}
# Session Replay
Source: https://docs.notte.cc/api-reference/using-session-replay
Use mp4_url from GET /sessions/{session_id}/replay to download recordings
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
`GET /sessions/{session_id}/replay` returns presigned URLs for the session recording after the session has ended.
The field most clients need is **`mp4_url`**: a time-limited presigned URL for the MP4 file. Use it to download or share the recording from any HTTP client (webhooks, CI, non-Python SDKs). Check `expires_at` for when the URL stops working.
```bash theme={null}
curl "https://api.notte.cc/sessions/{session_id}/replay" \
-H "Authorization: Bearer $NOTTE_API_KEY"
```
Example response:
```json theme={null}
{
"mp4_url": "https://storage.example.com/replays/session_abc.mp4?X-Amz-Signature=...",
"playlist_content": "#EXTM3U\n...",
"expires_at": "2026-08-06T18:00:00+00:00",
"video_start_ms": 0,
"video_duration_ms": 45200
}
```
## Response fields
Presigned URL for downloading the session recording as an MP4. Prefer this when you need the video file itself.
HLS playlist content with presigned segment URLs, for streaming playback.
When the presigned URLs expire. Download promptly if you need a durable copy.
Video start offset in milliseconds.
Video duration in milliseconds.
From the Python SDK, the same payload is returned by `session.replay()` as a
[`ReplayResponse`](/sdk-reference/misc/replayresponse)[`ReplayResponse`](/sdk-reference/misc/replayresponse.md).
Use `replay.mp4_url` or `replay.download("session.mp4")`.
Interactive OpenAPI playground for this endpoint is available under the API tab
(Sessions → Session Replay), generated from
[https://api.notte.cc/openapi.json](https://api.notte.cc/openapi.json).
See also [Session recordings](/features/sessions/recordings).
# Vault Create
Source: https://docs.notte.cc/api-reference/vaults/vault-create
https://api.notte.cc/openapi.json post /vaults/create
# Vault Credentials Get
Source: https://docs.notte.cc/api-reference/vaults/vault-credentials-get
https://api.notte.cc/openapi.json get /vaults/{vault_id}/credentials
# Browser Agents
Source: https://docs.notte.cc/concepts/agents
AI-powered agents that autonomously complete browser tasks
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Browser Agents are AI-powered systems that can autonomously navigate websites, complete tasks, and extract information using natural language instructions.
## What is a Browser Agent?
A Browser Agent combines:
* **Large Language Models (LLMs)** for reasoning and decision-making
* **Browser Sessions** for executing actions
* **Vision capabilities** to understand web pages
* **Autonomous planning** to complete multi-step tasks
Unlike scripted automation, agents can adapt to changes, handle unexpected scenarios, and complete tasks without predefined workflows.
## Quick Start
Create and run an agent in a few lines:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(open_viewer=True) as session:
agent = client.Agent(session=session, max_steps=5)
response = agent.run(
task="Browse on Notte docs and book a demo for me",
url="https://docs.notte.cc"
)
print(response)
```
```javascript JavaScript theme={null}
import { NotteClient } from 'notte-sdk';
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
await client.Session({ open_viewer: true }).use(async (session) => {
const agent = client.Agent({ session, max_steps: 5 });
const response = await agent.run({
task: 'Browse on Notte docs and book a demo for me',
url: 'https://docs.notte.cc',
});
console.log(response);
});
```
Agents run within [browser sessions](/concepts/sessions). Use context managers to ensure sessions are automatically stopped when done. This prevents orphaned sessions and unexpected costs.
## How Agents Work
### 1. Observation
The agent observes the current page state:
* Visible elements and their properties
* Interactive components (buttons, forms, links)
* Text content and structure
* Current URL and page metadata
### 2. Reasoning
Using the LLM, the agent:
* Understands the current page
* Plans the next action to complete the task
* Decides which element to interact with
* Determines when the task is complete
### 3. Action
The agent executes browser actions:
* Navigate to URLs
* Click buttons and links
* Fill forms
* Extract data
* Scroll and interact with dynamic content
### 4. Iteration
This cycle repeats until:
* The task is successfully completed
* Maximum steps are reached
* An error occurs that can't be resolved
## Agents vs Scripted Automation
Both agents and scripted automation run on [browser sessions](/concepts/sessions)—the cloud browser infrastructure. The difference is how you control what happens in that session.
| Aspect | Scripted Automation | Agent |
| --------------- | ----------------------- | ------------------------------- |
| **Control** | You write the code | AI decides each step |
| **Flexibility** | Fixed workflow | Adapts to changes |
| **Speed** | Fast (direct execution) | Slower (LLM reasoning per step) |
| **Cost** | Browser minutes only | Browser minutes + LLM calls |
| **Reliability** | Deterministic | Can vary based on page state |
| **Use Case** | Known, stable workflows | Unknown or dynamic workflows |
**Use scripted automation when:**
* You know the exact steps to take
* Speed and cost are critical
* The target pages rarely change
**Use agents when:**
* You don't know the exact steps
* Pages change frequently
* You need intelligent decision-making
You can combine both approaches: use an agent to figure out a workflow, then [convert it to a function](/features/agents/workflows) for faster, cheaper repeated execution.
## Agent Capabilities
Agents come with powerful built-in capabilities:
Get type-safe responses using Pydantic models
Use credentials and identities in automations
Analyze images and visual page elements
Debug with MP4 replays of agent execution
Automatic recovery from script failures
## Key Concepts
### Natural Language Tasks
Give instructions in plain English:
```python Python theme={null}
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")
```
```javascript JavaScript theme={null}
import { NotteClient } from 'notte-sdk';
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
await client.Session().use(async (session) => {
const agent = client.Agent({ session });
await agent.run({
task: 'Find the cheapest laptop under $1000 and add it to cart',
});
});
```
### Structured Output
Get responses in a specific format:
```python Python theme={null}
from notte_sdk import NotteClient
from pydantic import BaseModel
client = NotteClient()
class ContactInfo(BaseModel):
email: str
phone: str | None
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(task="Extract contact information", response_format=ContactInfo)
```
```javascript JavaScript theme={null}
import { z } from 'zod';
import { NotteClient } from 'notte-sdk';
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
const ContactInfo = z.object({
email: z.string(),
phone: z.string().nullable(),
});
await client.Session().use(async (session) => {
const agent = client.Agent({ session });
const result = await agent.run({
task: 'Extract contact information',
response_format: ContactInfo,
});
});
```
### Starting URL
Begin at a specific page:
```python Python theme={null}
agent = client.Agent(session=session)
agent.run(task="Find pricing information", url="https://example.com/products")
```
```javascript JavaScript theme={null}
const agent = client.Agent({ session });
await agent.run({
task: 'Find pricing information',
url: 'https://example.com/products',
});
```
### Step Limits
Control maximum actions:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
agent.run(
task="Find and summarize the top 5 AI news from today",
max_steps=20, # Limit to 20 actions
)
```
```javascript JavaScript theme={null}
import { NotteClient } from 'notte-sdk';
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
await client.Session().use(async (session) => {
const agent = client.Agent({ session });
await agent.run({
task: 'Find and summarize the top 5 AI news from today',
max_steps: 20, // Limit to 20 actions
});
});
```
## Error Handling
Agents can fail for various reasons. Always check the result:
```python Python theme={null}
agent = client.Agent(session=session)
result = agent.run(task="Complete task")
if result.success:
print(result.answer)
else:
print(f"Agent failed: {result.answer}")
```
```javascript JavaScript theme={null}
const agent = client.Agent({ session });
const result = await agent.run({ task: 'Complete task' });
if (result.success) {
console.log(result.answer);
} else {
console.log(`Agent failed: ${result.answer}`);
}
```
## Next Steps
Create, manage, and stop agents
All configuration options
Get typed responses from agents
Turn agent runs into reusable code
# File Storage
Source: https://docs.notte.cc/concepts/file-storage
Upload and download files for your automations
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
File Storage provides a cloud bucket for uploading files to use in your automations and downloading files that agents retrieve from websites.
## Quick Start
```python quickstart.py theme={null}
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 in storage.list_downloaded_files():
storage.download(file_name=file.name, local_dir="./downloads")
```
## How It Works
File Storage has two buckets:
| Bucket | Purpose | API |
| ------------- | ----------------------------------- | -------------------- |
| **Uploads** | Files you upload for agents to use | `storage.upload()` |
| **Downloads** | Files agents download from websites | `storage.download()` |
```
┌─────────────┐ ┌──────────────┐
│ Local Files │ ── upload() ─────> │ Uploads │
└─────────────┘ └──────┬───────┘
│
v
┌──────────────┐
│ Session │
│ / Agent │
└──────┬───────┘
│
v
┌─────────────┐ ┌──────────────┐
│ Local Files │ <── download() ─── │ Downloads │
└─────────────┘ └──────────────┘
```
## Uploading Files
Upload files from your local machine to make them available in sessions:
```python uploading_files.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
storage = client.FileStorage()
# Upload a file (uses the original filename)
storage.upload("report.pdf")
# Upload with a custom name
storage.upload("report.pdf", upload_file_name="quarterly_report.pdf")
# List uploaded files
files = storage.list_uploaded_files()
print(f"Uploaded: {files}")
```
Each uploaded file must be under **100 MB**. For larger files, contact the
team at [support@notte.cc](mailto:support@notte.cc).
## Downloading Files
Download files that agents retrieved from websites:
```python downloading_files.py theme={null}
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 the invoice from the account page")
# List downloaded files
downloaded = storage.list_downloaded_files()
print(f"Downloaded: {downloaded}")
# Download to local directory
for file in downloaded:
storage.download(file_name=file.name, local_dir="./invoices")
```
### Force Overwrite
Overwrite existing local files:
```python force_overwrite.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
storage = client.FileStorage()
storage.download(
file_name="report.pdf",
local_dir="./downloads",
force=True, # Overwrite if exists
)
```
## Using with Agents
Agents can interact with files on websites when storage is attached:
```python using_with_agents.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
storage = client.FileStorage()
# Upload files for the agent to use
storage.upload("contract.pdf")
storage.upload("signature.png")
with client.Session(storage=storage) as session:
agent = client.Agent(session=session, max_steps=15)
result = agent.run(
task="""
1. Upload contract.pdf to the document portal
2. Add signature.png to the signature field
3. Submit the form
4. Download the signed confirmation
""",
url="https://example.com/documents",
)
# Get the confirmation the agent downloaded
for file in storage.list_downloaded_files():
storage.download(file_name=file.name, local_dir="./signed")
```
## Using with Sessions
Use file storage with scripted automation:
```python using_with_sessions.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
storage = client.FileStorage()
# Upload file
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"]', file_path="data.csv")
session.execute(type="click", selector="button.submit")
# Download any files
for file in storage.list_downloaded_files():
storage.download(file_name=file.name, local_dir="./results")
```
## API Reference
### FileStorage Methods
| Method | Description |
| --------------------------------------------- | ---------------------------------- |
| `upload(file_path, upload_file_name=None)` | Upload a local file to storage |
| `download(file_name, local_dir, force=False)` | Download a file to local directory |
| `list_uploaded_files()` | List files you've uploaded |
| `list_downloaded_files()` | List files downloaded by agents |
### Parameters
**upload()**
* `file_path` - Path to the local file to upload
* `upload_file_name` - Optional custom name for the uploaded file
**download()**
* `file_name` - Name of the file in storage
* `local_dir` - Local directory to save the file
* `force` - Overwrite existing file (default: False)
## Supported File Types
File storage supports all common file types:
* **Documents**: PDF, DOCX, XLSX, TXT, CSV
* **Images**: PNG, JPG, JPEG, GIF, WEBP
* **Archives**: ZIP, RAR, TAR, GZ
* **Media**: MP4, MP3
* **Data**: JSON, XML
## Best Practices
### 1. Attach Storage Before Starting
Always create and attach storage before starting the session:
```python attach_before_starting.py theme={null}
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
```
### 2. Use Descriptive Filenames
```python descriptive_filenames.py theme={null}
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
Always check for downloaded files after the session ends:
```python check_downloads.py theme={null}
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.name, local_dir="./invoices")
```
## Next Steps
Use agents with file operations
Learn about browser sessions
Store credentials securely
Create browser identities
# Functions
Source: https://docs.notte.cc/concepts/functions
Deploy browser automations as serverless API endpoints
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Functions are serverless deployments of your browser automations that can be invoked via API, scheduled to run automatically, or triggered by events.
## What are Functions?
Functions turn your automation scripts into:
* **API endpoints** you can call with HTTP requests
* **Scheduled jobs** that run on a cron schedule
* **Reusable workflows** accessible from anywhere
* **Shareable automations** for your team
Unlike running scripts locally, Functions:
* ✅ Run on Notte's infrastructure (no servers to manage)
* ✅ Scale automatically based on demand
* ✅ Provide built-in logging and monitoring
* ✅ Can be invoked from any platform (Python, JavaScript, cURL, etc.)
* ✅ Support scheduling and automation
## How Functions Work
### 1. Write Your Script
Create a Python file with a `run()` function:
```python basic_function.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
def run(url: str, search_query: str):
"""Search a website url and extract results."""
with client.Session() as session:
# Navigate to site
session.execute(type="goto", url=url)
# Search
session.execute(type="fill", selector="input[name='search']", value=search_query)
session.execute(type="press_key", key="Enter")
# Extract results
results = session.scrape(instructions="Extract search results")
return results
```
### 2. Deploy to Notte
Upload your script to create a Function:
```python deploy_function.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Deploy function
function = client.Function(
path="my_automation.py", name="Search Automation", description="Searches a website and extracts results"
)
print(f"Function deployed: {function.function_id}")
print(f"Version: {function.response.latest_version}")
```
### 3. Invoke the Function
Call your Function as an API:
```python invoke_sdk.py theme={null}
# Via SDK
result = function.run(url="https://example.com", search_query="laptop")
print(result.result)
```
```bash theme={null}
# Via cURL
curl -X POST https://api.notte.cc/functions/{function_id}/runs/start \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"function_id": "workflow_123",
"variables": {
"url": "https://example.com",
"search_query": "laptop"
}
}'
```
## Function Structure
### The Handler Function
Functions must have a `run()` function that serves as the entry point:
```python handler_function.py theme={null}
def run(param1: str, param2: int = 10):
"""
Function docstring explains what it does.
Args:
param1: Description of param1
param2: Description of param2 (optional)
Returns:
Description of return value
"""
# Your automation code
result = perform_automation(param1, param2)
return result
```
**Key points:**
* Named `run()` - this is the entry point
* Can accept parameters (passed as `variables` when invoked)
* Should have type hints for clarity
* Should include docstring documentation
* Returns a value (any JSON-serializable type)
### Parameters
Define parameters as arguments to the `run` function:
```python parameters_example.py theme={null}
from notte_sdk import NotteClient
def run(email: str, password: str, product_id: str):
client = NotteClient()
with client.Session() as session:
session.execute(type="fill", id="email", value=email)
session.execute(type="fill", id="password", value=password)
session.execute(type="goto", url=f"https://example.com/product/{product_id}")
```
Pass values when invoking the function:
```python pass_values.py theme={null}
function.run(email="user@example.com", password="secret", product_id="123")
```
### Return Values
Functions can return any JSON-serializable data:
```python return_values.py theme={null}
from pydantic import BaseModel
# Return string
def run_string():
return "Task completed successfully"
# Return dict
def run_dict():
extracted_data = ["item1", "item2"]
return {"status": "success", "data": extracted_data, "count": len(extracted_data)}
# Return list
def run_list():
return ["item1", "item2", "item3"]
# Return Pydantic model (serialized)
class Result(BaseModel):
success: bool
data: list[str]
def run():
return Result(success=True, data=["a", "b"]).model_dump()
```
## Use Cases
### 1. Scheduled Scraping
Extract data on a schedule:
```python price_monitor.py theme={null}
# price_monitor.py
def run(product_urls: list[str]):
run_client = NotteClient()
prices = []
for url in product_urls:
with run_client.Session() as session:
session.execute(type="goto", url=url)
price = session.scrape(instructions="Extract product price")
prices.append({"url": url, "price": price})
return prices
# Deploy and schedule to run daily
```
**Schedule:** `0 9 * * *` (Every day at 9 AM)
***
### 2. API Endpoints
Expose automation as an API:
```python contact_extractor.py theme={null}
from notte_sdk import NotteClient
# contact_extractor.py
def run(company_url: str):
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url=company_url)
contact_info = session.scrape(instructions="Extract contact email and phone")
return contact_info
# Now callable from any service
# GET /functions/{id}/runs/start?variables={"company_url": "..."}
```
***
### 3. Webhooks
Trigger automations from external events:
```python order_processor.py theme={null}
from notte_sdk import NotteClient
# order_processor.py
def run(order_id: str, action: str):
client = NotteClient()
with client.Session() as session:
# Login to admin panel
session.execute(type="goto", url="https://admin.example.com")
# Process order
if action == "fulfill":
session.execute(type="click", selector=f"button[data-order='{order_id}'].fulfill")
elif action == "refund":
session.execute(type="click", selector=f"button[data-order='{order_id}'].refund")
return {"order_id": order_id, "action": action, "status": "completed"}
# Called via webhook from your e-commerce platform
```
***
### 4. Batch Processing
Process multiple items in parallel:
```python bulk_data_extract.py theme={null}
from concurrent.futures import ThreadPoolExecutor
from notte_sdk import NotteClient
# bulk_data_extract.py
def run(urls: list[str], max_workers: int = 5):
client = NotteClient()
def extract_from_url(url):
with client.Session() as session:
session.execute(type="goto", url=url)
data = session.scrape()
return {"url": url, "data": data}
with ThreadPoolExecutor(max_workers=max_workers) as executor:
results = list(executor.map(extract_from_url, urls))
return results
```
## How Functions Fit In
Functions are a **deployment layer** - they turn any automation into a reusable API.
```
┌─────────────────────────────────────────────────────┐
│ Function │
│ (Deployment & Scheduling) │
├─────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Scripted │ or │ Agent │ │
│ │ Automation │ │ (AI-driven) │ │
│ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │
│ └──────────┬───────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ Session │ │
│ │ (Cloud Browser) │ │
│ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────┘
```
* **Session** - The cloud browser that runs everything
* **Scripted Automation vs Agent** - How you control the session
* **Function** - Deploys your automation as an API with scheduling, versioning, and sharing
**Use Functions when:**
* You need to run automation repeatedly
* You want to expose automation as an API
* You need scheduling capabilities
* You want to share automation with team or customers
Functions can contain either scripted automation or agents - they're not mutually exclusive.
## Function Lifecycle
```mermaid theme={null}
graph LR
A[Write Script] --> B[Deploy Function]
B --> C[Get Function ID]
C --> D{Invoke}
D -->|API Call| E[Execute]
D -->|Schedule| E
D -->|Webhook| E
E --> F[Return Result]
F --> G[Access Logs/Replay]
```
1. **Write** - Create Python script with `run()` function
2. **Deploy** - Upload to Notte (creates function ID)
3. **Version** - Notte tracks versions automatically
4. **Invoke** - Call via API, schedule, or webhook
5. **Execute** - Runs on Notte infrastructure
6. **Monitor** - View logs, replays, and results
## Best Practices
### 1. Use Clear Parameters
Define parameters with type hints and descriptions:
```python bp_clear_parameters.py theme={null}
def run(target_url: str, max_results: int = 10, timeout_seconds: int = 30):
"""
Extract data from a website.
Args:
target_url: The URL to scrape
max_results: Maximum number of results to extract
timeout_seconds: Session timeout
"""
pass
```
### 2. Return Structured Data
Always return JSON-serializable data:
```python bp_return_structured.py theme={null}
from datetime import datetime
def my_function():
results = [] # your data
# Good - return JSON-serializable dict
return {"success": True, "data": results, "count": len(results), "timestamp": datetime.now().isoformat()}
# Bad - not JSON serializable
# return datetime.now() # Can't serialize datetime directly
```
### 3. Handle Errors Gracefully
Catch exceptions and return meaningful errors:
```python bp_handle_errors.py theme={null}
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__}
```
### 4. Add Logging
Log important steps for debugging:
```python bp_add_logging.py theme={null}
from loguru import logger
from notte_sdk import NotteClient
def run(url: str):
logger.info(f"Starting automation for {url}")
client = NotteClient()
with client.Session() as session:
logger.info("Session started")
session.execute(type="goto", url=url)
logger.info("Navigation complete")
data = session.scrape()
logger.info(f"Extracted {len(data)} items")
return data
```
## Next Steps
Learn how to write and deploy Functions
Call Functions via API, SDK, or cURL
Schedule Functions with cron
Update, version, and monitor Functions
# Persona Identities
Source: https://docs.notte.cc/concepts/personas
Self-service identities for web automation (account creation, 2FA,etc.)
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
## Overview
Notte Personas provide automated identity management for AI agents, enabling them to create accounts, handle two-factor authentication, and interact with web platforms without manual intervention.
`Notte Personas` come with complete digital identities:
* **Unique Email Address**: Dedicated mailbox for each persona with full email management
* **Phone Number**: SMS-capable phone number for verification and 2FA
* **Credential Vault**: Optional secure storage for passwords and authentication tokens
* **Automated Communication**: Built-in email and SMS reading capabilities
* **2FA Support**: Seamless handling of two-factor authentication flows
### Persona Attributes
| Field | Example Value |
| --------------------- | ------------------------------------------------------------- |
| **Name** | David Mason |
| Email | [david.smith@mail-sand.com](mailto:david.smith@mail-sand.com) |
| Phone Number | +1234567890 |
| Notte Secret Vault ID | `21e75bga-1e3f-4389-a034-9aaa62d1f355` |
| Persona ID | `ab9ec497-8e49-49ab-9af7-cc04a95a0613` |
## How it works
![persona-workflow]()
Personas act as complete digital identities that your AI agents can assume during execution. When an agent needs to create an account or authenticate with a service, it uses the persona's credentials and communication channels to complete the entire flow autonomously.
The persona system integrates with both the browser session and the secure vault, allowing agents to:
1. Fill registration forms with persona details
2. Receive and read verification emails automatically
3. Handle SMS-based 2FA codes
4. Store generated passwords and tokens securely
This creates a seamless experience where agents can navigate complex authentication flows without breaking execution to wait for human intervention.
## Persona Management
### Python SDK
The following snippet shows how to create and manage personas using the Notte Python SDK.
> ⚠️ You need to have an active Notte account to create personas. Each persona incurs additional charges for the email and phone services.
```python personas.py theme={null}
import datetime as dt
from notte_sdk.client import NotteClient
client = NotteClient()
persona = client.Persona(create_vault=True)
print(f"Persona email: {persona.info.email}")
# add a credential to the persona: password is generated automatically and email is the persona's email
persona.add_credentials(url="https://github.com/")
# read recent emails
recent_emails = persona.emails(only_unread=True, limit=10, timedelta=dt.timedelta(minutes=5))
print(f"Recent emails: {recent_emails}")
# get your persona in subsequent scripts
same_persona = client.Persona(persona.info.persona_id)
assert same_persona.info == persona.info
# delete the persona when you don't need it anymore
persona.delete()
```
## Use Cases
### Account Creation Workflows
Personas excel at automating account registration across multiple platforms:
* **SaaS Signups**: Automatically create accounts on software platforms
* **E-commerce**: Register for shopping sites and marketplaces
* **Social Media**: Set up profiles across social networks
* **Financial Services**: Complete KYC and account opening processes
* **QA Testing**: Generate test accounts for quality assurance
## Security & Privacy
* 🔒 Each persona operates in complete isolation
* 🔒 Communication channels are encrypted and secure
* 🔒 Optional integration with Notte's secure vault system
* 🔒 Automatic cleanup and data retention policies
* 🔒 Full audit trail of persona activities
Personas are designed to work seamlessly with Notte's existing vault system. You can create a persona with an associated vault to store any credentials generated during account creation, ensuring they're available for future agent sessions.
Personas should be used responsibly and in compliance with the terms of service of the platforms your agents interact with. Ensure your use cases align with platform policies and applicable regulations.
# Scraping
Source: https://docs.notte.cc/concepts/scraping
Extract content and structured data from web pages
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Extract web page content as markdown or structured data using LLM-powered extraction.
## Quick Start
Extract structured data from a page:
```python Python theme={null}
from pydantic import BaseModel
from notte_sdk import NotteClient
class HackerNewsPost(BaseModel):
title: str
url: str
points: int
author: str
class HackerNewsFeed(BaseModel):
posts: list[HackerNewsPost]
client = NotteClient()
result = client.scrape(
url="https://news.ycombinator.com",
response_format=HackerNewsFeed,
instructions="Extract the top 5 posts from the front page"
)
for i, post in enumerate(result.data.posts, 1):
print(f"{i}. {post.points} - {post.title}")
```
```javascript JavaScript theme={null}
import { z } from 'zod';
import { NotteClient } from 'notte-sdk';
const HackerNewsPost = z.object({
title: z.string(),
url: z.string(),
points: z.number(),
author: z.string(),
});
const HackerNewsFeed = z.object({
posts: z.array(HackerNewsPost),
});
const notte = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
const result = await notte.scrape('https://news.ycombinator.com', {
instructions: 'Extract the top 5 posts from the front page',
response_format: HackerNewsFeed,
});
result.posts.forEach((post, index) => {
console.log(`${index + 1}. ${post.points} - ${post.title}`);
});
```
## Scraping Methods
Notte provides two ways to scrape:
| Method | Use Case |
| -------------------- | ------------------------------------------- |
| `client.scrape(url)` | Quick, one-off scrapes |
| `session.scrape()` | Scraping after navigation or authentication |
### Quick Scrape
For simple scraping without session management:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Returns markdown content
markdown = client.scrape("https://example.com")
```
```javascript JavaScript theme={null}
import { NotteClient } from 'notte-sdk';
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
// Returns markdown content
const markdown = await client.scrape('https://example.com');
```
### Session-Based Scrape
For scraping after authentication or navigation:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
# Navigate and authenticate
session.execute(type="goto", url="https://example.com/login")
session.execute(type="fill", selector="input[name='email']", value="user@example.com")
session.execute(type="fill", selector="input[name='password']", value="password")
session.execute(type="click", selector="button[type='submit']")
# Navigate to protected page
session.execute(type="goto", url="https://example.com/dashboard")
# Scrape the page
content = session.scrape()
```
```javascript JavaScript theme={null}
import { NotteClient } from 'notte-sdk';
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
await client.Session().use(async (session) => {
// Navigate and authenticate
await session.execute({ type: 'goto', url: 'https://example.com/login' });
await session.execute({ type: 'fill', selector: "input[name='email']", value: 'user@example.com' });
await session.execute({ type: 'fill', selector: "input[name='password']", value: 'password' });
await session.execute({ type: 'click', selector: "button[type='submit']" });
// Navigate to protected page
await session.execute({ type: 'goto', url: 'https://example.com/dashboard' });
// Scrape the page
const content = await session.scrape();
});
```
## Structured Extraction
Extract data into typed Python objects using Pydantic models. The extraction is powered by an LLM that understands the page content and extracts the specified fields.
### Using Pydantic Models
Define a schema and extract matching data:
```python Python theme={null}
from notte_sdk import NotteClient
from pydantic import BaseModel
class Product(BaseModel):
name: str
price: float
description: str
client = NotteClient()
product = client.scrape(
"https://example.com/product", response_format=Product, instructions="Extract the product details"
)
print(f"Name: {product.name}, Price: {product.price}")
```
```javascript JavaScript theme={null}
import { z } from 'zod';
import { NotteClient } from 'notte-sdk';
const Product = z.object({
name: z.string(),
price: z.number(),
description: z.string(),
});
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
const product = await client.scrape('https://example.com/product', {
response_format: Product,
instructions: 'Extract the product details',
});
console.log(`Name: ${product.name}, Price: ${product.price}`);
```
### Using Instructions Only
For flexible extraction without a strict schema:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
result = client.scrape(
"https://example.com/article", instructions="Extract the article title, author, and publication date"
)
print(result)
```
```javascript JavaScript theme={null}
import { NotteClient } from 'notte-sdk';
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
const result = await client.scrape('https://example.com/article', {
instructions: 'Extract the article title, author, and publication date',
});
console.log(result);
```
### Extracting Lists
Extract multiple items from a page:
```python Python theme={null}
from notte_sdk import NotteClient
from pydantic import BaseModel
class Article(BaseModel):
title: str
url: str
summary: str
class ArticleList(BaseModel):
articles: list[Article]
client = NotteClient()
articles = client.scrape(
"https://news.example.com", response_format=ArticleList, instructions="Extract all articles from the homepage"
)
for article in articles.articles:
print(f"{article.title}: {article.url}")
```
```javascript JavaScript theme={null}
import { z } from 'zod';
import { NotteClient } from 'notte-sdk';
const Article = z.object({
title: z.string(),
url: z.string(),
summary: z.string(),
});
const ArticleList = z.object({
articles: z.array(Article),
});
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
const articles = await client.scrape('https://news.example.com', {
response_format: ArticleList,
instructions: 'Extract all articles from the homepage',
});
for (const article of articles.articles) {
console.log(`${article.title}: ${article.url}`);
}
```
### Nested Structures
Handle complex, nested data:
```python Python theme={null}
from notte_sdk import NotteClient
from pydantic import BaseModel
class Address(BaseModel):
street: str
city: str
country: str
class Company(BaseModel):
name: str
description: str
address: Address
employee_count: int | None
client = NotteClient()
company = client.scrape(
"https://example.com/about", response_format=Company, instructions="Extract company information including address"
)
print(company.address.city)
```
```javascript JavaScript theme={null}
import { z } from 'zod';
import { NotteClient } from 'notte-sdk';
const Address = z.object({
street: z.string(),
city: z.string(),
country: z.string(),
});
const Company = z.object({
name: z.string(),
description: z.string(),
address: Address,
employee_count: z.number().nullable(),
});
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
const company = await client.scrape('https://example.com/about', {
response_format: Company,
instructions: 'Extract company information including address',
});
console.log(company.address.city);
```
## Image Extraction
Extract all images from a page:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
images = client.scrape("https://example.com/gallery", only_images=True)
for image in images:
print(f"URL: {image.url}")
print(f"Description: {image.description}")
```
```javascript JavaScript theme={null}
import { NotteClient } from 'notte-sdk';
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
const images = await client.scrape('https://example.com/gallery', {
only_images: true,
});
for (const image of images) {
console.log(`URL: ${image.url}`);
console.log(`Description: ${image.description}`);
}
```
## Configuration Options
### Content Filtering
Control what content gets extracted:
```python Python theme={null}
# Only main content (excludes navbars, footers, sidebars)
markdown = client.scrape(url, only_main_content=True) # Default
# Include all page content
markdown = client.scrape(url, only_main_content=False)
```
```javascript JavaScript theme={null}
// Only main content (excludes navbars, footers, sidebars)
const markdown = await client.scrape(url, { only_main_content: true }); // Default
// Include all page content
const fullMarkdown = await client.scrape(url, { only_main_content: false });
```
### Links and Images
Control link and image extraction:
```python Python theme={null}
# Include links (default)
markdown = client.scrape(url, scrape_links=True)
# Exclude links
markdown = client.scrape(url, scrape_links=False)
# Include images in markdown
markdown = client.scrape(url, scrape_images=True)
# Exclude images (default)
markdown = client.scrape(url, scrape_images=False)
```
```javascript JavaScript theme={null}
// Include links (default)
const markdownWithLinks = await client.scrape(url, { scrape_links: true });
// Exclude links
const markdownWithoutLinks = await client.scrape(url, { scrape_links: false });
// Include images in markdown
const markdownWithImages = await client.scrape(url, { scrape_images: true });
// Exclude images (default)
const markdownWithoutImages = await client.scrape(url, { scrape_images: false });
```
### Scoped Scraping
Scrape only a specific section of the page:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
# Scrape content within a specific selector
content = session.scrape(selector="article.main-content")
# Scrape a specific container
content = session.scrape(selector="#product-details")
```
```javascript JavaScript theme={null}
import { NotteClient } from 'notte-sdk';
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
await client.Session().use(async (session) => {
// Scrape content within a specific selector
const articleContent = await session.scrape({
selector: 'article.main-content',
});
// Scrape a specific container
const productContent = await session.scrape({
selector: '#product-details',
});
});
```
### Link Placeholders
Reduce output size by using placeholders:
```python Python theme={null}
# Use placeholders for links and images
markdown = client.scrape(url, use_link_placeholders=True)
```
```javascript JavaScript theme={null}
// Use placeholders for links and images
const markdown = await client.scrape(url, {
use_link_placeholders: true,
});
```
## Return Types
The scrape method returns different types based on parameters:
| Parameters | Return Type |
| ------------------ | --------------------------- |
| None | `str` (markdown) |
| `instructions` | `StructuredData[BaseModel]` |
| `response_format` | `StructuredData[YourModel]` |
| `only_images=True` | `list[ImageData]` |
### StructuredData Response
When using structured extraction:
```python Python theme={null}
from notte_sdk import NotteClient
from pydantic import BaseModel
class Product(BaseModel):
name: str
price: float
client = NotteClient()
url = "https://example.com/product"
product = client.scrape(url, response_format=Product)
# Access the extracted data
print(f"Name: {product.name}, Price: {product.price}")
```
```javascript JavaScript theme={null}
import { z } from 'zod';
import { NotteClient } from 'notte-sdk';
const Product = z.object({
name: z.string(),
price: z.number(),
});
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
const url = 'https://example.com/product';
const product = await client.scrape(url, {
response_format: Product,
});
// Access the extracted data
console.log(`Name: ${product.name}, Price: ${product.price}`);
```
## Use Cases
### Data Collection
Collect product information:
```python Python theme={null}
from notte_sdk import NotteClient
from pydantic import BaseModel
class ProductInfo(BaseModel):
name: str
price: float
rating: float | None
reviews_count: int | None
client = NotteClient()
urls = [
"https://store.example.com/product/1",
"https://store.example.com/product/2",
]
products: list[ProductInfo] = []
for url in urls:
data = client.scrape(url, response_format=ProductInfo)
products.append(data)
```
```javascript JavaScript theme={null}
import { z } from 'zod';
import { NotteClient } from 'notte-sdk';
const ProductInfo = z.object({
name: z.string(),
price: z.number(),
rating: z.number().nullable(),
reviews_count: z.number().nullable(),
});
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
const urls = [
'https://store.example.com/product/1',
'https://store.example.com/product/2',
];
const products = [];
for (const url of urls) {
const data = await client.scrape(url, {
response_format: ProductInfo,
});
products.push(data);
}
```
### Content Monitoring
Track content changes:
```python Python theme={null}
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
# ...
```
```javascript JavaScript theme={null}
import { NotteClient } from 'notte-sdk';
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
// Get current content
const content = await client.scrape('https://example.com/pricing', {
instructions: 'Extract all pricing tiers and their features',
});
// Compare with previous version
// ...
```
### Research and Analysis
Extract structured research data:
```python Python theme={null}
from notte_sdk import NotteClient
from pydantic import BaseModel
class ResearchPaper(BaseModel):
title: str
authors: list[str]
abstract: str
publication_date: str | None
citations: int | None
client = NotteClient()
result = client.scrape("https://papers.example.com/paper/123", response_format=ResearchPaper)
```
```javascript JavaScript theme={null}
import { z } from 'zod';
import { NotteClient } from 'notte-sdk';
const ResearchPaper = z.object({
title: z.string(),
authors: z.array(z.string()),
abstract: z.string(),
publication_date: z.string().nullable(),
citations: z.number().nullable(),
});
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
const result = await client.scrape('https://papers.example.com/paper/123', {
response_format: ResearchPaper,
});
```
## Best Practices
### 1. Use Specific Instructions
Clear instructions improve extraction accuracy:
```python Python theme={null}
# Good
instructions = "Extract the product name, price in USD, and availability status"
# Vague
instructions = "Get product info"
```
```javascript JavaScript theme={null}
// Good
const instructions = 'Extract the product name, price in USD, and availability status';
// Vague
const vagueInstructions = 'Get product info';
```
### 2. Define Precise Schemas
Match your schema to the actual page content:
```python Python theme={null}
from pydantic import BaseModel
# Good - matches page structure
class GoodProduct(BaseModel):
name: str
price: float
in_stock: bool
# Bad - fields that may not exist
class BadProduct(BaseModel):
name: str
price: float
manufacturer: str # Page might not have this
warranty: str # Page might not have this
```
```javascript JavaScript theme={null}
import { z } from 'zod';
// Good - matches page structure
const GoodProduct = z.object({
name: z.string(),
price: z.number(),
in_stock: z.boolean(),
});
// Bad - fields that may not exist
const BadProduct = z.object({
name: z.string(),
price: z.number(),
manufacturer: z.string(), // Page might not have this
warranty: z.string(), // Page might not have this
});
```
### 3. Handle Missing Data
Use optional fields for data that might not exist:
```python Python theme={null}
from pydantic import BaseModel
class Product(BaseModel):
name: str
price: float
discount_price: float | None = None # Optional
rating: float | None = None # Optional
```
```javascript JavaScript theme={null}
import { z } from 'zod';
const Product = z.object({
name: z.string(),
price: z.number(),
discount_price: z.number().nullable().optional(), // Optional
rating: z.number().nullable().optional(), // Optional
});
```
### 4. Scope Your Scrapes
Use selectors to focus on relevant content:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
# Scrape only the main article, not comments or sidebar
content = session.scrape(selector="article.main")
```
```javascript JavaScript theme={null}
import { NotteClient } from 'notte-sdk';
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
await client.Session().use(async (session) => {
// Scrape only the main article, not comments or sidebar
const content = await session.scrape({
selector: 'article.main',
});
});
```
## Next Steps
Learn about session management
Use AI agents for complex scraping
Store credentials for authenticated scraping
Deploy scraping as serverless functions
# Browser Sessions
Source: https://docs.notte.cc/concepts/sessions
Cloud-hosted browser instances for automation
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Sessions are isolated browser instances running in the cloud that you can control programmatically. Think of them as headless Chrome browsers, but managed, scalable, and equipped with anti-detection, proxies, and captcha solving out of the box.
Every operation in Notte—whether you're running an AI agent, scraping data, or automating a workflow—happens within a session.
## Quick Start
Create a session and start automating:
```python Python theme={null}
from playwright.sync_api import sync_playwright
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(open_viewer=True) as session:
cdp_url = session.cdp_url()
with sync_playwright() as p:
browser = p.chromium.connect_over_cdp(cdp_url)
page = browser.contexts[0].pages[0]
page.goto("https://www.google.com")
page.screenshot(path="screenshot.png")
```
```javascript JavaScript theme={null}
import { chromium } from 'playwright-core';
import { NotteClient } from 'notte-sdk';
const notte = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
await notte.Session({ open_viewer: true }).use(async (session) => {
const status = await session.status();
const cdpUrl = status.cdp_url;
if (!cdpUrl) {
throw new Error('Session did not return a cdp_url');
}
const browser = await chromium.connectOverCDP(cdpUrl);
try {
const page = browser.contexts()[0].pages()[0];
await page.goto('https://news.ycombinator.com');
const topStories = await page.locator('.titleline > a').allInnerTexts();
console.log('Top 5 Hacker News stories:');
topStories.slice(0, 5).forEach((title, index) => {
console.log(`${index + 1}. ${title}`);
});
} finally {
await browser.close();
}
});
```
We strongly recommend using the `with` statement (context manager) to ensure sessions are automatically stopped when done. This prevents orphaned sessions and unexpected costs. See [Session Lifecycle](/features/sessions/lifecycle) for manual management options.
## Core Operations
Sessions provide three methods for interacting with the browser:
| Method | Purpose |
| ----------- | ------------------------------------------------ |
| `observe()` | Get the current page state and available actions |
| `execute()` | Perform an action on the page |
| `scrape()` | Extract structured data from the page |
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as page:
url = "https://www.linkedin.com/"
# observe page and take a step
page.execute(type="goto", url=url)
actions = page.observe(instructions="click 'jobs'")
res = page.execute(actions[0])
print(res.message)
# another one
actions = page.observe(instructions="dismiss the sign in check")
res = page.execute(actions[0])
print(res.message)
```
```javascript JavaScript theme={null}
import { NotteClient } from 'notte-sdk';
const client = new NotteClient({
apiKey: process.env.NOTTE_API_KEY,
});
await client.Session().use(async (page) => {
const url = 'https://www.linkedin.com/';
// Observe page and take a step
await page.execute({ type: 'goto', url });
let actions = await page.observe({ instructions: "click 'jobs'" });
let result = await page.execute(actions[0]);
console.log(result.message);
// Another one
actions = await page.observe({ instructions: 'dismiss the sign in check' });
result = await page.execute(actions[0]);
console.log(result.message);
});
```
## Session Capabilities
Sessions come with powerful built-in capabilities:
Route traffic through residential proxies for geo-targeting
Automatically solve reCAPTCHA and hCaptcha
Evade bot detection with fingerprint randomization
Record sessions for debugging and replay
Watch sessions execute in real-time
Persist browser state across sessions
## Next Steps
Create, manage, and stop sessions
All configuration options
Complete action reference
Use Playwright via CDP
# Secret Vaults
Source: https://docs.notte.cc/concepts/vaults
Enterprise-grade credential management for your Sessions & Agents
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
## Overview
Notte provides an enterprise-grade secure vault system that allows you to safely share authentication details with AI agents.
All sensitive data is encrypted at rest and in transit, and credentials are never exposed to LLMs or third-party services during agent execution.
This ensures your passwords, API keys, and other secrets remain protected while enabling agents to authenticate and interact with services on your behalf.
## Secure your credentials
Your credentials are protected with multiple layers of security:
* **End-to-End Encryption**: All secrets are encrypted at rest and in transit.
* **Zero Trust Architecture**: Credentials are never forwarded to LLM calls or external services.
* **Restricted Access**: Only your agents can access your credentials.
* **2FA Support**: Comprehensive support for two-factor authentication credentials.
## How it works
![vault-fill-action]()
The Vault acts as an intermediary between the LLM agent and the browser session.
Some actions like `FillActions` may contain secure information such as passwords, credit card numbers, MFA secrets, etc.
When the system detects that the intent of the LLM Agent is to use such sensitive information, the vault takes over the execution and manually replaces the dummy
credentials provided by the LLM with the actual credentials based on the content of the vault.
The significant security benefit of this approach is that the LLM never actually sees the actual credentials.
## Vault Management
### Python SDK
The following snippet shows how to manage your vault using the Notte Python SDK.
```python agent_with_vault.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Get your vault id from the Notte dashboard
vault = client.Vault(vault_id="my_vault_id")
# Add your credentials securely
vault.add_credentials(
url="https://github.com/",
email="my_cool_email@gmail.com",
password="my_cool_password",
)
# Run an agent with secure credential access
with client.Session() as session:
agent = client.Agent(vault=vault, session=session, max_steps=10)
response = agent.run(task="Go to the nottelabs/notte repo and star it. If it's already starred don't unstar it.")
```
## Security Guarantees
* 🔒 Credentials are never stored in plain text
* 🔒 No credential data is sent to LLM providers
* 🔒 All credential operations are performed locally
* 🔒 Access to credentials is strictly controlled and logged
* 🔒 Open-source implementation for transparency
# Agent Configuration
Source: https://docs.notte.cc/features/agents/configuration
Configure agent behavior with creation and runtime parameters
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Configure agents with parameters that control their reasoning model, step limits, vision capabilities, and more.
## Creating an Agent
Create an agent with configuration parameters:
```python creating_agent.py theme={null}
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
)
```
## Agent Creation Parameters
Parameters set when creating the agent instance.
### session
The browser session the agent will use to execute actions. Must be a Notte session instance.
```python param_session.py theme={null}
with client.Session(headless=False) as session:
agent = client.Agent(session=session)
```
### reasoning\_model
The large language model used for agent reasoning and decision-making. Supported models include `gemini/gemini-2.0-flash`, `anthropic/claude-3.5-sonnet`, `anthropic/claude-3.5-haiku`, `openai/gpt-4o`, and `openai/gpt-4o-mini`.
```python param_reasoning_model.py theme={null}
agent = client.Agent(session=session, reasoning_model="anthropic/claude-3.5-sonnet")
```
### use\_vision
Whether to enable vision capabilities for the agent. Vision allows the agent to analyze images, screenshots, and visual page elements. Not all models support vision.
```python param_use_vision.py theme={null}
agent = client.Agent(
session=session,
use_vision=True, # Agent can understand images
)
```
### max\_steps
Maximum number of actions the agent can take before stopping. Must be between 1 and 50. Higher values allow more complex tasks but increase cost and execution time.
```python param_max_steps.py theme={null}
agent = client.Agent(
session=session,
max_steps=20, # Allow up to 20 actions
)
```
### vault
Optional vault instance containing credentials the agent can use for authentication. See [Vaults](/concepts/vaults) for details.
```python param_vault.py theme={null}
vault = client.Vault(vault_id="vault_123")
agent = client.Agent(
session=session,
vault=vault, # Agent can access vault credentials
)
```
### persona
Optional persona providing the agent with phone numbers, email addresses, and other identity information. See [Personas](/concepts/personas) for details.
```python param_persona.py theme={null}
persona = client.Persona(persona_id="persona_456")
agent = client.Agent(
session=session,
persona=persona, # Agent can use persona information
)
```
### notifier
Optional notifier that sends notifications when the agent completes or fails. Useful for long-running tasks.
```python param_notifier.py theme={null}
with client.Session() as session:
# Agent with notification via email
agent = client.Agent(
session=session,
# Notifications can be configured in the Notte console
)
```
## Agent Runtime Parameters
Parameters provided when running the agent.
### task
Natural language description of what the agent should accomplish. Be specific and clear for best results.
```python param_task.py theme={null}
result = agent.run(task="Find the cheapest laptop under $1000 and add it to cart")
```
### url
Optional starting URL for the agent. If not provided, the agent starts from the current page in the session.
```python param_url.py theme={null}
result = agent.run(task="Extract pricing information", url="https://example.com/products")
```
### response\_format
Optional Pydantic model defining the structure of the agent's response. Use this to get type-safe, structured output. See [Structured Output](/features/agents/structured-output) for details.
```python param_response_format.py theme={null}
from notte_sdk import NotteClient
from pydantic import BaseModel
class Product(BaseModel):
name: str
price: float
in_stock: bool
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(task="Extract product information", response_format=Product)
```
### session\_offset
**Experimental** - The step number from which the agent should gather information from the session history. If not provided, the agent has fresh memory. Use this to make the agent aware of previous actions.
```python param_session_offset.py theme={null}
# Execute some actions first
session.execute(type="goto", url="https://example.com")
session.execute(type="click", selector="button.search")
# Agent remembers actions from step 0
result = agent.run(task="Continue from where we left off", session_offset=0)
```
## Configuration Examples
### Simple Agent
Minimal configuration for basic tasks:
```python simple_agent.py theme={null}
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(task="Find contact email")
```
### Production Agent
Full configuration for production use:
```python production_agent.py theme={null}
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}")
```
### Structured Data Extraction
Agent configured for data extraction:
```python structured_extraction.py theme={null}
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 and result.answer:
company = CompanyInfo.model_validate_json(result.answer)
print(f"Company: {company.name}")
print(f"Email: {company.email}")
print(f"Phone: {company.phone}")
```
## Best Practices
### 1. Choose Appropriate Step Limits
Match `max_steps` to task complexity:
```python bp_step_limits.py theme={null}
# Simple task (3-5 actions)
max_steps = 5
# Medium complexity (5-15 actions)
max_steps = 15
# Complex multi-page task (15-30 actions)
max_steps = 30
```
### 2. Balance Cost and Capability
Use cheaper models for simple tasks:
```python bp_model_selection.py theme={null}
# Simple navigation and extraction
reasoning_model = "gemini/gemini-2.0-flash"
# Complex reasoning and decision-making
reasoning_model = "anthropic/claude-3.5-sonnet"
```
### 3. Use Vision Selectively
Disable vision when not needed to reduce costs:
```python bp_vision.py theme={null}
# Text-only site
agent = client.Agent(session=session, use_vision=False)
# Image-heavy site
agent = client.Agent(session=session, use_vision=True)
```
### 4. Provide Context via URL
Start agents at the right page:
```python bp_url_context.py theme={null}
# Good - start where needed
agent.run(task="Extract product details", url="https://example.com/product/123")
# Less efficient - agent must navigate first
agent.run(task="Go to product page and extract details", url="https://example.com")
```
## Next Steps
Learn about agent execution modes
Debug agents with visual replays
Get typed responses from agents
Store credentials for agent use
# Agent Fallback
Source: https://docs.notte.cc/features/agents/fallback
Automatically recover from script failures with AI agents
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Agent Fallback automatically spawns an AI agent when deterministic script execution fails, providing intelligent error recovery without manual intervention.
## Overview
When executing session actions, failures can occur due to:
* Elements not found
* Unexpected page changes
* Timing issues
* Dynamic content
Agent Fallback catches these failures and uses an agent to recover:
```python agent_fallback.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
with client.AgentFallback(session, task="Add item to cart") as fb:
# Try deterministic actions
session.execute(type="click", selector="#add-to-cart")
session.execute(type="click", selector="#checkout")
# If any action fails, agent takes over automatically
if fb.success:
print("Task completed!")
if fb.agent_invoked:
print("Agent helped recover from failure")
```
## How It Works
### 1. Normal Execution
Actions execute normally when they succeed:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
with client.AgentFallback(session, task="Submit form") as fb:
session.execute(type="fill", selector="input[name='email']", value="user@example.com")
session.execute(type="click", selector="button[type='submit']")
# No agent spawned if all actions succeed
print(f"Agent invoked: {fb.agent_invoked}") # False
```
### 2. Automatic Recovery
When an action fails, the agent spawns:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
with client.AgentFallback(session, task="Add to cart") as fb:
# This selector is wrong - action will fail
session.execute(type="click", selector="#wrong-selector")
# Agent automatically:
# 1. Sees the failure
# 2. Understands the task ("Add to cart")
# 3. Finds the correct button
# 4. Completes the action
print(f"Agent invoked: {fb.agent_invoked}") # True
print(f"Success: {fb.success}") # True (agent recovered)
```
### 3. Continuation
After agent recovery, remaining actions are skipped:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
with client.AgentFallback(session, task="Complete checkout") as fb:
session.execute(type="click", selector="#step1") # Success
session.execute(type="click", selector="#step2") # Fails - agent spawned
session.execute(type="click", selector="#step3") # Skipped (agent already handled task)
```
## Use Cases
### 1. Fragile Selectors
Handle pages with frequently changing selectors:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
with client.AgentFallback(session, task="Click the submit button") as fb:
# Try specific selector first (fast and cheap)
session.execute(type="click", selector="button#submit-btn")
# If selector changed, agent finds the button (slower but works)
```
### 2. Dynamic Content
Handle dynamically loaded content:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
with client.AgentFallback(session, task="Click the popup close button") as fb:
# Try clicking without waiting
session.execute(type="click", selector=".popup-close")
# If popup not loaded yet, agent waits and retries
```
### 3. A/B Testing
Handle pages with multiple variations:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
with client.AgentFallback(session, task="Click continue button") as fb:
# Try variant A
session.execute(type="click", selector="#continue-a")
# If user got variant B, agent adapts
```
### 4. Graceful Degradation
Start with fast scripts, fall back to AI when needed:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
with client.AgentFallback(session, task="Navigate to pricing") as fb:
# Fast path - direct navigation
session.execute(type="click", selector="nav a[href='/pricing']")
# Slow path - agent finds the pricing link if layout changed
```
## Configuration
### Task Description
The task guides the agent when it's invoked:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
# Clear task description helps agent understand goal
with client.AgentFallback(session, task="Add the first product to cart") as fb:
session.execute(type="click", selector=".add-to-cart")
```
### Agent Parameters
Pass agent configuration:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
with client.AgentFallback(
session,
task="Complete signup",
max_steps=15, # Agent parameters
reasoning_model="anthropic/claude-3.5-sonnet",
use_vision=True,
) as fb:
session.execute(type="click", selector="#signup")
```
### Vault and Persona
Provide credentials to the agent:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
vault = client.Vault(vault_id="vault_123")
with client.Session() as session:
with client.AgentFallback(
session,
task="Login and navigate to settings",
vault_id=vault.vault_id,
) as fb:
# Try logging in with deterministic actions
session.execute(type="fill", selector="#email", value="user@example.com")
session.execute(type="fill", selector="#password", value="password123")
session.execute(type="click", selector="#login")
# If login flow changed, agent uses vault credentials
```
## Fallback Properties
Access information about the fallback execution:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
with client.AgentFallback(session, task="Complete task") as fb:
# Execute actions
session.execute(type="click", selector="#button")
# Check what happened
print(f"All succeeded: {fb.success}")
print(f"Agent was invoked: {fb.agent_invoked}")
if fb.agent_response:
print(f"Agent result: {fb.agent_response}")
```
### Success
Whether the task was completed successfully:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
with client.AgentFallback(session, task="Task") as fb:
session.execute(type="click", selector="#button")
if fb.success:
print("Task completed successfully!")
else:
print("Task failed even after agent intervention")
```
### Agent Response
Details from the agent if it was invoked:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
with client.AgentFallback(session, task="Extract data") as fb:
session.execute(type="click", selector="#button")
if fb.agent_invoked and fb.agent_response:
print(f"Agent answer: {fb.agent_response.answer}")
print(f"Agent steps: {len(fb.agent_response.steps)}")
```
Access detailed information about each execution attempt:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
with client.AgentFallback(session, task="Task") as fb:
session.execute(type="click", selector="#btn1")
session.execute(type="click", selector="#btn2") # Fails
for step in fb.steps:
print(f"Action: {step.action}") # The action type and parameters
print(f"Success: {step.success}") # Whether this step succeeded
if not step.success:
print(f"Error: {step.message}") # Error message if failed
```
This is useful for debugging which specific action triggered the agent fallback.
## Best Practices
### 1. Use for Brittle Workflows
Ideal for pages that change frequently:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
# Good use case - page layout changes often
with client.AgentFallback(session, task="Click pricing link") as fb:
session.execute(type="click", selector="a[href='/pricing']")
```
### 2. Be Specific in Tasks
Clear tasks help the agent understand what to do:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
# Good - specific task
with client.AgentFallback(session, task="Add the blue XL t-shirt to cart") as fb:
session.execute(type="click", selector="#add-to-cart")
# Less clear - vague task
with client.AgentFallback(session, task="Do something") as fb:
session.execute(type="click", selector="#button")
```
### 3. Try Fast Path First
Put cheap, fast actions inside the fallback:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
with client.AgentFallback(session, task="Navigate to dashboard") as fb:
# Fast path - direct click
session.execute(type="click", selector="a[href='/dashboard']")
# Agent only invoked if fast path fails
```
### 4. Don't Use for Complex Logic
Fallback is for single-goal recovery, not complex workflows:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
# Bad - too complex for fallback
with client.AgentFallback(session, task="Complete entire checkout process") as fb:
session.execute(type="click", selector="#cart")
session.execute(type="click", selector="#checkout")
session.execute(type="fill", selector="#address", value="123 Main St")
# ... many more steps
# Better - break into smaller fallbacks
with client.AgentFallback(session, task="Click cart") as fb:
session.execute(type="click", selector="#cart")
with client.AgentFallback(session, task="Proceed to checkout") as fb:
session.execute(type="click", selector="#checkout")
```
### 5. Monitor Fallback Rate
Track how often agents are invoked:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
fallback_invoked_count = 0
total_runs = 0
for _ in range(100):
with client.Session() as session:
with client.AgentFallback(session, task="Task") as fb:
session.execute(type="click", selector="#button")
total_runs += 1
if fb.agent_invoked:
fallback_invoked_count += 1
fallback_rate = fallback_invoked_count / total_runs
print(f"Agent fallback rate: {fallback_rate:.1%}")
# If rate is high, consider:
# - Updating selectors
# - Using agents directly
# - Improving page stability
```
## Limitations
### Not Supported
Agent Fallback does not support:
* `session.scrape()` calls
* `raise_on_failure=True` on actions
* Multiple nested fallbacks
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
# This will raise an error
with client.AgentFallback(session, task="Task") as fb:
data = session.scrape() # Not allowed
# This will raise an error
with client.AgentFallback(session, task="Task") as fb:
session.execute(type="click", selector="#btn", raise_on_failure=True) # Not allowed
```
### When Not to Use
Don't use Agent Fallback for:
* Tasks that always fail (fix the script instead)
* Complex multi-step workflows (use full agent)
* Scraping/data extraction (use session.scrape or agents)
* When you need structured output (use agent with response\_format)
## Error Handling
Handle failures gracefully:
```python error_handling.py theme={null}
def alert_failure(message: str) -> None:
logger.error(message)
try:
with client.Session() as session:
with client.AgentFallback(session, task="Critical task") as fb:
session.execute(type="click", selector="#button")
if not fb.success:
# Even agent couldn't complete the task
alert_failure(f"Task failed: {fb.steps[-1].message}")
```
## Next Steps
Understand agent execution modes
Configure agent parameters
Learn about session actions
Build reliable automations
# Agent Lifecycle
Source: https://docs.notte.cc/features/agents/lifecycle
Understand agent execution modes, states, and control flow
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Agents support multiple execution patterns - from simple blocking calls to advanced asynchronous monitoring. Choose the right pattern for your use case.
## Execution Modes
### Run (Blocking)
The simplest way to execute an agent - start and wait for completion:
```python run_blocking.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session, max_steps=10)
result = agent.run(task="Go to example.com and find the contact email")
if result.success:
print(result.answer)
else:
print(f"Failed: {result.answer}")
```
**When to use:**
* Simple scripts
* Synchronous workflows
* You don't need to do other work while the agent runs
***
### Start + Wait (Non-blocking)
Start the agent and wait for completion separately:
```python start_wait.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
# Start agent (returns immediately)
agent.start(task="Complete this task")
# Do other work here...
# Wait for completion
result = agent.wait()
```
**When to use:**
* You need to start multiple agents in parallel
* You want to do other work while the agent runs
* You need more control over execution
***
### Async Execution
Run agents asynchronously with `async`/`await`:
```python async_agent.py theme={null}
import asyncio
from notte_sdk import NotteClient
client = NotteClient()
async def run_agent_task():
with client.Session() as session:
agent = client.Agent(session=session)
agent.start(task="Extract data from the page")
result = await agent.async_watch_logs_and_wait()
return result
# Run async
result = asyncio.run(run_agent_task())
print(result.answer)
```
**When to use:**
* Building async applications
* Running multiple agents concurrently
* Integrating with async frameworks (FastAPI, aiohttp)
## Agent States
Agents transition through these states during execution:
```mermaid theme={null}
graph LR
A[Created] --> B[Running]
B --> C{Max Steps?}
C -->|No| D{Task Complete?}
C -->|Yes| E[Stopped: Max Steps]
D -->|No| F{Error?}
D -->|Yes| G[Completed: Success]
F -->|Yes| H[Failed: Error]
F -->|No| B
```
### Running
Agent is actively executing:
```python state_running.py theme={null}
agent = client.Agent(session=session)
agent.start(task="Complete task")
# Agent state: Running
```
### Completed
Agent successfully finished the task:
```python state_completed.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.wait()
if result.success:
# Agent state: Completed
print(result.answer)
```
### Failed
Agent encountered an error:
```python state_failed.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.wait()
if not result.success:
# Agent state: Failed
print(f"Error: {result.answer}")
```
### Stopped (Max Steps)
Agent reached maximum step limit:
```python state_max_steps.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session, max_steps=5)
result = agent.run(task="Very complex task")
if len(result.steps) >= 5:
# Agent hit max_steps limit
print("Agent stopped: maximum steps reached")
```
## Monitoring Progress
### Status Checking
Check agent progress at any time:
```python status_checking.py theme={null}
agent = client.Agent(session=session)
agent.start(task="Long running task")
# Check status
status = agent.status()
print(f"Agent ID: {status.agent_id}")
print(f"Current state: {status.status}")
print(f"Steps completed: {len(status.steps)}")
print(f"Success: {status.success}")
```
### Live Log Streaming
Stream agent logs in real-time via WebSocket:
```python live_log_streaming.py theme={null}
def monitor_agent():
with client.Session() as session:
agent = client.Agent(session=session)
agent.start(task="Complete task")
# Stream logs and get final status
status = agent.watch_logs(log=True)
if status is None:
status = agent.status()
return status
```
### Polling Pattern
Check status periodically:
```python polling_pattern.py theme={null}
import time
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
agent.start(task="Long task")
while True:
status = agent.status()
if status.status == "closed":
break
print(f"Progress: {len(status.steps)} steps completed")
time.sleep(5) # Check every 5 seconds
print(f"Final result: {status.answer}")
```
## Parallel Execution
### Multiple Independent Agents
Run multiple agents simultaneously:
```python parallel_agents.py theme={null}
import asyncio
from notte_sdk import NotteClient
client = NotteClient()
async def run_multiple_agents():
async def run_one(task_description: str):
with client.Session() as session:
agent = client.Agent(session=session)
agent.start(task=task_description)
return await agent.async_watch_logs_and_wait()
# Run all agents in parallel (each with its own session)
results = await asyncio.gather(*[run_one(t) for t in ["Task 1", "Task 2", "Task 3"]])
return results
results = asyncio.run(run_multiple_agents())
for i, result in enumerate(results):
print(f"Agent {i + 1}: {result.answer}")
```
## Stopping Agents
### Manual Stop
Stop a running agent:
```python manual_stop.py theme={null}
agent = client.Agent(session=session)
agent.start(task="Long task")
# Do something...
# Stop the agent
agent.stop()
```
**Note:** You cannot stop agents once they complete a step - they must finish the current action.
### Timeout Pattern
Implement custom timeouts:
```python timeout_pattern.py theme={null}
import asyncio
from notte_sdk import NotteClient
async def run_with_timeout(agent, timeout_seconds=60):
try:
async with asyncio.timeout(timeout_seconds):
agent.start(task="Complete task")
result = await agent.async_watch_logs_and_wait()
return result
except TimeoutError as e:
# agent.stop() is already called internally by async_watch_logs_and_wait on cancellation
raise TimeoutError(f"Agent exceeded {timeout_seconds}s timeout") from e
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
# Run with 60 second timeout
result = asyncio.run(run_with_timeout(agent, timeout_seconds=60))
```
## Response Structure
Agent responses contain execution details:
```python response_structure.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(task="Extract data")
# Access result properties
print(result.success) # bool: Did agent succeed?
print(result.answer) # str: Agent's response
print(result.steps) # list: All steps taken
print(result.agent_id) # str: Unique agent ID
print(result.session_id) # str: Session used
```
### Step Details
Inspect individual steps:
```python step_details.py theme={null}
agent = client.Agent(session=session)
result = agent.run(task="Navigate and extract")
for i, step in enumerate(result.steps):
print(f"Step {i + 1}:")
print(f" Action: {step['action']}")
print(f" Success: {step['success']}")
print(f" Message: {step['message']}")
```
## Error Handling
### Graceful Degradation
Handle failures gracefully:
```python graceful_degradation.py theme={null}
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(task="Complete task")
if result.success:
# Process successful result
print(result.answer)
else:
# Handle failure
logger.error(f"Agent failed: {result.answer}")
# Fallback strategy
```
### Retry Pattern
Retry failed agents:
```python agent_retry.py theme={null}
import time
from notte_sdk import NotteClient
client = NotteClient()
MAX_RETRIES = 3
for attempt in range(MAX_RETRIES):
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(task="Complete task")
if result.success:
print(f"Success: {result.answer}")
break
print(f"Attempt {attempt + 1} failed, retrying...")
time.sleep(2**attempt) # Exponential backoff
else:
raise RuntimeError("Agent failed after all retries")
```
### Agent Fallback
Use `AgentFallback` for automatic error recovery:
```python agent_fallback_example.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
with client.AgentFallback(session, task="Add item to cart") as agent_fb:
# Try deterministic actions first
session.execute(type="click", selector="#add-to-cart")
session.execute(type="click", selector="#checkout")
# Agent automatically handles any failures
if agent_fb.success:
print("Task completed (possibly with agent help)")
```
See [Agent Fallback](/features/agents/fallback) for details.
## Best Practices
### 1. Use Appropriate Execution Mode
```python bp_execution_mode.py theme={null}
import asyncio
from notte_sdk import NotteClient
client = NotteClient()
async def main():
with client.Session() as session:
agent = client.Agent(session=session)
# Simple tasks: Use run()
result = agent.run(task="Quick task")
# Multiple agents: Use async (each with its own session)
async def run_one(task: str):
with client.Session() as s:
a = client.Agent(session=s)
a.start(task=task)
return await a.async_watch_logs_and_wait()
results = await asyncio.gather(run_one("Task 1"), run_one("Task 2"))
# Long tasks with monitoring: Use start() + polling
agent.start(task="Long task")
done = False
while not done:
status = agent.status()
# Update UI, log progress, etc.
done = True # placeholder
asyncio.run(main())
```
### 2. Always Check Success
```python bp_check_success.py theme={null}
agent = client.Agent(session=session)
result = agent.run(task="Critical task")
if not result.success:
# Don't proceed if agent failed
raise RuntimeError(f"Critical task failed: {result.answer}")
# Safe to proceed with result
print(result.answer)
```
### 3. Set Appropriate Step Limits
```python bp_step_limits.py theme={null}
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
)
```
### 4. Clean Up Resources
```python bp_cleanup.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Use context managers for automatic cleanup
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(task="Task")
# Session automatically closed
```
## Next Steps
Configure agent parameters
Automatic error recovery
Debug with visual replays
# Replay & Debugging
Source: https://docs.notte.cc/features/agents/replay
Debug agents with visual replays and step-by-step inspection
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Debug agent executions with MP4 replays that show exactly what the agent saw and did during its run.
## Agent Replay
Get a visual replay of the agent's execution. The `session.replay()` method returns a
`ReplayResponse` with **`mp4_url`** — a presigned URL for the MP4 — which you can
pass around or download with `replay.download()`:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(task="Navigate and extract data")
# Get MP4 replay (returns presigned URL)
replay = session.replay()
print(replay.mp4_url) # Presigned URL for MP4 download
# Download to file
replay.download("agent_run.mp4")
```
## What's Included
Agent replays capture:
* **Visual recording** of every page the agent visited
* **Actions taken** by the agent (clicks, fills, navigations)
* **Page transitions** and loading states
* **Element highlights** showing what the agent interacted with
* **Timestamps** for each action
## Viewing Replays
### In Jupyter Notebook
Display the replay inline:
```python view_in_notebook.py theme={null}
with client.Session() as session:
agent = client.Agent(session=session)
agent.run(task="Complete task")
replay = session.replay()
replay.download("notebook_replay.mp4")
```
### Save to File
Save for later viewing or sharing:
```python save_to_file.py theme={null}
with client.Session() as session:
agent = client.Agent(session=session)
agent.run(task="Complete task")
replay = session.replay()
replay.download("debug_run.mp4")
# With custom path
output_dir = Path("./replays")
output_dir.mkdir(exist_ok=True)
replay.download(output_dir / f"agent_{agent.agent_id}.mp4")
```
### In Browser
Use the Notte Console to view replays:
```python view_in_browser.py theme={null}
result = agent.run(task="Complete task")
# Get replay URL
print(f"View replay: https://console.notte.cc/sessions/{session.session_id}")
```
## Debugging Workflow
### 1. Run Agent
Execute your agent task:
```python run_agent.py theme={null}
agent = client.Agent(session=session, max_steps=15)
result = agent.run(task="Find and click the pricing button")
```
### 2. Check If Failed
Identify failures:
```python check_if_failed.py theme={null}
agent = client.Agent(session=session)
result = agent.run(task="Complete task")
if not result.success:
print(f"Agent failed: {result.answer}")
print(f"Completed {len(result.steps)} steps")
```
### 3. Inspect Steps
Review what the agent did:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(task="Complete task")
for i, step in enumerate(result.steps):
print(f"Step {i + 1}: {step['action']}")
print(f" Success: {step['success']}")
if not step["success"]:
print(f" Error: {step['message']}")
```
### 4. Watch Replay
See the visual execution:
```python watch_replay.py theme={null}
with client.Session() as session:
agent = client.Agent(session=session)
agent.run(task="Complete task")
replay = session.replay()
replay.download("debug_replay.mp4")
# Watch where it failed
# Identify if element selectors were wrong
# Check if page loaded correctly
```
### 5. Fix and Retry
Adjust based on findings:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
# Maybe increase max_steps
agent = client.Agent(session=session, max_steps=25)
# Or adjust the task
result = agent.run(task="Click the 'View Pricing' button in the main navigation")
```
## Common Issues
### Agent Can't Find Element
**Symptoms:**
* Agent fails with "Element not found"
* Replay shows element exists but wasn't clicked
**Debug:**
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(task="Complete task")
replay = session.replay()
replay.download("missing_element.mp4")
# Watch replay and check:
# - Did page finish loading?
# - Is element visible/in viewport?
# - Is element covered by another element?
```
**Fix:**
```python fix_missing_element.py theme={null}
agent = client.Agent(session=session)
# Be more specific in task
task = "Wait for the page to load, then click the blue 'Submit' button at the bottom"
# Or use session actions first
session.execute(type="goto", url="https://example.com")
time.sleep(2) # Wait for load
result = agent.run(task="Click submit button")
```
### Agent Takes Wrong Action
**Symptoms:**
* Agent clicks wrong button
* Agent fills wrong form field
**Debug:**
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(task="Fill the email field")
# Check what agent saw
for step in result.steps:
print(f"Action: {step['action']}")
print(f"Reasoning: {step.get('reasoning', 'N/A')}")
```
**Fix:**
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
# Be more specific
task = "Fill the email input field in the signup form with user@example.com"
# Or disable vision if causing confusion
agent = client.Agent(session=session, use_vision=False)
```
### Agent Exceeds Max Steps
**Symptoms:**
* Agent stops before completing task
* `len(result.steps) == max_steps`
**Debug:**
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(task="Complete task")
print(f"Steps taken: {len(result.steps)}")
print(f"Max steps: {agent.request.max_steps}")
replay = session.replay()
replay.download("debug_replay.mp4") # See where it got stuck
```
**Fix:**
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
# Increase max_steps
agent = client.Agent(session=session, max_steps=30)
# Or break task into smaller steps
result1 = agent.run(task="Navigate to products page")
result2 = agent.run(task="Search for laptops")
```
## Advanced Debugging
### Step-by-Step Analysis
Inspect each step in detail:
```python step_by_step_analysis.py theme={null}
result = agent.run(task="Complex task")
for i, step in enumerate(result.steps):
print(f"\n=== Step {i + 1} ===")
print(f"Action: {step.get('action')}")
print(f"Success: {step.get('success')}")
print(f"Page URL: {step.get('url')}")
print(f"Message: {step.get('message')}")
```
### Comparing Runs
Compare successful vs failed runs:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Successful run
with client.Session() as session_1:
agent_1 = client.Agent(session=session_1)
result_success = agent_1.run(task="Working task")
replay_success = session_1.replay()
replay_success.download("success.mp4")
# Failed run
with client.Session() as session_2:
agent_2 = client.Agent(session=session_2)
result_fail = agent_2.run(task="Failing task")
replay_fail = session_2.replay()
replay_fail.download("failure.mp4")
# Compare side-by-side
# Identify where behavior diverges
```
### Agent Status During Execution
Monitor agent in real-time:
```python monitor_status.py theme={null}
with client.Session() as session:
agent = client.Agent(session=session)
agent.start(task="Long running task")
while True:
status = agent.status()
if status.status == "closed":
break
print(f"Steps: {len(status.steps)}")
time.sleep(5)
# Get replay after completion
# replay = session.replay()
# replay.download("replay.mp4")
```
## Best Practices
### 1. Always Review Failed Agents
Don't ignore failures - watch the replay:
```python review_failed_agents.py theme={null}
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(task="Critical task")
if not result.success:
replay = session.replay()
replay.download(f"failure_{agent.agent_id}.mp4")
print(f"Saved replay for debugging: failure_{agent.agent_id}.mp4")
```
### 2. Save Replays for Production Issues
Keep replays of production failures:
```python save_production_replays.py theme={null}
result = agent.run(task="Production task")
if not result.success:
replay = session.replay()
replay.download(f"prod_failure_{agent.agent_id}.mp4")
logger.error(f"Agent failed, replay saved: prod_failure_{agent.agent_id}.mp4")
except Exception as e:
logger.error(f"Agent exception: {e}")
```
### 3. Use Replays for QA
Verify agent behavior before deploying:
```python replays_for_qa.py theme={null}
with client.Session() as session:
agent = client.Agent(session=session)
# Test run
result = agent.run(task="Test checkout flow")
# Review replay before production
replay = session.replay()
replay.download("qa_replay.mp4")
# Verify:
# - All steps completed correctly
# - No unexpected behavior
# - Performance is acceptable
```
### 4. Share Replays with Team
Save and share for collaboration:
```python share_with_team.py theme={null}
with client.Session() as session:
agent = client.Agent(session=session)
agent.run(task="Feature test")
replay = session.replay()
replay.download(f"feature_test_{agent.agent_id}.mp4")
# Share file with team
# Or share console link
print(f"Console replay: https://console.notte.cc/sessions/{session.session_id}")
```
## Limitations
Replays are currently:
* ✅ Available for all completed agents
* ✅ Full video recording of execution
* ✅ Include element highlights
* ⚠️ Generated after completion (not real-time)
* ⚠️ May be large files for long runs
## Next Steps
Understand agent execution
Optimize agent settings
Build reliable agents
Watch sessions in real-time
# Structured Output
Source: https://docs.notte.cc/features/agents/structured-output
Get type-safe, structured responses from agents using Pydantic models
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Agents can return structured data in a specific format using Pydantic models, ensuring type safety and validation.
## Overview
By default, agents return unstructured text answers:
```python overview_default.py theme={null}
result = agent.run(task="Find the contact email")
print(result.answer) # "contact@example.com"
```
With structured output, define the exact format you want:
```python overview_structured.py theme={null}
agent = client.Agent(session=session)
result = agent.run(task="Find contact info", response_format=ContactInfo)
if result.success and result.answer:
contact = ContactInfo.model_validate_json(result.answer)
print(contact.email) # Type-safe access
```
## Basic Example
Define a Pydantic model and pass it to `response_format`:
```python theme={null}
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,
)
# Parse and access
if result.success and result.answer:
product = Product.model_validate_json(result.answer)
print(f"{product.name}: ${product.price}")
if product.in_stock:
print("Available!")
```
## Complex Models
### Nested Structures
Models can contain nested objects:
```python nested_structures.py theme={null}
agent = client.Agent(session=session)
result = agent.run(task="Extract company information", response_format=Company)
if result.success and result.answer:
company = Company.model_validate_json(result.answer)
print(company.name)
print(company.address.city)
```
### Lists of Objects
Extract multiple items:
```python lists_of_objects.py theme={null}
from notte_sdk import NotteClient
from pydantic import BaseModel
class Review(BaseModel):
author: str
rating: int
comment: str
class ReviewList(BaseModel):
reviews: list[Review]
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(
task="Extract all product reviews",
response_format=ReviewList,
)
# Iterate over reviews
if result.success and result.answer:
data = ReviewList.model_validate_json(result.answer)
for review in data.reviews:
print(f"{review.author}: {review.rating}/5")
print(review.comment)
```
### Optional Fields
Use `None` for optional fields:
```python theme={null}
from pydantic import BaseModel
class Article(BaseModel):
title: str
author: str | None # May not always be present
date: str | None
content: str
```
## Use Cases
### E-commerce Data Extraction
Extract structured product data:
```python ecommerce_extraction.py theme={null}
class ProductListing(BaseModel):
name: str
price: float
original_price: float | None
rating: float
review_count: int
availability: str
seller: str
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(
task="Extract product listing information",
url="https://store.example.com/products/laptop",
response_format=ProductListing,
)
```
### Lead Generation
Extract structured contact information:
```python lead_generation.py theme={null}
class BusinessLead(BaseModel):
company_name: str
contact_email: str | None
phone: str | None
website: str
industry: str
employee_count: str | None
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(
task="Extract business information from this company page",
url="https://example.com/about",
response_format=BusinessLead,
)
```
### Job Listings
Extract job posting details:
```python job_listings.py theme={null}
class JobPosting(BaseModel):
title: str
company: str
location: str
salary_range: str | None
job_type: str # "Full-time", "Part-time", etc.
posted_date: str
requirements: list[str]
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(
task="Extract job posting information",
response_format=JobPosting,
```
### Social Media Data
Extract social media profiles:
```python social_media.py theme={null}
username: str
display_name: str
bio: str | None
follower_count: int
following_count: int
post_count: int
verified: bool
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(
task="Extract social media profile information",
response_format=SocialProfile,
```
## Field Validation
Use Pydantic validators for data quality:
```python field_validation.py theme={null}
class Product(BaseModel):
name: str = Field(min_length=1)
price: float = Field(gt=0) # Must be positive
rating: float = Field(ge=0, le=5) # 0-5 range
@field_validator("price")
@classmethod
def validate_price(cls, v: float) -> float:
if v > 10000:
raise ValueError("Price seems unreasonably high")
return v
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(
task="Extract product",
response_format=Product,
```
## Best Practices
### 1. Be Specific in Task Description
Match your task to the response format:
```python bp_specific_task.py theme={null}
result = agent.run(
task="Extract the product name, price, and stock status",
response_format=Product,
)
# Less clear - agent might not fill all fields
result = agent.run(
task="Tell me about this product",
response_format=Product,
)
```
### 2. Use Appropriate Types
Choose Python types that match the data:
```python theme={null}
from datetime import date
from pydantic import BaseModel
class Event(BaseModel):
title: str
date: date # Will be parsed as date
price: float # Not str
attendee_count: int # Not float
```
### 3. Make Optional Fields Explicit
Don't assume data will always be present:
```python theme={null}
from pydantic import BaseModel
class Product(BaseModel):
name: str # Always required
price: float # Always required
discount: float | None = None # Might not exist
rating: float | None = None # Might not exist
```
### 4. Use Field Descriptions
Help the agent understand what you want:
```python theme={null}
from pydantic import BaseModel, Field
class Product(BaseModel):
name: str = Field(description="Product title/name")
price: float = Field(description="Current selling price in USD")
original_price: float | None = Field(description="Original price before discount, if any")
```
### 5. Start Simple, Then Expand
Begin with basic models:
```python theme={null}
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
```
## Error Handling
Handle validation errors:
```python error_handling.py theme={null}
try:
result = agent.run(
task="Extract product data",
response_format=Product,
)
product = result.answer
except ValidationError as e:
print(f"Agent returned invalid data: {e}")
```
## Limitations
### Not Suitable For
Structured output works best for data extraction, not for:
* Open-ended creative tasks
* Tasks requiring explanation or reasoning
* When you want natural language responses
```python limitations_not_suitable.py theme={null}
with client.Session() as session:
agent = client.Agent(session=session)
# Do this instead
result = agent.run(task="Explain how this product works")
print(result.answer) # Natural language explanation
```
### Complex Relationships
Very complex nested structures may be challenging:
```python limitations_complex.py theme={null}
class Product(BaseModel):
name: str
price: float
# Difficult for agents
class ComplexStructure(BaseModel):
nested: dict[str, list[dict[str, Product]]]
# Better - flatten or simplify
class SimplifiedStructure(BaseModel):
products: list[Product]
categories: list[str]
```
## Next Steps
Configure agent parameters
Understand agent execution modes
Alternative data extraction methods
Data extraction best practices
# Agent to Function Conversion
Source: https://docs.notte.cc/features/agents/workflows
Convert agent executions into reusable function code
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Convert successful agent runs into deterministic function code that can be executed faster and cheaper than agents.
## Overview
After an agent completes a task, you can extract the steps as function code:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
agent = client.Agent(session=session)
result = agent.run(task="Navigate to pricing page and extract plans")
if result.success:
# Convert to function code
function_code = agent.workflow.code()
print(function_code.python_script)
```
## Why Convert to Functions?
| Aspect | Agent | Function |
| ---------------- | ---------------------- | ------------------------- |
| **Execution** | AI decides each step | Predefined steps |
| **Speed** | Slower (LLM reasoning) | Faster (direct execution) |
| **Cost** | Higher (LLM tokens) | Lower (actions only) |
| **Reliability** | Can vary | Deterministic |
| **Adaptability** | Handles changes | Breaks if page changes |
**Use functions when:**
* The task is well-defined and repeatable
* Page structure is stable
* Speed and cost matter
* You need predictable execution
## Getting Function Code
### As Python Script
Get executable Python code:
```python get-python-script.py theme={null}
agent = client.Agent(session=session)
result = agent.run(task="Login and navigate to dashboard")
if result.success:
# Get function code
code = agent.workflow.code(as_workflow=True)
print(code.python_script)
```
Example output:
```python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
# Step 1: Navigate to login page
session.execute(type="goto", url="https://example.com/login")
# Step 2: Fill email field
session.execute(type="fill", selector="input[name='email']", value="user@example.com")
# Step 3: Fill password field
session.execute(type="fill", selector="input[name='password']", value="********")
# Step 4: Click login button
session.execute(type="click", selector="button[type='submit']")
# Step 5: Wait for dashboard
session.execute(type="goto", url="https://example.com/dashboard")
```
### As Function Object
Create a reusable function:
```python create-function-object.py theme={null}
result = agent.run(task="Extract product data")
if result.success:
# Create function from agent
function = agent.workflow.create_function()
print(f"Created function: {function.function_id}")
# Run function later
function_result = function.run()
```
## Running Functions
### Execute Generated Code
Review the generated Python before running it:
Generated workflows contain LLM-produced code and should be treated as untrusted. Inspect the entire file, then run
it only in an isolated environment with the minimum required permissions.
```python theme={null}
# Generated from agent
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.search")
session.execute(type="fill", selector="input[name='query']", value="laptop")
data = session.scrape(instructions="Extract product names")
print(data)
```
Before testing the saved file:
1. Use a disposable container or virtual machine with no host or home-directory mounts.
2. Provide only short-lived, minimum-scope credentials; generated code can read and transmit every value you expose.
3. Restrict network access to the destinations the workflow requires, when possible.
4. Destroy the environment and revoke its credentials after the test.
### Use Function API
Run via the function endpoint:
```python use-function-api.py theme={null}
agent.run(task="Complete task")
# Create function from successful agent
function = agent.workflow.create_function()
# Run multiple times
for query in ["laptop", "phone", "tablet"]:
```
## Use Cases
### 1. Prototyping with Agents
Use agents to figure out the automation, then convert:
```python prototyping-with-agents.py theme={null}
# Phase 1: Prototype with agent
agent = client.Agent(session=session)
result = agent.run(task="Find all products under $100")
if result.success:
# Phase 2: Convert to function for production
code = agent.workflow.code()
# Save for production use
with open("production_function.py", "w") as f:
f.write(code.python_script)
```
### 2. Scheduled Tasks
Convert one-time agent runs to scheduled functions:
```python scheduled-tasks.py theme={null}
agent = client.Agent(session=session)
result = agent.run(task="Extract daily price changes")
# Convert to function
function = agent.workflow.create_function()
# Schedule to run daily (via API or console)
# function.schedule(cron="0 9 * * *")
```
### 3. Cost Optimization
Run agents once, then use cheaper functions:
```python cost-optimization.py theme={null}
agent = client.Agent(session=session)
result = agent.run(task="Complex data extraction")
# Recurring: Use function ($0.05 per run)
function = agent.workflow.create_function()
# Run 100 times - save $15 vs running agent each time
for i in range(100):
function.run()
```
### 4. Testing Variations
Create function templates from agents:
```python testing-variations.py theme={null}
# Base workflow from agent
agent = client.Agent(session=session)
result = agent.run(task="Search and extract results")
code = agent.workflow.code()
# Modify code for variations
# - Different search queries
# - Different extraction logic
# - Different URLs
```
## Customizing Generated Code
### Add Parameters
Make functions reusable with parameters:
```python add-parameters.py theme={null}
# Agent-generated base code
code = agent.workflow.code()
# Customize with parameters
customized_code = f"""
def extract_products(search_query: str, max_results: int = 10):
{code.python_script}
"""
```
### Add Error Handling
Enhance with production-ready error handling:
```python add-error-handling.py theme={null}
# Agent-generated code
base_code = agent.workflow.code()
enhanced_code = f"""
from notte_sdk import NotteClient
from loguru import logger
def run_function():
client = NotteClient()
try:
with client.Session() as session:
{base_code.python_script}
return {{"success": True, "data": result}}
except Exception as e:
logger.error(f"Function failed: {{e}}")
```
### Optimize Selectors
Review and improve generated selectors:
```python optimize-selectors.py theme={null}
# Generated code might use:
session.execute(type="click", selector="div.container > button:nth-child(3)")
# Optimize to:
session.execute(type="click", selector="button[data-testid='submit']")
```
## Best Practices
### 1. Test Generated Functions
Always test before production:
```python test-generated-functions.py theme={null}
agent.run(task="Complete task")
# Generate function code
code = agent.workflow.code()
# Save for review before isolated execution
with open("generated_function.py", "w", encoding="utf-8") as generated_file:
generated_file.write(code.python_script)
print("Saved generated_function.py. Review it, then run it in a disposable container or virtual machine.")
```
### 2. Document the Source
Track which agent generated the function:
```python document-the-source.py theme={null}
result = agent.run(task="Extract product data")
function = agent.workflow.create_function()
# Add metadata
metadata = {
"agent_id": agent.agent_id,
"original_task": "Extract product data",
"created_at": datetime.now().isoformat(),
"success_rate": result.success,
}
```
### 3. Version Control
Store functions in git:
```python version-control.py theme={null}
agent = client.Agent(session=session)
agent.run(task="Extract products")
# Save function code
code = agent.workflow.code()
function_path = Path("functions/extract_products.py")
function_path.parent.mkdir(exist_ok=True)
```
### 4. Monitor Function Success
Track if functions continue to work:
```python theme={null}
from datetime import datetime
def run_monitored_function():
try:
function = client.Function(function_id="func_abc123")
result = function.run()
if result.status == "closed":
log_success(datetime.now())
else:
alert_failure(result.result)
except Exception as e:
# Function broken - maybe page changed?
# Time to re-run agent and regenerate
alert_function_broken(e)
```
### 5. Regenerate When Pages Change
When functions break, use agents to update:
```python regenerate-when-pages-change.py theme={null}
# Old function failing
try:
old_function.run()
except Exception:
print("Function broken, regenerating...")
with client.Session() as session:
# Use agent to figure out new function
agent = client.Agent(session=session)
result = agent.run(task=original_task_description)
if result.success:
# Generate new function
```
## Limitations
Functions work best for:
* ✅ Stable, unchanging pages
* ✅ Deterministic tasks
* ✅ Known sequences of actions
Functions are not suitable for:
* ❌ Pages that change frequently
* ❌ Tasks requiring adaptation
* ❌ Complex decision-making
When pages change or tasks become complex, revert to agents.
## Next Steps
Deploy automations as serverless APIs
Available session actions
Optimize agent runs
Deploy and manage serverless functions
# Creating Functions
Source: https://docs.notte.cc/features/functions/creating
Write and deploy browser automation Functions
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
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:
```python hello_function.py theme={null}
def run():
"""A simple function that returns a greeting."""
return "Hello from Notte Functions!"
```
### Function with Parameters
Accept input parameters:
```python greet_function.py theme={null}
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:
```python scraper_function.py theme={null}
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:
```python deploy_sdk.py theme={null}
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
```python deployment_options.py theme={null}
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:**
* `workflow_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 function is publicly accessible
## Function Requirements
### The Handler
Must have a `run()` function:
```python handler_examples.py theme={null}
# Correct
def run(param1, param2):
return "result"
# Wrong - different name
def execute(param1, param2):
return "result"
# Wrong - no function
result = perform_task()
```
### Dependencies
Import Notte SDK and standard libraries:
```python dependencies.py theme={null}
# Built-in imports
# Notte SDK
# Third-party (common libraries available)
def run():
# Your code
pass
```
**Available packages:**
* `notte-sdk` - Notte SDK
* `requests` - HTTP client
* `pydantic` - Data validation
* Standard Python library
* Most common packages
### Return Values
Return JSON-serializable data:
```python return_values.py theme={null}
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
```python parameter_types.py theme={null}
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
Use type hints for automatic validation:
```python type_validation.py theme={null}
def run(count: int):
# count is automatically validated as int
for i in range(count):
print(i)
```
### Complex Types
Use Pydantic for structured parameters:
```python complex_types.py theme={null}
from notte_sdk import NotteClient
from pydantic import BaseModel
class SearchParams(BaseModel):
url: str
query: str
max_results: int = 10
def run(params: SearchParams):
# params is validated against SearchParams model
client = NotteClient()
# Use params.url, params.query, etc.
```
## Environment Variables
Access secrets securely:
```python environment_variables.py theme={null}
import os
from notte_sdk import NotteClient
def run():
# Access environment variables
api_key = os.getenv("MY_API_KEY")
webhook_url = os.getenv("WEBHOOK_URL")
if not api_key:
return {"error": "API key not configured"}
# Use in automation
client = NotteClient(api_key=api_key)
```
Set environment variables in Console or locally for testing.
## Error Handling
### Graceful Errors
Return error information in results:
```python graceful_errors.py theme={null}
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:
```python raising_exceptions.py theme={null}
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:
```python test_locally.py theme={null}
# 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)
```
### Mock API Calls
Test without deploying:
```python mock_api_calls.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Load existing function with decryption key for local execution
function = client.Function(
function_id="func_abc123",
decryption_key="your-decryption-key", # Required for local execution
)
# Run locally (not on cloud)
result = function.run(local=True, url="https://example.com")
print(result.result)
```
## Best Practices
### 1. Document Parameters
Use clear docstrings:
```python document_params.py theme={null}
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:
```python return_structured.py theme={null}
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:
```python add_logging.py theme={null}
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)} items")
return data
```
### 4. Set Timeouts
Prevent functions from hanging:
```python set_timeouts.py theme={null}
from notte_sdk import NotteClient
def run(url: str):
client = NotteClient()
# Set session timeout
with client.Session(idle_timeout_minutes=5) as session:
session.execute(type="goto", url=url)
data = session.scrape()
return data
```
### 5. Validate Inputs
Check parameters before processing:
```python validate_inputs.py theme={null}
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
```python simple_scraper.py theme={null}
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
```python form_submission.py theme={null}
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
```python structured_extraction.py theme={null}
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
Learn how to call your Functions
Schedule Functions to run automatically
Update and manage Functions
Back to Functions overview
# Function Invocations
Source: https://docs.notte.cc/features/functions/invocations
Call Functions via API, SDK, cURL, or webhooks
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Functions can be invoked in multiple ways - through the Python SDK, HTTP API, cURL commands, or as webhook endpoints.
## Via Python SDK
The simplest way to call a Function:
```python invoke_function.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Get function by ID
function = client.Function(function_id="func_abc123")
# Run function with parameters
result = function.run(url="https://example.com", search_query="laptop")
print(result.result) # Access the return value
print(result.status) # "closed" or "failed"
print(result.session_id) # Session ID if created
```
### Run Parameters
```python run_parameters.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="workflow_abc123")
result = function.run(
# Your function parameters (passed as variables)
url="https://example.com",
query="search term",
# Execution options
stream=True, # Stream logs in real-time (default: True)
timeout=300, # Timeout in seconds (default: 300)
raise_on_failure=True, # Raise exception on failure (default: True)
local=False, # Run locally vs cloud (default: False)
)
```
### Handling Results
```python handling_results.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="workflow_abc123")
result = function.run(url="https://example.com")
# Check status
if result.status == "closed":
print("Success!")
print(result.result) # Function return value
elif result.status == "failed":
print("Function failed")
print(result.result) # Error message
# Access metadata
print(f"Workflow ID: {result.workflow_id}")
print(f"Run ID: {result.workflow_run_id}")
print(f"Session ID: {result.session_id}")
```
## Via HTTP API
Call Functions as HTTP endpoints:
### POST Request
```http HTTP theme={null}
POST https://api.notte.cc/functions/{function_id}/runs/start
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"function_id": "function_abc123",
"variables": {
"url": "https://example.com",
"query": "laptop"
},
"stream": true
}
```
### Response
```json JSON theme={null}
{
"function_id": "function_abc123",
"function_run_id": "run_xyz789",
"session_id": "session_456",
"result": {
"data": ["result1", "result2"],
"count": 2
},
"status": "closed"
}
```
## Via cURL
### Basic cURL Request
```bash cURL theme={null}
curl -X POST https://api.notte.cc/functions/function_abc123/runs/start \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"function_id": "function_abc123",
"variables": {
"url": "https://example.com",
"search_query": "laptop"
}
}'
```
### Generate cURL Command
Get the exact cURL command for your Function:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="func_abc123")
# Generate cURL command
curl_command = function.get_curl(
url="https://example.com",
search_query="laptop"
)
print(curl_command)
```
Output:
```bash Output theme={null}
curl --location 'https://api.notte.cc/functions/function_abc123/runs/start' \
--header 'x-notte-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
"function_id": "function_abc123",
"variables": {
"url": "https://example.com",
"search_query": "laptop"
}
}'
```
## Via JavaScript/Node.js
Call from JavaScript applications:
```javascript JavaScript theme={null}
// Using fetch
const response = await fetch(
'https://api.notte.cc/functions/function_abc123/runs/start',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
function_id: 'function_abc123',
variables: {
url: 'https://example.com',
search_query: 'laptop'
}
})
}
);
const result = await response.json();
console.log(result);
```
### With Axios
```javascript JavaScript theme={null}
const axios = require('axios');
const result = await axios.post(
'https://api.notte.cc/functions/function_abc123/runs/start',
{
function_id: 'function_abc123',
variables: {
url: 'https://example.com',
search_query: 'laptop'
}
},
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
}
);
console.log(result.data);
```
## Streaming Logs
Watch function execution in real-time:
### Via SDK
```python stream_sdk.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="workflow_abc123")
# Stream logs while running
result = function.run(
url="https://example.com",
stream=True, # Logs printed to console
)
```
### Via HTTP (Server-Sent Events)
```bash cURL theme={null}
curl -X POST https://api.notte.cc/functions/function_abc123/runs/start \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"function_id": "function_abc123",
"variables": {"url": "https://example.com"},
"stream": true
}' \
--no-buffer
```
Response streams:
```text Output theme={null}
data: {"type": "log", "message": "Starting function..."}
data: {"type": "log", "message": "Session created"}
data: {"type": "log", "message": "Navigation complete"}
data: {"type": "result", "message": "{\"function_id\": \"...\", ...}"}
```
## Async Invocation
### Create and Start Separately
For long-running functions:
```python async_create_start.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Create a run (returns immediately)
run_response = client.functions.create_run("function_abc123", local=False)
run_id = run_response.workflow_run_id
print(f"Run created: {run_id}")
# Start the run
client.functions.run(run_id, function_id="function_abc123", variables={"url": "https://example.com"})
```
### Check Run Status
```python check_run_status.py theme={null}
# Check run status
run_status = client.functions.get_run("function_abc123", run_id)
print(f"Status: {run_status.status}") # "active", "closed", "failed"
print(f"Result: {run_status.result}")
```
### Stop a Running Function
```python stop_running.py theme={null}
# Stop a long-running function
client.functions.stop_run("function_abc123", run_id)
```
## Webhook Integration
### As Webhook Endpoint
Use Functions as webhook receivers:
```python webhook_handler.py theme={null}
def run(event_type: str, data: dict):
"""Handle webhook events."""
if event_type == "order.created":
# Process new order
process_order(data)
elif event_type == "user.signup":
# Welcome new user
send_welcome_email(data)
return {"status": "processed", "event": event_type}
```
Configure webhook in external service:
```
Webhook URL: https://api.notte.cc/functions/function_abc123/runs/start
Method: POST
Headers: Authorization: Bearer YOUR_API_KEY
```
### Testing Webhooks
Test webhook locally:
```bash cURL theme={null}
curl -X POST https://api.notte.cc/functions/function_abc123/runs/start \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"function_id": "function_abc123",
"variables": {
"event_type": "order.created",
"data": {"order_id": "123", "amount": 99.99}
}
}'
```
## Error Handling
### SDK Error Handling
```python sdk_error_handling.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="workflow_abc123")
try:
result = function.run(url="https://example.com")
if result.status == "failed":
print(f"Function failed: {result.result}")
except Exception as e:
print(f"Unexpected error: {e}")
```
### Disable Raise on Failure
```python disable_raise.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="workflow_abc123")
# Don't raise exception on failure
result = function.run(url="https://example.com", raise_on_failure=False)
# Check status manually
if result.status == "failed":
print(f"Function failed: {result.result}")
else:
print(f"Success: {result.result}")
```
### HTTP Error Handling
```python Python theme={null}
import requests
response = requests.post(
"https://api.notte.cc/functions/function_abc123/runs/start",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"function_id": "function_abc123",
"variables": {"url": "https://example.com"}
}
)
if response.status_code == 200:
result = response.json()
print(result)
else:
print(f"Error {response.status_code}: {response.text}")
```
## Batch Invocations
### Run Multiple Functions
```python batch_invocation.py theme={null}
from concurrent.futures import ThreadPoolExecutor
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="func_abc123")
urls = ["https://site1.com", "https://site2.com", "https://site3.com"]
def invoke_function(url):
return function.run(url=url)
# Run in parallel
with ThreadPoolExecutor(max_workers=3) as executor:
results = list(executor.map(invoke_function, urls))
for result in results:
print(result.result)
```
### Sequential Invocations
```python sequential.py theme={null}
results = []
for url in urls:
result = function.run(url=url)
results.append(result.result)
print(results)
```
## Local vs Cloud Execution
### Cloud Execution (Default)
```python cloud_execution.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="workflow_abc123")
# Runs on Notte infrastructure
result = function.run(
url="https://example.com",
local=False, # Default
)
```
**Advantages:**
* Scalable
* No local resources needed
* Built-in logging
* Session replays available
### Local Execution
```python local_execution.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Load function with decryption key for local execution
function = client.Function(
function_id="func_abc123",
decryption_key="your-key", # Required for local execution
)
# Runs on your machine
result = function.run(url="https://example.com", local=True)
```
**Advantages:**
* Debugging
* Development/testing
* No cloud execution costs
**Requirements:**
* Decryption key (from Console) - passed when creating Function instance
* Function code accessible locally
## Rate Limits
### Account Limits
Functions have rate limits based on your plan:
* **Free**: 10 concurrent runs
* **Pro**: 50 concurrent runs
* **Enterprise**: Custom limits
### Handling Rate Limits
```python Python theme={null}
import time
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="workflow_abc123")
def invoke_with_retry(function, **variables):
max_retries = 3
for attempt in range(max_retries):
try:
return function.run(**variables)
except Exception as e:
if "rate limit" in str(e).lower():
wait_time = 2 ** attempt # Exponential backoff
time.sleep(wait_time)
else:
raise
raise RuntimeError("Max retries exceeded")
result = invoke_with_retry(
function,
url="https://example.com"
)
```
## Best Practices
### 1. Use Appropriate Timeout
```python timeout_examples.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="function_abc123")
# Short task
result = function.run(url="https://example.com", timeout=60)
# Long task
result = function.run(url="https://example.com", timeout=600)
```
### 2. Stream Logs for Debugging
```python stream_debug.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="function_abc123")
# Development - stream logs
result = function.run(url="https://example.com", stream=True)
# Production - no streaming
result = function.run(url="https://example.com", stream=False)
```
### 3. Handle Errors Gracefully
```python graceful_errors.py theme={null}
def send_alert(message: str) -> None:
print(message)
try:
```
### 4. Use Variables for Dynamic Data
```python use_variables.py theme={null}
# Good - parameterized
result = function.run(url=dynamic_url, query=user_input)
# Bad - hardcoded
result = function.run() # URL hardcoded in function
```
## Next Steps
Schedule Functions automatically
Update and monitor Functions
Learn to write Functions
Full API documentation
# Function Management
Source: https://docs.notte.cc/features/functions/management
Update, version, monitor, and manage your deployed Functions
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Manage the lifecycle of your Functions including updates, versioning, monitoring executions, and viewing replays.
## Viewing Functions
### List All Functions
View all deployed Functions:
```python list_functions.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# List all functions
functions = client.functions.list()
for func in functions.items:
print(f"ID: {func.workflow_id}")
print(f"Name: {func.name}")
print(f"Version: {func.latest_version}")
print(f"Created: {func.created_at}")
print("---")
```
### Get Function Details
Retrieve specific Function information:
```python get_function_details.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Get function by ID
function = client.Function(function_id="func_abc123")
# Access function properties
print(f"Function ID: {function.function_id}")
print(f"Name: {function.response.name}")
print(f"Description: {function.response.description}")
print(f"Latest Version: {function.response.latest_version}")
print(f"Versions: {function.response.versions}")
```
## Updating Functions
### Update Function Code
Deploy a new version of your Function:
```python update_code.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="func_abc123")
# Update with new code
function.update(path="updated_function.py")
print(f"Updated to version: {function.response.latest_version}")
```
### Update Function Metadata
Change Function name or description:
```python theme={null}
# Update metadata (via console or API)
# Name and description updates are available through the Console
```
**Note:** Function updates create new versions automatically. Previous versions remain accessible for rollback.
## Versioning
### Version Management
Functions automatically version on each update:
```python version_management.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="func_abc123")
# Get all versions
print(f"Available versions: {function.response.versions}")
# Get latest version
print(f"Latest: {function.response.latest_version}")
```
### Run Specific Version
Execute a specific Function version:
```python run_specific_version.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="func_abc123")
# Run latest version (default)
result = function.run(url="https://example.com")
# Run specific version
result = function.run(url="https://example.com", version="v2")
```
### Version History
Track changes across versions:
```python version_history.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
functions = client.functions.list()
for func in functions.items:
print(f"Function: {func.name}")
print(f"Versions: {', '.join(func.versions)}")
print(f"Latest: {func.latest_version}")
```
## Monitoring Executions
### View Run History
List recent Function executions:
```python view_run_history.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Get recent runs
runs = client.functions.list_runs(
function_id="function_abc123",
only_active=False, # Include completed runs
)
for run in runs.items:
print(f"Run ID: {run.workflow_run_id}")
print(f"Status: {run.status}")
print(f"Created: {run.created_at}")
print(f"Updated: {run.updated_at}")
print("---")
```
### Check Run Status
Monitor specific execution:
```python check_run_status.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Get run details
run_status = client.functions.get_run("function_abc123", "run_xyz789")
print(f"Status: {run_status.status}") # "active", "closed", "failed"
print(f"Result: {run_status.result}")
print(f"Session ID: {run_status.session_id}")
```
**Status values:**
* `active` - Function is currently running
* `closed` - Function completed successfully
* `failed` - Function encountered an error
### Filter Active Runs
View only running executions:
```python filter_active_runs.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Get only active runs
active_runs = client.functions.list_runs("function_abc123", only_active=True)
print(f"Active runs: {len(active_runs.items)}")
for run in active_runs.items:
print(f"Run {run.workflow_run_id} - {run.status}")
```
## Viewing Replays
### Access Function Replay
Watch MP4 replay of Function execution:
```python access_replay.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="func_abc123")
# Run the function first
result = function.run(url="https://example.com")
# Get replay for this run (uses the session from the last run)
replay = function.replay()
# Download the replay
replay.download("function_replay.mp4")
```
**Replay features:**
* Video recording of browser session
* Shows all actions taken
* Useful for debugging failures
* Available after running a function
### Replay After Run
Get replay immediately after execution:
```python replay_after_run.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="func_abc123")
# Run function
result = function.run(url="https://example.com")
# Get replay for this run (automatically uses the session from the run)
replay = function.replay()
# Download the video
replay.download("execution_replay.mp4")
```
## Managing Runs
### Stop Running Function
Cancel a long-running execution:
```python stop_running.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Stop specific run
client.functions.stop_run("function_abc123", "run_xyz789")
print("Function execution stopped")
```
### Monitoring Long Runs
Track execution progress:
```python monitor_runs.py theme={null}
import time
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="func_abc123")
# Start run
result = function.run(
url="https://example.com",
stream=False, # Don't stream logs
)
run_id = result.workflow_run_id
# Poll status
while True:
status = client.functions.get_run("func_abc123", run_id)
print(f"Status: {status.status}")
if status.status in ["closed", "failed"]:
print(f"Final result: {status.result}")
break
time.sleep(5) # Check every 5 seconds
```
## Forking Functions
### Fork Shared Function
Create your own copy of a shared Function:
```python fork_function.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Fork a function from marketplace or teammate
original = client.Function(function_id="func_abc123")
forked_function = original.fork()
print(f"Forked function ID: {forked_function.function_id}")
print("Original ID: func_abc123")
```
**Use cases:**
* Customize shared Functions
* Create templates from marketplace
* Copy teammate's Functions
* Experiment without affecting original
### Modify Forked Function
After forking, update as needed:
```python modify_forked.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Fork function
original = client.Function(function_id="shared_function_id")
forked = original.fork()
# Update your copy
forked.update(path="my_modified_version.py")
# Run your version
result = forked.run(url="https://example.com")
```
## Downloading Functions
### Download Function Code
Retrieve Function source code:
```python download_code.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(
function_id="func_abc123",
decryption_key="your-decryption-key", # Required for downloading
)
# Download function code
code = function.download()
print(code) # Function source code
# Or download directly to a file
code = function.download(path="downloaded_function.py")
```
**Requirements:**
* Decryption key (available in Console) - passed when creating Function instance
* Only works for Functions you own or have access to
### Download for Backup
Back up all your Functions:
```python backup_functions.py theme={null}
import os
from notte_sdk import NotteClient
client = NotteClient()
functions = client.functions.list()
# Create backup directory
os.makedirs("function_backups", exist_ok=True)
for func in functions.items:
function = client.Function(function_id=func.workflow_id, decryption_key="your-key")
try:
code = function.download()
filename = f"function_backups/{func.name}_{func.latest_version}.py"
with open(filename, "w") as f:
f.write(code)
print(f"Backed up: {func.name}")
except Exception as e:
print(f"Failed to backup {func.name}: {e}")
```
## Deleting Functions
### Delete Function
Remove a Function permanently:
```python delete_function.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="func_abc123")
# Delete function
function.delete()
print("Function deleted")
```
**Warning:**
* Deletion is permanent
* All versions are deleted
* Run history is preserved
* Cannot be undone
## Sharing Functions
### Make Function Public
Share Functions with others:
```python make_public.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Deploy as shared
function = client.Function(
path="my_function.py",
name="Public Scraper",
shared=True, # Make publicly accessible
)
```
**Shared Functions:**
* ✅ Others can view and fork
* ✅ Original remains under your control
* ❌ Others cannot modify your version
* ✅ Usage tracked to your account
### Private Functions
Keep Functions private (default):
```python private_function.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(
path="my_function.py",
name="Private Automation",
shared=False, # Private (default)
)
```
## Best Practices
### 1. Version Your Functions
Update incrementally with clear changes:
```python version_backup.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="func_abc123")
# Before major update, download current version
current_code = function.download(decryption_key="key")
# Save backup
with open(f"backups/function_v{function.response.latest_version}.py", "w") as f:
f.write(current_code)
# Update function
function.update(path="new_version.py")
```
### 2. Monitor Function Health
Regular health checks:
```python function_health_check.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
def check_function_health(function_id: str):
"""Check recent run success rate."""
runs = client.functions.list_runs(function_id, only_active=False)
total = len(runs.items)
failed = sum(1 for r in runs.items if r.status == "failed")
success_rate = ((total - failed) / total * 100) if total > 0 else 0
print(f"Success rate: {success_rate:.1f}%")
print(f"Total runs: {total}")
print(f"Failed runs: {failed}")
return success_rate
# Monitor function
check_function_health("func_abc123")
```
### 3. Clean Up Old Runs
Archive or analyze old execution data:
```python cleanup_old_runs.py theme={null}
import json
from datetime import datetime, timedelta
from notte_sdk import NotteClient
client = NotteClient()
def archive_old_runs(function_id: str, days_old: int = 30):
"""Archive runs older than specified days."""
runs = client.functions.list_runs(function_id, only_active=False)
cutoff_date = datetime.now() - timedelta(days=days_old)
archive = []
for run in runs.items:
if run.created_at < cutoff_date:
archive.append(
{
"run_id": run.workflow_run_id,
"status": run.status,
"created_at": run.created_at.isoformat(),
"result": str(run.result)[:100], # First 100 chars
}
)
# Save archive
with open(f"archives/{function_id}_{datetime.now().date()}.json", "w") as f:
json.dump(archive, f, indent=2)
print(f"Archived {len(archive)} old runs")
archive_old_runs("function_abc123")
```
### 4. Document Changes
Keep change log for Function updates:
```python document_changes.py theme={null}
"""
Function: Data Scraper
Function ID: func_abc123
Version History:
- v1 (2024-01-15): Initial release
- v2 (2024-01-20): Added error handling
- v3 (2024-01-25): Improved scraping accuracy
- v4 (2024-02-01): Added retry logic
"""
def run(url: str):
# Your function code
pass
```
### 5. Test Before Production
Validate updates before deploying:
```python test_before_prod.py theme={null}
from notte_sdk import NotteClient
def validate_before_production():
client = NotteClient()
# Test locally first - decryption key needed for local execution
function = client.Function(function_id="func_abc123", decryption_key="your-key")
# Run with local=True for testing
test_result = function.run(url="https://test-site.com", local=True)
if test_result.status == "closed":
print("Test passed, ready to update production")
function.update(path="tested_function.py")
else:
print(f"Test failed: {test_result.result}")
```
## Troubleshooting
### Function Fails to Run
Check run details for errors:
```python troubleshoot_fails.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
function = client.Function(function_id="func_abc123")
run = client.functions.get_run("func_abc123", "run_xyz789")
if run.status == "failed":
print(f"Error: {run.result}")
# Run the function to get a replay
result = function.run()
replay = function.replay()
replay.download("debug_replay.mp4")
```
### Missing Environment Variables
Verify configuration:
```python missing_env_vars.py theme={null}
import os
def run():
required_vars = ["API_KEY", "WEBHOOK_URL"]
missing = [var for var in required_vars if not os.getenv(var)]
if missing:
return {"error": f"Missing environment variables: {', '.join(missing)}"}
# Continue with automation
```
### High Failure Rate
Analyze failure patterns:
```python high_failure_rate.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
runs = client.functions.list_runs("function_abc123")
failures = [r for r in runs.items if r.status == "failed"]
print(f"Failed runs: {len(failures)}/{len(runs.items)}")
# Analyze failure reasons
for run in failures[:5]: # Last 5 failures
print(f"Run {run.workflow_run_id}:")
print(f" Error: {run.result}")
print(f" Time: {run.created_at}")
```
## Next Steps
Learn how to write Functions
Call Functions via API or SDK
Schedule Functions with cron
Back to Functions overview
# Function Schedules
Source: https://docs.notte.cc/features/functions/schedules
Schedule Functions to run automatically with cron expressions
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Schedule Functions to run automatically at specific times using cron expressions.
## Overview
Function scheduling allows you to:
* Run automations on a regular schedule (daily, weekly, hourly, etc.)
* Execute tasks at specific times
* Automate recurring workflows
* Monitor websites continuously
Schedules are configured in the [Notte Console](https://console.notte.cc) and run automatically on Notte's infrastructure.
## Creating a Schedule
### Via Console
1. Go to [console.notte.cc/functions](https://console.notte.cc/functions)
2. Select your Function
3. Click "Schedule"
4. Enter cron expression
5. Set parameters (variables)
6. Save schedule
### Cron Expression Format
Cron expressions define when Functions run:
```
* * * * *
│ │ │ │ │
│ │ │ │ └─── Day of week (0-6, Sunday=0)
│ │ │ └───── Month (1-12)
│ │ └─────── Day of month (1-31)
│ └───────── Hour (0-23)
└─────────── Minute (0-59)
```
## Common Schedules
### Every Minute
```
* * * * *
```
Run function every minute.
**Use for:** Real-time monitoring, high-frequency updates
***
### Every Hour
```
0 * * * *
```
Run at the start of every hour (e.g., 1:00, 2:00, 3:00).
**Use for:** Hourly data collection, periodic checks
***
### Every Day at 9 AM
```
0 9 * * *
```
Run every day at 9:00 AM.
**Use for:** Daily reports, morning data sync
***
### Every Monday at 8 AM
```
0 8 * * 1
```
Run every Monday at 8:00 AM.
**Use for:** Weekly reports, start-of-week tasks
***
### First Day of Month
```
0 0 1 * *
```
Run at midnight on the 1st of every month.
**Use for:** Monthly reports, billing cycles
***
### Every 15 Minutes
```
*/15 * * * *
```
Run every 15 minutes.
**Use for:** Frequent monitoring, regular updates
***
### Weekdays at 6 PM
```
0 18 * * 1-5
```
Run at 6:00 PM Monday through Friday.
**Use for:** End-of-day business tasks
***
### Multiple Times Per Day
```
0 9,12,15,18 * * *
```
Run at 9 AM, 12 PM, 3 PM, and 6 PM every day.
**Use for:** Regular business hours monitoring
***
## Use Cases
### 1. Daily Price Monitoring
Monitor competitor pricing every day:
```python price_monitor.py theme={null}
from datetime import datetime
from notte_sdk import NotteClient
def run(competitor_urls: list[str]):
"""Monitor competitor prices daily."""
client = NotteClient()
prices = []
for url in competitor_urls:
with client.Session() as session:
session.execute(type="goto", url=url)
price = session.scrape(instructions="Extract product price")
prices.append({"url": url, "price": price})
return {"prices": prices, "checked_at": datetime.now().isoformat()}
```
**Schedule:** `0 9 * * *` (Every day at 9 AM)
***
### 2. Hourly Data Collection
Collect data every hour:
```python data_collector.py theme={null}
from datetime import datetime
from notte_sdk import NotteClient
def run(source_url: str):
"""Collect data every hour."""
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url=source_url)
data = session.scrape()
return {"data": data, "timestamp": datetime.now().isoformat()}
```
**Schedule:** `0 * * * *` (Every hour)
***
### 3. Weekly Reports
Generate reports every Monday:
```python weekly_report.py theme={null}
from datetime import datetime
from notte_sdk import NotteClient
def run():
"""Generate weekly report."""
client = NotteClient()
# Collect data from multiple sources
report_data = []
sources = ["https://analytics.example.com", "https://dashboard.example.com"]
for url in sources:
with client.Session() as session:
session.execute(type="goto", url=url)
data = session.scrape(instructions="Extract weekly metrics")
report_data.append(data)
return {"report": report_data, "week": datetime.now().isocalendar()[1]}
```
**Schedule:** `0 8 * * 1` (Every Monday at 8 AM)
***
### 4. Continuous Monitoring
Monitor website availability every 5 minutes:
```python uptime_monitor.py theme={null}
from datetime import datetime
from notte_sdk import NotteClient
def run(target_url: str, expected_text: str):
"""Monitor site uptime."""
client = NotteClient()
try:
with client.Session(idle_timeout_minutes=2) as session:
session.execute(type="goto", url=target_url)
content = session.scrape()
is_up = expected_text in content
return {"status": "up" if is_up else "down", "url": target_url, "checked_at": datetime.now().isoformat()}
except Exception as e:
return {"status": "error", "url": target_url, "error": str(e), "checked_at": datetime.now().isoformat()}
```
**Schedule:** `*/5 * * * *` (Every 5 minutes)
***
## Schedule Parameters
### Static Parameters
Set fixed parameters for scheduled runs:
```
Schedule: 0 9 * * *
Parameters:
url: "https://example.com"
max_results: 10
```
Every scheduled run uses these parameters.
### Dynamic Parameters
Use environment variables or context:
```python dynamic_params.py theme={null}
import os
from datetime import datetime
def run():
# Access environment variables
api_key = os.getenv("API_KEY")
webhook_url = os.getenv("WEBHOOK_URL")
# Use current date
today = datetime.now().strftime("%Y-%m-%d")
# Your automation
pass
```
## Managing Schedules
### View Scheduled Runs
Check upcoming scheduled executions in the Console:
1. Go to Function details
2. View "Scheduled Runs" section
3. See next execution time
4. View execution history
### Pause Schedule
Temporarily disable schedule:
1. Go to Function schedules
2. Toggle schedule off
3. Resume later without losing configuration
### Delete Schedule
Remove schedule permanently:
1. Go to Function schedules
2. Delete schedule
3. Function can still be invoked manually
## Monitoring Scheduled Functions
### Execution History
View past scheduled runs:
```python execution_history.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# List recent runs
runs = client.functions.list_runs(
"function_abc123",
only_active=False, # Include completed runs
)
for run in runs.items:
print(f"Run {run.workflow_run_id}:")
print(f" Status: {run.status}")
print(f" Created: {run.created_at}")
print(f" Updated: {run.updated_at}")
```
### Failed Runs
Handle scheduled failures:
```python failed_runs.py theme={null}
def run():
try:
# Your automation
result = perform_automation()
# Send success notification
notify_success(result)
return result
except Exception as e:
# Send failure alert
notify_failure(str(e))
# Return error info
return {"success": False, "error": str(e)}
```
### Alerts
Set up alerts for failures:
```python alerts.py theme={null}
def run():
try:
# Your automation
result = perform_automation()
return result
except Exception as e:
# Send to Slack/Discord/Email
requests.post(
os.getenv("WEBHOOK_URL", ""),
json={"text": f"Scheduled function failed: {str(e)}", "function_id": "function_abc123"},
)
raise # Re-raise to mark run as failed
```
## Best Practices
### 1. Use Appropriate Frequency
Match schedule to data update frequency:
```
# Data updates hourly
0 * * * * ✅ Good
# Data updates hourly, but checking every minute
* * * * * ❌ Wasteful
```
### 2. Add Error Handling
Scheduled functions should handle errors gracefully:
```python error_handling.py theme={null}
def run():
try:
result = perform_automation()
return {"success": True, "data": result}
except Exception as e:
# Log error, send alert
return {"success": False, "error": str(e)}
```
### 3. Set Reasonable Timeouts
```python set_timeouts.py theme={null}
from notte_sdk import NotteClient
def run():
client = NotteClient()
# Set timeout appropriate for schedule
with client.Session(idle_timeout_minutes=10) as session:
# Your automation
pass
```
### 4. Monitor Schedule Health
Check that schedules are running:
```python weekly_health_check.py theme={null}
from notte_sdk import NotteClient
def run():
"""Check if all schedules are healthy."""
client = NotteClient()
# Get all workflow runs from last 24 hours
workflows = client.functions.list()
health_report = []
for workflow in workflows.items:
runs = client.functions.list_runs(workflow.workflow_id)
# Check recent runs
recent_failures = [r for r in runs.items if r.status == "failed"]
health_report.append({"workflow_id": workflow.workflow_id, "recent_failures": len(recent_failures)})
return health_report
```
**Schedule:** `0 0 * * *` (Daily health check)
### 5. Use Idempotent Operations
Design functions to handle duplicate runs:
```python idempotent.py theme={null}
def already_processed(date: str):
"""Check if date has already been processed."""
# TODO: Implement logic to check if date has already been processed
False
def process_data(date: str):
"""Process data for the given date."""
# TODO: Implement logic to process data for the given date
"processed"
def mark_processed(date: str):
"""Mark date as processed."""
# TODO: Implement logic to mark date as processed
"mark_as_processed"
def run(date: str):
"""Idempotent function - safe to run multiple times."""
# Use date as unique identifier
# Skip if already processed
if already_processed(date):
return {"status": "already_processed", "date": date}
# Process data
result = process_data(date)
# Mark as processed
mark_processed(date)
return {"status": "processed", "date": date, "result": result}
```
## Timezone Considerations
Schedules run in UTC by default. Convert to your timezone:
```python theme={null}
# If you want 9 AM EST (UTC-5), use:
# 14 * * * * (9 AM + 5 hours = 14:00 UTC)
# If you want 9 AM PST (UTC-8), use:
# 17 * * * * (9 AM + 8 hours = 17:00 UTC)
```
Or handle timezone in function:
```python timezone.py theme={null}
from datetime import datetime
import pytz
def run():
# Get current time in specific timezone
tz = pytz.timezone("America/New_York")
current_time = datetime.now(tz)
# Your automation
pass
```
## Next Steps
Learn how to invoke Functions manually
Update and monitor Functions
Write schedulable Functions
Configure schedules in Console
# Ad Blocking
Source: https://docs.notte.cc/features/sessions/ad-blocking
Built-in ad and tracker blocking for browser sessions
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Ad Blocking provides built-in filtering of advertisements, trackers, and unwanted content in your browser sessions. This improves page load performance, reduces bandwidth usage, and creates cleaner pages for scraping and automation.
## Key Benefits
* **Faster page loads** - Skip downloading ads and trackers
* **Reduced bandwidth** - Lower data transfer costs
* **Cleaner content** - Easier extraction without ad clutter
* **Better reliability** - Avoid ad-related JavaScript errors
**Enterprise Feature**
Built-in Ad Blocking is available exclusively for enterprise customers. Contact [andrea@notte.cc](mailto:andrea@notte.cc) to learn more about enterprise plans and advanced session features.
# Browser Controls
Source: https://docs.notte.cc/features/sessions/browser-controls
Complete reference of all browser actions available in sessions
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Sessions provide a comprehensive set of browser actions for interacting with web pages. All actions are executed through `session.execute()`.
## Navigation Actions
### Goto
Navigate to a URL.
```python goto.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
```
**Parameters:**
* `url` (str): The URL to navigate to
**Use for:** Opening pages, navigating between pages
***
### GotoNewTab
Open a URL in a new browser tab.
```python goto_new_tab.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto_new_tab", url="https://example.com/products")
```
**Parameters:**
* `url` (str): The URL to open in a new tab
**Use for:** Opening multiple pages simultaneously, preserving context
***
### SwitchTab
Switch to a different browser tab.
```python switch_tab.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
# Open multiple tabs
session.execute(type="goto", url="https://example.com")
session.execute(type="goto_new_tab", url="https://example.com/products")
# Switch back to first tab
session.execute(type="switch_tab", tab_index=0)
```
**Parameters:**
* `tab_index` (int): Zero-based index of the tab to switch to
**Use for:** Managing multiple tabs, comparing content across pages
***
### GoBack
Navigate back to the previous page.
```python go_back.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
session.execute(type="goto", url="https://example.com/products")
# Go back to homepage
session.execute(type="go_back")
```
**Use for:** Browser back button functionality, returning to previous pages
***
### GoForward
Navigate forward in browser history.
```python go_forward.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
session.execute(type="goto", url="https://example.com/products")
session.execute(type="go_back")
# Now go forward again
session.execute(type="go_forward")
```
**Use for:** Browser forward button functionality
***
### Reload
Reload the current page.
```python reload.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
session.execute(type="reload")
```
**Use for:** Refreshing page content, retrying after errors
***
## Interaction Actions
### Click
Click on an element.
```python click.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
# Click by CSS selector
session.execute(type="click", selector="button#submit")
# Pseudo observe output: [B1] button "Submit"
# Only use IDs that appear in your live observe() output.
session.execute(type="click", id="B1")
# Click by text selector
session.execute(type="click", selector="button:has-text('Submit')")
```
**Parameters:**
* `selector` (str): CSS selector for the element
* `id` (str): Element ID
* `text` (str): Exact text content
* `aria_label` (str): ARIA label attribute
* `placeholder` (str): Placeholder text
* `title` (str): Title attribute
**Use for:** Clicking buttons, links, checkboxes, any clickable element
***
### Fill
Fill a text input or textarea.
```python fill.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
# Fill by selector
session.execute(type="fill", selector="input[name='email']", value="user@example.com")
# Pseudo observe output: [I1] input "Email"
# Only use IDs that appear in your live observe() output.
session.execute(type="fill", id="I1", value="user@example.com")
# Fill by placeholder selector
session.execute(type="fill", selector="input[placeholder='Enter your email']", value="user@example.com")
```
**Parameters:**
* `selector` (str): CSS selector for the input
* `id` (str): Element ID
* `placeholder` (str): Placeholder text
* `aria_label` (str): ARIA label
* `value` (str): The text to fill
**Use for:** Filling forms, search boxes, text inputs
***
### Check
Check or uncheck a checkbox.
```python check.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
# Check a checkbox
session.execute(type="check", selector="input[type='checkbox']#terms", value=True)
# Uncheck a checkbox
session.execute(type="check", selector="input[type='checkbox']#newsletter", value=False)
```
**Parameters:**
* `selector` (str): CSS selector for the checkbox
* `id` (str): Element ID
* `checked` (bool): True to check, False to uncheck
**Use for:** Toggling checkboxes, accepting terms, selecting options
***
### SelectDropdownOption
Select an option from a dropdown.
```python select_dropdown_option.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
# Select by visible text
session.execute(type="select_dropdown_option", selector="select#country", value="United States")
# Select by value attribute
session.execute(type="select_dropdown_option", selector="select#country", value="us")
```
**Parameters:**
* `selector` (str): CSS selector for the select element
* `option_text` (str): Visible text of the option
* `option_value` (str): Value attribute of the option
**Use for:** Selecting from dropdowns, choosing options
***
### PressKey
Press a keyboard key.
```python press_key.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
# Press Enter
session.execute(type="press_key", key="Enter")
# Press Escape
session.execute(type="press_key", key="Escape")
# Press Tab
session.execute(type="press_key", key="Tab")
```
**Parameters:**
* `key` (str): Key name (e.g., "Enter", "Escape", "Tab", "ArrowDown")
**Use for:** Keyboard navigation, submitting forms, triggering shortcuts
**Common keys:** Enter, Escape, Tab, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Backspace, Delete
***
### EvaluateJs
Evaluate JavaScript code on the current page and return the result.
```python goto_new_tab.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://notte.cc/")
session.execute(type="evaluate_js", code="document.title")
```
**Parameters:**
* `code` (str): The JavaScript code to evaluate on the page
**Use for:** Evaluating JavaScript code, extracting data from the page
***
## Scrolling Actions
### ScrollUp
Scroll up on the page.
```python scroll_up.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
session.execute(type="scroll_up")
```
**Use for:** Scrolling to top of page, revealing content above
***
### ScrollDown
Scroll down on the page.
```python scroll_down.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
session.execute(type="scroll_down")
```
**Use for:** Loading lazy content, revealing content below, pagination
***
## File Actions
### UploadFile
Upload a file to a file input.
```python upload_file.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com/upload")
# Upload from local file
session.execute(type="upload_file", selector="input[type='file']", file_path="/path/to/document.pdf")
# Upload with ID
session.execute(type="upload_file", id="file-upload", file_path="/path/to/image.jpg")
```
**Parameters:**
* `selector` (str): CSS selector for the file input
* `id` (str): Element ID
* `file_path` (str): Path to the file to upload
**Use for:** Uploading documents, images, any file input
***
### DownloadFile
Download a file from a link.
```python download_file.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
result = session.execute(type="download_file", selector="a.download-link")
print(f"Downloaded: {result}")
```
**Parameters:**
* `selector` (str): CSS selector for the download link
* `id` (str): Element ID
**Use for:** Downloading files, reports, documents
***
## Wait Action
### Wait
Pause execution for a specified duration.
```python wait.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
# Wait 2 seconds
session.execute(type="wait", time_ms=2000)
# Wait 5 seconds for page to load
session.execute(type="wait", time_ms=5000)
```
**Parameters:**
* `duration` (int): Time to wait in milliseconds
**Use for:** Waiting for page loads, animations, dynamic content
**Tip:** Use sparingly. Notte automatically waits for page loads and element visibility. Only use Wait for specific timing requirements.
***
## Data Extraction
### Scrape
Extract data from the current page.
```python scrape.py theme={null}
from notte_sdk import NotteClient
from pydantic import BaseModel
client = NotteClient()
class Product(BaseModel):
name: str
price: float
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
# Get page markdown
markdown = session.scrape()
# Extract with instructions
data = session.scrape(instructions="Extract all product names and prices")
# Structured extraction (wrap list in a model)
products = session.scrape(response_format=Product, instructions="Extract all products")
```
**Parameters:**
* `instructions` (str): Natural language extraction instructions
* `response_format` (type\[BaseModel]): Pydantic model for structured output
* `only_main_content` (bool): Extract only main content, ignore headers/footers
**Use for:** Data extraction, web scraping, content analysis
See [Scraping](/concepts/scraping) for detailed documentation.
***
## Communication Actions
### SmsRead
Read SMS messages from a persona's phone number.
```python sms_read.py theme={null}
from collections.abc import Sequence
from notte_sdk import NotteClient
from notte_sdk.types import SMSResponse
client = NotteClient()
def extract_code(messages: Sequence[SMSResponse]) -> str:
# Extract verification code from messages
for msg in messages:
if msg.body and "code" in msg.body.lower():
return msg.body
return ""
# Create persona with phone number
persona = client.Persona(create_phone_number=True)
phone_number = persona.info.phone_number
# Use in session
with client.Session() as session:
# Trigger SMS (e.g., 2FA code)
if phone_number:
session.execute(type="fill", selector="input[name='phone']", value=phone_number)
session.execute(type="click", selector="button.send-code")
# Read SMS from persona
messages = persona.sms()
# Extract verification code
code = extract_code(messages)
```
**Parameters:**
* `persona_id` (str): Persona ID with phone number
**Use for:** Reading 2FA codes, SMS verification, phone-based authentication
See [Personas](/concepts/personas) for details.
***
### EmailRead
Read emails from a persona's email address.
```python email_read.py theme={null}
from collections.abc import Sequence
from notte_sdk import NotteClient
from notte_sdk.types import EmailResponse
client = NotteClient()
def extract_link(messages: Sequence[EmailResponse]) -> str:
# Extract verification link from messages
for msg in messages:
if msg.text_content and "verify" in msg.text_content.lower():
return msg.text_content
return ""
# Create persona with email
persona = client.Persona()
# Use in session
with client.Session() as session:
# Trigger email (e.g., verification email)
session.execute(type="fill", selector="input[name='email']", value=persona.info.email)
session.execute(type="click", selector="button.send-verification")
# Read emails from persona
messages = persona.emails()
# Extract verification link
link = extract_link(messages)
```
**Parameters:**
* `persona_id` (str): Persona ID with email address
**Use for:** Reading verification emails, email-based authentication
See [Personas](/concepts/personas) for details.
***
## Action Patterns
### Chaining Actions
Execute multiple actions in sequence:
```python action_chaining.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
# Navigation
session.execute(type="goto", url="https://example.com/login")
# Form filling
session.execute(type="fill", selector="input[name='email']", value="user@example.com")
session.execute(type="fill", selector="input[name='password']", value="password123")
# Submission
session.execute(type="click", selector="button[type='submit']")
# Wait for redirect
session.execute(type="wait", time_ms=2000)
# Verify success
content = session.scrape()
print(content)
```
### Error Handling
Handle action failures:
```python error_handling.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
# Don't raise on failure
result = session.execute(type="click", selector="button.maybe-exists", raise_on_failure=False)
if result.success:
print("Button clicked successfully")
session.execute(type="click", selector="button.next")
else:
print(f"Click failed: {result.message}")
# Try alternative approach
session.execute(type="click", selector="button.alternative")
```
### Conditional Actions
Execute actions based on conditions:
```python conditional_actions.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
# Check if element exists
result = session.execute(type="click", selector="button.optional", raise_on_failure=False)
if result.success:
# Element was there and clicked
session.execute(type="click", selector="button.next")
else:
# Element wasn't there, skip
print("Optional button not found, continuing...")
```
## Selector Strategies
### CSS Selectors
Most flexible and commonly used:
```python css_selectors.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
# By ID
session.execute(type="click", selector="#submit-button")
# By class
session.execute(type="click", selector=".btn-primary")
# By attribute
session.execute(type="click", selector="button[type='submit']")
# By combination
session.execute(type="click", selector="form#login button.submit")
# By nth-child
session.execute(type="click", selector="ul li:nth-child(2)")
```
### Direct Attributes
Use direct attribute parameters when available:
```python direct_attributes.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
# Pseudo observe output: [B1] button "Submit"
# Only use IDs that appear in your live observe() output.
session.execute(type="click", id="B1")
# By selector
session.execute(type="click", selector="button[type='submit']")
# By placeholder selector
session.execute(type="fill", selector="input[placeholder='Enter email']", value="user@example.com")
# By ARIA label selector
session.execute(type="click", selector="button[aria-label='Close dialog']")
```
### Best Practices
**Prefer stable selectors:**
```python stable_selectors.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
# Good - uses ID (stable)
session.execute(type="click", id="submit-btn")
# Good - uses data attribute
session.execute(type="click", selector="button[data-testid='submit']")
# Avoid - fragile position-based
session.execute(type="click", selector="div > div > button:nth-child(3)")
```
**Use specific selectors:**
```python specific_selectors.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
# Good - specific
session.execute(type="fill", selector="form#login input[name='email']", value="user@example.com")
# Less specific - might match wrong element
session.execute(type="fill", selector="input", value="user@example.com")
```
## Common Workflows
### Form Submission
```python form_submission.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com/contact")
session.execute(type="fill", id="name", value="John Doe")
session.execute(type="fill", id="email", value="john@example.com")
session.execute(type="fill", id="message", value="Hello!")
session.execute(type="click", selector="button[type='submit']")
```
### Search and Extract
```python search_extract.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
session.execute(type="goto", url="https://example.com")
session.execute(type="fill", selector="input[name='search']", value="laptop")
session.execute(type="press_key", key="Enter")
session.execute(type="wait", time_ms=2000)
results = session.scrape(instructions="Extract search results")
print(results)
```
### Multi-Tab Workflow
```python multi_tab.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
def process_data(data):
print(f"Processed: {data[:100]}...")
with client.Session() as session:
# Open multiple tabs
session.execute(type="goto", url="https://site1.com")
session.execute(type="goto_new_tab", url="https://site2.com")
session.execute(type="goto_new_tab", url="https://site3.com")
# Extract from each tab
for tab_index in range(3):
session.execute(type="switch_tab", tab_index=tab_index)
data = session.scrape()
process_data(data)
```
### File Upload and Download
```python file_upload_download.py theme={null}
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", time_ms=3000)
# Download result
result = session.execute(type="download_file", selector="a.download")
print(f"Downloaded: {result}")
```
## Next Steps
Configure session behavior
Manage session states
Detailed API documentation
Let AI handle actions automatically
# Browser Extensions
Source: https://docs.notte.cc/features/sessions/browser-extensions
Load custom browser extensions in your sessions
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Browser Extensions support allows you to load Chrome extensions into your browser sessions. This enables capabilities like specialized ad blockers, password managers, custom tooling, and other extension-based functionality.
## Key Benefits
* **Custom tooling** - Load proprietary or specialized extensions
* **Enhanced capabilities** - Access extension-specific features and APIs
* **Familiar workflows** - Use the same extensions as your local browser
* **Pre-configured sessions** - Extensions loaded automatically on session start
**Enterprise Feature**
Browser Extensions support is available exclusively for enterprise customers. Contact [andrea@notte.cc](mailto:andrea@notte.cc) to learn more about enterprise plans and custom browser configurations.
# Browser Pools
Source: https://docs.notte.cc/features/sessions/browser-pools
Managed pools of browser instances for high-throughput automation
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Browser Pools provide managed, pre-warmed browser instances that are ready to use instantly. Instead of creating new browser sessions on demand, pools maintain a set of active browsers that can be allocated to your automation tasks immediately.
## Key Benefits
* **Instant session availability** - No cold start delays
* **Automatic scaling** - Pools grow and shrink based on demand
* **Resource optimization** - Efficient browser lifecycle management
* **High throughput** - Handle thousands of concurrent automations
**Enterprise Feature**
Browser Pools are available exclusively for enterprise customers. Contact [andrea@notte.cc](mailto:andrea@notte.cc) to learn more about enterprise plans and custom deployment options.
# Browser Profiles
Source: https://docs.notte.cc/features/sessions/browser-profiles
Persist browser state across sessions
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Profiles let you save and reuse browser state—including cookies, local storage, session storage, and cache—across multiple sessions. This is useful for maintaining login states, preserving user preferences, or building realistic multi-session workflows.
## How Profiles Work
A profile is a saved snapshot of a browser's user data directory. By default, each Notte session uses a fresh browser state to ensure isolation.
When you create a profile and use it in a session with `persist=True`, Notte saves that session's browser state. You can then attach the profile to future sessions to restore the saved state.
## Create a Profile
Create a profile to store browser state. Optionally, give it a name to keep track of different profiles:
```python create_profile.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Create a profile with optional name
profile = client.profiles.create(name="my-profile")
print(f"Profile created: {profile.profile_id}")
print(f"Profile name: {profile.name}")
```
## Use a Profile in a Session
Attach a profile to a session to load saved browser state:
```python use_profile.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Use an existing profile in a session
with client.Session(profile={"id": "notte-profile-abc123", "persist": False}) as session:
# Session loads saved browser state from the profile
session.execute(type="goto", url="https://example.com")
```
### Persist Changes
The `persist` parameter controls whether session changes are saved back to the profile:
* `True` - Save browser state to the profile when the session ends
* `False` (default) - Use the profile as read-only; don't save changes
Set `persist=True` the first time you use a new profile to save the initial browser state. After that, you can use `persist=False` to reuse the profile without modifying it.
## Profile Login Example
### Step 1: Login and Save to Profile
First, create a profile and perform a login. When the session ends with `persist=True`, all cookies and browser state are saved to the profile:
```python persist_profile.py theme={null}
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
```
### Step 2: Reuse the Saved Profile
Use the saved profile in a new session. The browser automatically loads the saved state, so you're already authenticated:
```python reuse_profile.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Reuse a previously saved profile (read-only)
with client.Session(profile={"id": "notte-profile-abc123", "persist": False}) as session:
# Navigate directly - already authenticated!
session.execute(type="goto", url="https://github.com")
# Perform actions as logged-in user
obs = session.observe()
print(f"Page title: {obs.metadata.title}")
```
**What happens:**
1. A new session is created using the same profile ID
2. The browser loads saved cookies and state from the profile
3. You navigate directly without needing to log in again
4. The session picks up right where the previous one left off
This pattern is useful for:
* Avoiding repeated logins across automation runs
* Testing authenticated user flows
* Managing multiple accounts with separate profiles
* Maintaining session state over time
## Using Profiles with Agents
Profiles work seamlessly with Notte Agents. An agent running with a pre-authenticated profile can access authenticated resources immediately:
```python profile_with_agent.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Use a profile with an agent
with client.Session(profile={"id": "notte-profile-abc123", "persist": False}) as session:
agent = client.Agent(session=session, max_steps=10)
# Agent runs with pre-authenticated session
response = agent.run(
task="Go to my GitHub notifications and summarize them", url="https://github.com/notifications"
)
print(f"Agent response: {response.answer}")
```
## Managing Profiles
### List Profiles
Retrieve all your profiles with optional filtering:
```python list_profiles.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# List all profiles
profiles = client.profiles.list()
for profile in profiles:
print(f"- {profile.name}: {profile.profile_id}")
# Filter by name
filtered = client.profiles.list(name="github")
print(f"Found {len(filtered)} profiles matching 'github'")
```
### Get Profile Details
Retrieve information about a specific profile:
```python get_profile.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Get profile details
profile = client.profiles.get("notte-profile-abc123")
print(f"Profile ID: {profile.profile_id}")
print(f"Profile Name: {profile.name}")
print(f"Created At: {profile.created_at}")
```
### Delete a Profile
Delete a profile when you no longer need it:
```python delete_profile.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Delete a profile
deleted = client.profiles.delete("notte-profile-abc123")
if deleted:
print("Profile deleted successfully")
```
## Read-Only Profile Usage
Load a profile without saving changes by setting `persist=False`:
```python use_profile.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Use an existing profile in a session
with client.Session(profile={"id": "notte-profile-abc123", "persist": False}) as session:
# Session loads saved browser state from the profile
session.execute(type="goto", url="https://example.com")
```
**Use cases for read-only profiles:**
* Test workflows without affecting saved state
* Run parallel sessions with the same profile safely
* Maintain a clean baseline profile for repeated use
By default, `persist` is `False`, so you don't have to explicitly specify it for read-only access.
## Best Practices
### Profile Management
* Use descriptive names to identify profiles by their purpose (e.g., `github-login`, `twitter-bot-1`)
* Create separate profiles for different accounts or services
* Periodically verify that saved sessions are still valid
### Security
* Profiles contain sensitive session data; treat profile IDs as secrets
* Delete profiles for accounts that are no longer needed
* Use separate profiles for production and development environments
### Performance
* Profiles with large caches may take longer to load
* Consider creating fresh profiles periodically if performance degrades
## Comparison: Profiles vs Cookies
| Feature | Profiles | Cookies |
| --------------- | -------------------------------------------- | ---------------------- |
| **Scope** | Full browser state (cookies, storage, cache) | Cookies only |
| **Storage** | Managed by Notte | JSON file you manage |
| **Persistence** | Automatic on session end | Manual export/import |
| **Use case** | Long-term state preservation | Quick cookie injection |
Use profiles when you need complete browser state preservation. Use cookies when you only need to inject specific authentication tokens.
## Next Steps
Manage session lifecycle
Manual cookie management
Secure credential storage
All session options
# Browser Types
Source: https://docs.notte.cc/features/sessions/browser-types
Choose between Chromium or Chrome for your sessions
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Notte supports multiple browser engines, allowing you to choose the right browser for your automation needs.
## Supported Browsers
### Chromium (Default)
Chromium is the open-source browser that powers Chrome. It's the default and recommended option for most use cases.
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(browser_type="chromium") as session:
page = session.page
page.goto("https://example.com")
```
**Best for:**
* General web automation
* Fast performance
* Wide compatibility
### Chrome
Google Chrome with additional Google-specific features and branding.
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(browser_type="chrome") as session:
page = session.page
page.goto("https://example.com")
```
**Best for:**
* Sites that detect Chromium vs Chrome
* Google service automation
* Maximum compatibility
## Choosing the Right Browser
### Use Chromium when:
* Starting a new project (it's the default)
* You need fast performance
* Standard web automation
### Use Chrome when:
* Sites specifically check for Chrome vs Chromium
* Automating Google services
* You need maximum compatibility
## Next Steps
Configure anti-detection features
Automatically solve captchas
All session configuration options
Use persistent browser profiles
# CAPTCHA Solving
Source: https://docs.notte.cc/features/sessions/captcha-solving
Automatically detect and solve captchas during browser automation
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Notte can automatically detect and solve captchas including reCAPTCHA v2, reCAPTCHA v3, hCaptcha, and simple text challenges during your browser automation.
## Quick Start
Enable captcha solving when creating a session:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(solve_captchas=True) as session:
page = session.page
page.goto("https://www.google.com/recaptcha/api2/demo")
# Captcha automatically solved
```
## Supported CAPTCHA Types
Notte automatically detects and solves:
* ✅ **reCAPTCHA v2** - Checkbox and image challenges
* ✅ **reCAPTCHA v3** - Invisible captchas
* ✅ **hCaptcha** - Checkbox and image challenges
* ✅ **Text CAPTCHAs** - Simple "read the characters and type them" challenges
* ✅ **Image CAPTCHAs** - Visual verification challenges
## How It Works
When captcha solving is enabled:
1. **Detection** - Notte monitors the page for captcha elements
2. **Solving** - Captchas are solved automatically in the background
3. **Continuation** - Your automation continues seamlessly
No additional code is needed - captchas are solved automatically when encountered.
## Captcha + Proxies
Combine captcha solving with proxies for better success rates:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(
solve_captchas=True,
proxies=True # Use residential proxies
) as session:
page = session.page
page.goto("https://example.com")
# Both captcha solving and proxies active
```
## Best Practices
### 1. Use Realistic Delays
Add human-like delays before and after captcha-protected actions:
```python realistic_delays.py theme={null}
import time
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(solve_captchas=True) as session:
page = session.page
# Navigate to page
page.goto("https://example.com/protected")
# Wait for page to load
time.sleep(2)
# Fill form
page.fill('input[name="email"]', "user@example.com")
time.sleep(1)
# Submit (captcha will be solved)
page.click('button[type="submit"]')
```
### 2. Monitor for Failures
Check if captcha solving failed:
```python monitor_failures.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(solve_captchas=True) as session:
page = session.page
page.goto("https://example.com/protected")
try:
page.click('button[type="submit"]')
page.wait_for_url("**/success", timeout=30000) # 30 seconds
except Exception as e:
print(f"Captcha solving may have failed: {e}")
# Handle failure
```
### 3. Use Headless=False for Debugging
Watch captcha solving in action:
```python headless_debug.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(
solve_captchas=True,
headless=False, # Opens live viewer
) as session:
# You can watch captchas being solved
pass
```
### 4. Combine with Stealth
Use stealth features for better success rates:
```python combine_stealth.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(solve_captchas=True, proxies=True, viewport_width=1920, viewport_height=1080) as session:
# Maximum captcha success rate
pass
```
## Examples
### reCAPTCHA
For reCAPTCHA challenges, use the `captcha_solve` action with `captcha_type="recaptcha"`. This example comes from the [reCAPTCHA template](https://www.notte.cc/templates/captcha-bot-handling/basic-recaptcha).
```python recaptcha_solve_action.py theme={null}
from notte_sdk import NotteClient
DEMO_URL = "https://nopecha.com/captcha/recaptcha#easy"
client = NotteClient()
with client.Session(solve_captchas=True, proxies=True, open_viewer=True) as session:
session.execute(type="goto", url=DEMO_URL)
result = session.execute(
type="captcha_solve",
captcha_type="recaptcha",
raise_on_failure=False,
)
if not result.success:
raise RuntimeError(f"reCAPTCHA solve failed: {result.message}")
session.execute(type="wait", time_ms=2000)
```
### Text CAPTCHAs
Text CAPTCHAs are the old-school challenges that show distorted letters, numbers, or a short phrase and ask the user to type the answer into a field. For these challenges, use `captcha_type="text"`. This example comes from the [text CAPTCHA template](https://www.notte.cc/templates/captcha-bot-handling/basic-text-captcha).
```python text_captcha_solve_action.py theme={null}
from notte_sdk import NotteClient
DEMO_URL = "https://captcha.com/demos/features/captcha-demo.aspx#"
VALIDATE_SELECTOR = 'internal:role=button[name="Validate"i]'
client = NotteClient()
with client.Session(solve_captchas=True, proxies=True, open_viewer=True) as session:
session.execute(type="goto", url=DEMO_URL)
result = session.execute(
type="captcha_solve",
captcha_type="text",
raise_on_failure=False,
)
if not result.success:
raise RuntimeError(f"Text CAPTCHA solve failed: {result.message}")
session.execute(type="click", selector=VALIDATE_SELECTOR)
```
## Limitations
### What CAPTCHA Solving Can Do:
* ✅ Solve most reCAPTCHA v2 challenges
* ✅ Solve reCAPTCHA v3 automatically
* ✅ Solve most hCaptcha challenges
* ✅ Solve simple text and image CAPTCHA challenges
* ✅ Work with residential proxies
* ✅ Work in headless and non-headless mode
### What It Cannot Do:
* ❌ Solve 100% of captchas (some are unsolvable)
* ❌ Reliably solve heavily distorted or ambiguous text challenges
* ❌ Solve custom/proprietary captcha systems
* ❌ Bypass all bot detection (combine with stealth)
## Common Issues
### Issue: Captchas Not Being Solved
**Possible causes:**
* `solve_captchas=True` not set
* Captcha type not supported
* Site has additional bot detection
**Solution:**
```python ensure_requirements.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Ensure all requirements are met
with client.Session(
solve_captchas=True, # Must be enabled
proxies=True, # Helps with detection
) as session:
pass
```
### Issue: Timeout Waiting for Captcha
Increase session timeout for captcha-heavy workflows:
```python timeout_handling.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(
solve_captchas=True,
idle_timeout_minutes=15, # Longer timeout
) as session:
pass
```
## Testing CAPTCHA Solving
Test captcha solving on demo sites:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
test_sites = [
"https://www.google.com/recaptcha/api2/demo",
"https://2captcha.com/demo/recaptcha-v2",
"https://democaptcha.com/demo-form-eng/hcaptcha.html"
]
with client.Session(
solve_captchas=True,
headless=False
) as session:
page = session.page
for site in test_sites:
print(f"Testing {site}")
page.goto(site)
page.screenshot(path=f"captcha_test_{test_sites.index(site)}.png")
```
## Pricing
CAPTCHA solving incurs additional costs based on the number of captchas solved. Check your plan for details.
## Next Steps
Learn about Chrome and other browsers
Combine with anti-detection features
Use proxies with captcha solving
Watch captcha solving in real-time
# Cloudflare Web Bot Auth
Source: https://docs.notte.cc/features/sessions/cloudflare-web-bot-auth
Access Cloudflare-protected websites by cryptographically signing browser requests
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Many websites use Cloudflare's [Web Bot Auth](https://webbotauth.io) protocol to distinguish between legitimate automated services and unwanted bots. Notte is registered as a verified bot in Cloudflare's registry, which means sessions can cryptographically prove their identity and gain access to otherwise restricted content.
## How It Works
Cloudflare's Web Bot Auth relies on [HTTP Message Signatures (RFC 9421)](https://datatracker.ietf.org/doc/html/rfc9421) to verify the origin of requests. When enabled, Notte transparently signs every outgoing HTTP request in the session with our registered cryptographic identity. Cloudflare then checks these signatures against its verified bots list and grants access accordingly.
In practice, this means:
1. You create a session with `web_bot_auth=True`
2. Every HTTP request leaving the browser is signed with Notte's credentials
3. Cloudflare verifies the signature and recognizes Notte as a trusted bot
4. The request passes through without triggering bot challenges
No extra code or configuration is needed on your side beyond flipping the flag.
## Quick Start
Pass `web_bot_auth=True` when creating a session:
```python quick_start.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(web_bot_auth=True) as session:
page = session.page
page.goto("https://example.com")
# All requests are automatically signed
```
## Complete Example
Web bot auth pairs well with other session features. Here's an example combining it with residential proxies and the live viewer:
```python complete_example.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(
web_bot_auth=True,
proxies=True, # Use residential proxies
open_viewer=True,
) as session:
page = session.page
# Navigate to a Cloudflare-protected site
page.goto("https://example.com")
# Interact with the page normally
page.click("a[href='/dashboard']")
page.wait_for_load_state("networkidle")
print("Successfully accessed protected content!")
```
## Using with Agents
Agents automatically inherit web bot auth from the underlying session:
```python agent_example.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(web_bot_auth=True) as session:
agent = client.Agent(session=session)
response = agent.run(task="Go to example.com and extract the main content")
print(response.answer)
```
## Verifying Your Setup
The [webbotauth.io/test](https://webbotauth.io/test) page is a handy diagnostic tool that shows whether incoming requests carry valid signatures. Point a web bot auth session at it to confirm everything is working:
```python testing.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(
web_bot_auth=True,
open_viewer=True,
) as session:
page = session.page
page.goto("https://webbotauth.io/test")
page.screenshot(path="web_bot_auth_test.png")
print("Check the screenshot to verify authentication status")
```
## Use Cases
* **Scraping Cloudflare-protected sites** — bypass bot challenges on sites that recognize verified bots
* **Reliable agent workflows** — prevent agents from getting stuck on Cloudflare interstitial pages
* **Data pipelines** — collect data from protected endpoints without manual intervention
Web bot auth proves your identity cryptographically, which is fundamentally different from [stealth mode](/features/sessions/stealth-mode) (which hides your identity) or [proxies](/features/sessions/proxies) (which mask your IP). These approaches are complementary — combining them gives you the broadest coverage.
## Limitations
* Only effective on sites that participate in Cloudflare's verified bots program
* Requests are identified as coming from Notte — the target site must trust Notte as a verified bot
* Does not replace other anti-detection techniques for sites that don't use Cloudflare Web Bot Auth
## Further Reading
* [Cloudflare Blog — Verified Bots with Cryptography](https://blog.cloudflare.com/verified-bots-with-cryptography/)
* [HTTP Message Signatures — RFC 9421](https://datatracker.ietf.org/doc/html/rfc9421)
* [Web Bot Auth IETF Draft](https://datatracker.ietf.org/doc/html/draft-meunier-web-bot-auth-architecture)
* [WebBotAuth.io](https://webbotauth.io)
## Next Steps
Combine with anti-detection features
Route traffic through residential proxies
Automatically solve captchas
Explore all session options
# Session Configurations
Source: https://docs.notte.cc/features/sessions/configuration
Learn how to create and configure Notte browser sessions
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Sessions are isolated browser instances running in the cloud that you can control programmatically. Each session provides a Playwright-compatible page that you can automate using familiar browser automation APIs.
## Quick Start
Create a session with default settings:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
print(f"Session ID: {session.session_id}")
page = session.page # Playwright-compatible page
page.goto("https://example.com")
```
Active sessions can be viewed and managed in the [Sessions](https://console.notte.cc/sessions) page in the console.
Sessions are automatically stopped when exiting the context manager. Always use the `with` statement to ensure proper cleanup.
## Configuration Options
Customize your session with these options:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(
headless=True,
solve_captchas=True,
proxies=True,
viewport_width=1920,
viewport_height=1080,
timeout_minutes=10,
browser_type="chromium"
) as session:
page = session.page
page.goto("https://example.com")
```
### Common Parameters
Whether to run the browser in headless mode. Set to `false` to open a live viewer in your browser.
Automatically detect and solve captchas (reCAPTCHA, hCaptcha, etc.)
Enable residential proxies. Set to `true` for default proxies or provide custom proxy configuration.
See [Proxy Configuration](#proxies) for details.
Session timeout in minutes. Sessions automatically close after this duration (min: 1, max: 30).
Browser viewport width in pixels.
Browser viewport height in pixels.
Browser engine to use: `"chromium"`, or `"chrome"`.
### Advanced Parameters
Custom user agent string for the browser session.
Custom Chrome/Chromium launch arguments. Advanced use only.
Connect to an external browser session via Chrome DevTools Protocol URL (e.g., from Kernel.sh or other providers).
Enable file storage for uploading/downloading files during the session.
Path to a JSON file for automatic cookie loading at session start and saving at session end.
Attach a file storage instance to the session for file operations.
Default perception type for observations: `"fast"` (simple) or `"deep"` (LLM-powered).
Raise exceptions when action execution fails instead of returning error results.
## Session Response
When you start a session, you get access to these properties and methods:
```python session_response.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
session = client.Session()
session.start()
# Session properties
session_id = session.session_id # Unique identifier
cdp_url = session.cdp_url() # Chrome DevTools Protocol URL
page = session.page # Playwright page object
# Session status
status = session.status() # Get current status
# Viewing
session.viewer() # Open live viewer in browser
session.viewer_cdp() # Open CDP debugger
session.viewer_notebook() # Display in Jupyter notebook
# Cookies
cookies = session.get_cookies()
session.set_cookies(cookies=cookies)
session.stop()
# Replay
replay = session.replay() # Get replay after session ends
replay.download("session.mp4")
```
## Headless Mode
Control whether to run the browser visibly or in the background:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Headless mode (no viewer)
with client.Session(headless=True) as session:
page = session.page
page.goto("https://example.com")
# Non-headless (opens live viewer automatically)
with client.Session(headless=False) as session:
page = session.page
page.goto("https://example.com")
# Viewer opens automatically in your browser
```
When `headless=False`, a live viewer automatically opens in your browser so you can watch the automation in real-time.
## Proxies
Route sessions through residential proxies for geo-targeting and enhanced stealth:
```python proxies_simple.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(proxies=True) as session:
page = session.page
page.goto("https://example.com")
```
See the [Proxies Guide](/features/sessions/proxies) for country-specific proxies, custom proxies, and troubleshooting.
## Captcha Solving
Automatically detect and solve captchas during automation:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(
solve_captchas=True,
) as session:
page = session.page
page.goto("https://www.google.com/recaptcha/api2/demo")
# Captchas are automatically solved
```
See the [Captcha Solving](/features/sessions/captcha-solving) guide for more details.
## Session Timeout
Configure how long sessions stay active:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Session closes after 10 minutes of inactivity
with client.Session(timeout_minutes=10) as session:
page = session.page
page.goto("https://example.com")
```
The timeout range is 1-30 minutes. Sessions automatically close when the timeout is reached.
## Custom Viewport Size
Set custom screen dimensions for specific testing scenarios:
```python Python theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# 4K resolution
with client.Session(
viewport_width=3840,
viewport_height=2160
) as session:
page = session.page
page.goto("https://example.com")
```
## Cookie Management
Automatically load and save cookies across sessions using the `cookie_file` parameter:
```python cookie_file.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
with client.Session(cookie_file="cookies.json") as session:
page = session.page
page.goto("https://example.com")
# Cookies auto-loaded at start, auto-saved when session ends
```
See the [Cookies Guide](/features/sessions/cookies) for manual cookie management and best practices.
## External Providers (CDP)
Use Notte with external browser providers like Kernel.sh:
```python Python theme={null}
from notte_sdk import NotteClient
from kernel import Kernel
client = NotteClient()
kernel = Kernel()
# Create browser on Kernel
kernel_browser = kernel.browsers.create()
# Connect Notte to Kernel's browser
with client.Session(cdp_url=kernel_browser.cdp_ws_url) as session:
page = session.page
page.goto("https://example.com")
```
See the [Kernel.sh Integration](/integrations/kernel) guide for complete setup instructions.
## Next Steps
Watch recorded sessions and debug issues
Configure proxies and anti-detection features
Watch sessions in real-time
Persist authentication across sessions
# Cookies
Source: https://docs.notte.cc/features/sessions/cookies
Persist authentication and manage cookies across sessions
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
Cookies allow you to persist authentication state across sessions, avoiding repeated logins and maintaining session continuity.
## Automatic Persistence
The simplest approach is automatic cookie persistence using `cookie_file`:
```python automatic_persistence.py theme={null}
from notte_sdk import NotteClient
client = NotteClient()
# Cookies automatically loaded at start, saved when session ends
with client.Session(cookie_file="cookies.json") as session:
page = session.page
page.goto("https://example.com/login")
# Log in once, cookies are captured
page.fill('input[name="email"]', "user@example.com")
page.fill('input[name="password"]', "password")
page.click('button[type="submit"]')
# Next time: already logged in!
with client.Session(cookie_file="cookies.json") as session:
page = session.page
page.goto("https://example.com/dashboard")
# Authentication persisted from previous session
```
The `cookie_file` parameter handles everything automatically - loading cookies when the session starts and saving them when it ends.
## Manual Cookie Management
For more control, use `set_cookies()` and `get_cookies()`:
```python manual_cookie_management.py theme={null}
import json
from notte_sdk import NotteClient
client = NotteClient()
# Save cookies from a session
with client.Session() as session:
page = session.page
page.goto("https://example.com")
# Perform login...
# Get and save cookies
cookies = session.get_cookies()
with open("cookies.json", "w") as f:
json.dump(cookies, f)
# Load cookies in a new session
with client.Session() as session:
with open("cookies.json", "r") as f:
cookies = json.load(f)
session.set_cookies(cookies=cookies)
page = session.page
page.goto("https://example.com/dashboard")
# Already authenticated
```
## Uploading Cookies
Upload cookies from an existing file:
```python upload_cookies.py theme={null}
from typing import Any
from notte_sdk import NotteClient
# Upload cookies for github.com to automatically login
cookies: list[dict[str, Any]] = [
{
"name": "sb-db-auth-token",
"value": "base64-cookie-value",
"domain": "github.com",
"path": "/",
"expires": 9778363203.913704,
"httpOnly": False,
"secure": False,
"sameSite": "Lax",
}
]
# create a new session
client = NotteClient()
with client.Session() as session:
_ = session.set_cookies(cookies=cookies) # type: ignore[arg-type] # can also set cookie_file="path/to/cookies.json"
# Use the cookies in your session
agent = client.Agent(session=session, max_steps=5)
res = agent.run(
task="go to nottelabs/notte get repo info. Fail if you are not logged in",
url="https://github.com/nottelabs/notte",
)
# or get the cookies from the session
cookies_resp = session.get_cookies()
```
### Cookie File Format
Cookies must be a valid JSON array:
```json theme={null}
[
{
"name": "session_id",
"value": "abc123",
"domain": ".example.com",
"path": "/",
"expires": 1735689600,
"httpOnly": true,
"secure": true
}
]
```
## Extracting Cookies
### From Your Browser
Export cookies from your browser:
```python extract_cookies_local.py theme={null}
import json
from pathlib import Path
from patchright.sync_api import sync_playwright
cookie_path = Path("github_cookies.json")
# Initialize Playwright
with sync_playwright() as playwright:
browser = playwright.chromium.launch(headless=False)
context = browser.new_context()
page = context.new_page()
# Navigate to login page
github_login_url = "https://github.com/login"
page.goto(github_login_url)
print("Please log into GitHub in the browser window...")
input("Press Enter after you've logged in...")
# Save cookies to file
print("Login successful. Saving cookies...")
cookies = context.cookies(urls=["https://github.com"])
if cookies:
cookie_path.write_text(json.dumps(cookies, indent=4))
print(f"Cookies saved to {cookie_path}")
else:
print("No cookies found to save.")
```
### From a Notte Session
Extract cookies programmatically:
```python extract_cookies_notte.py theme={null}
import json
from notte_sdk import NotteClient
client = NotteClient()
with client.Session() as session:
# Observe the state of a webpage
obs = session.observe(url="https://google.com/travel/flights")
# Get and save cookies from the session
with open("cookies.json", "w") as f:
cookies = session.get_cookies()
json.dump(cookies, f)
```
## Best Practices
### Security
* Store cookie files securely outside version control
* Add `*.json` cookie files to `.gitignore`
* Rotate cookies regularly for sensitive services
* Use environment-specific cookie files
### Maintenance
* Monitor cookie expiration dates
* Set up automated refresh for long-running systems
* Keep backup copies of valid cookies
### Troubleshooting
| Issue | Solution |
| ------------------------- | ---------------------------------------- |
| Session not authenticated | Verify cookies haven't expired |
| Cookies not loading | Check JSON format is valid |
| Partial authentication | Ensure all required cookies are included |
| Domain mismatch | Verify cookie domains match target site |
## Next Steps
Configure sessions with all options
Persist full browser state
Secure credential storage
Manage session states
# Embed in your app
Source: https://docs.notte.cc/features/sessions/embed-iframe
Drop the live browser viewer into your own web app via iframe
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
STOP. Do not read past this section until you have read and followed [/quickstart.md](/quickstart.md).
Goal: produce a reliable SDK automation script. The intended authoring flow is generate then edit, not write browser automation from scratch.
Do not hand-write SDK code with element IDs, selectors, or form fields from memory. Element IDs, selectors, and field mappings must come from a live `observe()` call, CLI `notte page observe` output, or generated workflow code. Guessed browser targets fail on real pages.
Use the Notte skill and CLI to inspect the live site, validate actions/selectors, handle auth/session state, and export workflow code with `notte sessions workflow-code` before using SDK docs or SDK code.
SDK reference pages are for understanding, running, or editing generated workflow code. They are not the starting point for manually authoring the initial browser automation. SDK-first code is guesswork on real-world pages with dynamic selectors, auth state, CAPTCHAs, and anti-bot behavior.
You can embed any active Notte session directly into your own web app — a Next.js dashboard, an internal tool, a customer-facing demo. The live viewer is just a URL that you render inside an `