AI agent instructions
AI agent instructions
use() callback starts the session and stops it when the callback finishes, including when it throws.
Usage
See more operations on sessions:Scrape
Scrape the current page.With
response_format or instructions, the extracted data is returned
directly and a failed extraction throws ScrapeFailedError. Pass
raiseOnFailure: false to receive the StructuredData wrapper instead.Observe
Observe the current page: the list of actions that can be taken, a
screenshot and page metadata.The
perception_type defaults to the session option (fast). A bare
string argument is accepted as the perception type.Deprecated: perception_type: 'deep' and instructions are removed on
December 1, 2026, and each warns once per session. Use perception_type: 'fast' (the default) instead of 'deep'. For instructions:
<<ALTERNATIVE FOR instructions: session.act() — pending>>. See https://docs.notte.cc/features/sessions/observe-migrationExecute
Execute an action on the current page.When the action fails and
raiseOnFailure is true (the default, see the
session option), the structured exception_detail returned by the API is
rehydrated into an ActionExecutionError whose errorType names the
server-side error class. captcha_solve actions get a 100 s request
timeout and are retried up to 3 times on HTTP 408.Parameters
Use the defaults or pass these options toclient.Session(options):
boolean | undefined
Wait in the SDK for managed authentication on start(). Defaults to true; use() always waits.
number | undefined
Additional server-side login attempts, from 0 to 2. Only sent with auth_ids.
boolean | undefined
deprecated:Remote sessions always use the supported browser launch mode.
Retained as a boolean so existing typed configuration still compiles.
true is discarded; false raises a migration error when starting.boolean | undefined
Open the live viewer in the local default browser after the session starts.
This is a local SDK option and is not sent to the API.
boolean | undefined
Default for
execute(): throw ActionExecutionError when an action fails.
The counterpart of raise_on_failure on RemoteSession. Defaults to true.PerceptionType | undefined
Default perception type for
observe(). Defaults to fast. 'deep' is
deprecated and removed on December 1, 2026; use 'fast'.string | undefined
JSON cookie file: loaded into the session on
start() when it exists and
appended with the session cookies on stop().RemoteFileStorage | undefined
File storage to attach to the session for uploads and downloads.
boolean | undefined
Whether to try to automatically solve captchas
number | undefined
Maximum session lifetime in minutes (absolute maximum, not affected by activity).
number | undefined
Idle timeout in minutes. Session closes after this period of inactivity (resets on each operation).
boolean | (NotteProxy | ExternalProxy | TailnetProxy)[] | undefined
List of custom proxies to use for the session. If True, the default proxies will be used.
"chromium" | "chrome" | "chrome-nightly" | "chrome-turbo" | undefined
The browser type to use. Supported values are chromium and chrome. chrome-nightly and chrome-turbo are legacy aliases for chrome.
string | null | undefined
The user agent to use for the session
string[] | null | undefined
Overwrite the chrome instance arguments
number | null | undefined
Viewport width in pixels (minimum 500). Set together with viewport_height.
number | null | undefined
Viewport height in pixels (minimum 500). Set together with viewport_width.
"5:4" | "16:9" | null | undefined
Viewport shape preset. When set, the backend fits the largest rectangle of this aspect ratio inside the sampled available screen area. Cannot be combined with explicit viewport_width/viewport_height.
string | null | undefined
The CDP URL of another remote session provider.
SessionProfile | null | undefined
Browser profile configuration for state persistence
boolean | undefined
Whether to use web bot authentication.
{ [key: string]: string; } | null | undefined
Extra HTTP headers to be sent with every request.
string | null | undefined
The vault to use for the session
string[] | undefined
Managed Auth connection IDs to verify and, when necessary, authenticate inside this session. Initial verification runs before returning; when login is needed, the session returns as authenticating. Poll /sessions/{id}/auth for readiness.
boolean | undefined
Block ads and trackers in managed browsers using Basic filtering. Set false to disable. Does not configure externally supplied CDP browsers.
boolean | undefined
Enable Notte’s highest-fidelity browser environment for sites with sophisticated bot detection. Available to approved workspaces.
"raw" | "full" | "last_action" | undefined
Ignored since notte 1.10: screenshots are returned without highlighting.deprecated:
boolean | undefined
Whether to enable the Notte recorder extension for this session. The extension is installed but remains inactive when this is false.
boolean | undefined
Save session replay. False permanently disables saved replay; Live View remains available.
boolean | undefined
Save browser session logs. False permanently disables saved logs, without disabling metering.
Direct constructor reference
Direct constructor reference