Notte SDK

https://www.npmjs.com/package/notte-sdk
Admin
Notte SDK is a TypeScript SDK providing cloud-hosted browser sessions with LLM-powered web agents...
Tokens:20,123
Snippets:186
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install SDK Dependencies

Source: https://www.npmjs.com/package/notte-sdk?activeTab=dependencies

Command to install all necessary project dependencies using npm.

```bash
npm install
```

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

### Install notte-sdk

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Install the package via npm.

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

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

### Install SDK Dependencies

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Installs all necessary project dependencies using npm. This is a prerequisite for building and testing the SDK.

```bash
# Install dependencies
npm install
```

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

### Install Notte SDK

Source: https://www.npmjs.com/package/notte-sdk?activeTab=dependencies

Command to install the Notte SDK package using npm.

```bash
npm i notte-sdk
```

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

### Install Notte SDK

Source: https://www.npmjs.com/package/notte-sdk?activeTab=readme

Install the notte-sdk package using npm. This is the primary command for adding the SDK to your project.

```bash
`npm i notte-sdk`
```

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

### Agent with Zod Schema

Source: https://www.npmjs.com/package/notte-sdk?activeTab=readme

Example of using Zod schemas for structured answers with the agent.

```APIDOC
## Agent with Zod Schema

### Description
Demonstrates how to use Zod schemas with `agent.start()` and `agent.run()` for structured and validated responses. The SDK converts Zod schemas to JSON Schemas for API interaction. The `answer` from `run()` is validated against the provided schema.

### Request Example
```javascript
import { z } from 'zod';

const Answer = z.object({ title: z.string(), summary: z.string() });

await notte.Session().use(async (session) => {
  const agent = notte.Agent({ session, max_steps: 5 });
  const result = await agent.run({
    task: 'Go to notte.cc and return the page title and summary',
    response_format: Answer,
  });
  // result.answer is typed as { title: string; summary: string } and validated
  console.log(result.answer.title);
});
```
```

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

### Agent with Vault Integration

Source: https://www.npmjs.com/package/notte-sdk?activeTab=dependencies

Example of using an agent with integrated vault for automatic credential management during tasks.

```APIDOC
## Agent with Vault Integration

### Description
This example demonstrates how an agent can leverage a Secret Vault for automatic authentication and credential management when performing tasks that require login.

### Request Example
```javascript
// Assuming 'vault' is an initialized Notte Vault object
// and 'notte' is an initialized NotteClient object

await notte.Session().use(async (session) => {
  const agent = notte.Agent({
    session,
    vault_id: vault.vaultId // Agent will use this vault for authentication
  });

  const result = await agent.run({
    task: "Login to GitHub and create a new repository",
    url: "https://github.com/login"
  });
});
```

### Response
#### Success Response (200)
- **answer** (any) - The result of the agent's task after successful execution and authentication using the specified vault.
```

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

### Agent with Structured Answers

Source: https://www.npmjs.com/package/notte-sdk?activeTab=dependents

Example of using Zod schemas for structured and validated agent responses.

```APIDOC
## Agent with Structured Answers using Zod

### Description
Demonstrates how to use Zod schemas with `agent.start()` and `agent.run()` to ensure structured and validated JSON responses from the agent. The SDK converts the Zod schema to JSON Schema for API interaction, and the final answer is validated against the provided schema.

### Request Example
```javascript
import { z } from 'zod';

const Answer = z.object({
  title: z.string(),
  summary: z.string()
});

await notte.Session().use(async (session) => {
  const agent = notte.Agent({ session, max_steps: 5 });
  const result = await agent.run({
    task: 'Go to notte.cc and return the page title and summary',
    response_format: Answer,
  });
  // result.answer is typed as { title: string; summary: string } and validated
  console.log(result.answer.title);
});
```

### Response Example
```json
{
  "answer": {
    "title": "Notte.cc - Secure AI Operations",
    "summary": "Notte provides tools for secure and efficient AI operations, including credential management and agent task execution."
  }
}
```
```

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

### Session Management with Context Manager

Source: https://www.npmjs.com/package/notte-sdk

Utilizes the context manager pattern for session management, ensuring automatic start and stop of the browser session. This is the recommended way to handle sessions for reliable resource cleanup.

```typescript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Context manager pattern (automatic start/stop)
await notte.Session({ timeoutMinutes: 30 }).use(async (session) => {
  // Session is automatically started
  console.log('Session ID:', session.getId());

  const status = await session.status();
  console.log('Session status:', status);

  // Session is automatically stopped when done
});
```

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

### Structured Answers with Zod

Source: https://www.npmjs.com/package/notte-sdk?activeTab=dependencies

Example of using Zod schemas for structured data validation with agent.run().

```APIDOC
## Structured Answers with Zod

### Description
Both `agent.start()` and `agent.run()` accept a Zod schema as `response_format`. The SDK converts this to a JSON Schema before calling the API. For `agent.run()`, the final answer is validated against the provided schema and typed accordingly.

### Request Example
```javascript
import { z } from 'zod';

const Answer = z.object({
  title: z.string(),
  summary: z.string()
});

await notte.Session().use(async (session) => {
  const agent = notte.Agent({ session, max_steps: 5 });
  const result = await agent.run({
    task: 'Go to notte.cc and return the page title and summary',
    response_format: Answer,
  });
  // result.answer is typed as { title: string; summary: string } and validated
  console.log(result.answer.title);
});
```

### Response
#### Success Response (200)
- **answer** (object) - The validated and typed answer from the agent, conforming to the provided Zod schema.
```

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

### TypeScript Type Inference Example

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Demonstrates TypeScript's strong type inference capabilities within the Notte SDK. Imported types like `SessionStatus` and `AgentResponse` are correctly inferred.

```typescript
import { NotteClient, SessionStatus, AgentResponse } from 'notte-sdk';

const notte = new NotteClient();

// All types are properly inferred
await notte.Session().use(async (session) => {
  const status: SessionStatus = await session.status();
  const agent = notte.Agent({ session });
  const response: AgentResponse = await agent.run("task");
});
```

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

### Manual Session Management

Source: https://www.npmjs.com/package/notte-sdk

Manages browser sessions manually by explicitly calling start() and stop() methods. This approach requires careful handling of potential errors to ensure the session is always stopped.

```typescript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Manual session management
const session = notte.Session();
await session.start();
try {
  const status = await session.status();
  console.log('Session status:', status);
} finally {
  await session.stop();
}
```

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

### Build the SDK

Source: https://www.npmjs.com/package/notte-sdk?activeTab=dependencies

Command to build the Software Development Kit.

```bash
npm run build
```

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

### Build and Test SDK

Source: https://www.npmjs.com/package/notte-sdk

Common CLI commands for managing dependencies, building, and testing the SDK.

```bash
# Install dependencies
npm install

# Generate client from OpenAPI spec
npm run generate

# Build the SDK
npm run build

# Run tests
npm test

# Type checking
npm run typecheck
```

```bash
# Run all tests
npm test

# Run tests with coverage
npm run test -- --coverage

# Run specific test file
npm run test src/test/client.test.ts
```

```bash
# Regenerate client code
npm run generate
```

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

### Legacy Client Creation Methods

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Demonstrates two legacy methods for creating and configuring the client for backward compatibility. Ensure correct base URL and API key are provided.

```typescript
import { createClient, client } from 'notte-sdk';

// Legacy method 1
const legacyClient = createClient({
  baseUrl: 'https://api.notte.cc',
  token: 'your-api-key'
});

// Legacy method 2
import { client } from 'notte-sdk';
client.setConfig({ baseUrl: 'https://api.notte.cc' });
client.interceptors.request.use((request) => {
  request.headers.set('Authorization', 'Bearer your-api-key');
  return request;
});
```

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

### Legacy Client Creation with Notte SDK

Source: https://www.npmjs.com/package/notte-sdk?activeTab=versions

Demonstrates two legacy methods for creating and configuring the Notte client for backward compatibility.

```typescript
import { createClient, client } from 'notte-sdk';

// Legacy method 1
const legacyClient = createClient({
  baseUrl: 'https://api.notte.cc',
  token: 'your-api-key'
});
```

```typescript
import { client } from 'notte-sdk';
client.setConfig({ baseUrl: 'https://api.notte.cc' });
client.interceptors.request.use((request) => {
  request.headers.set('Authorization', 'Bearer your-api-key');
  return request;
});
```

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

### Build the SDK

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Compiles the SDK source code into distributable files. This command is typically run before publishing or deploying the SDK.

```bash
# Build the SDK
npm run build
```

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

### Agent Execution and Status

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Execute agent tasks using non-blocking start or blocking run methods with status checks.

```typescript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

await notte.Session().use(async (session) => {
  const agent = notte.Agent({
    session,
    max_steps: 10
  });

  // Non-blocking: start agent and get ID
  const agentId = await agent.start("Navigate to Google and search for 'TypeScript'");
  console.log('Agent started:', agentId);

  // Check agent status
  const status = await agent.status();
  console.log('Agent status:', status);

  // Blocking: run agent and wait for completion with live updates
  const response = await agent.run(
    "Find the latest TypeScript documentation",
    (update) => {
      if (update.type === 'step') {
        console.log(`Step update:`, update.data);
      } else if (update.type === 'completion') {
        console.log(`Completed:`, update.data);
      }
    }
  );

  console.log('Final result:', response);
});
```

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

### Run SDK Tests

Source: https://www.npmjs.com/package/notte-sdk?activeTab=dependencies

Command to execute all the tests for the SDK.

```bash
npm test
```

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

### Python SDK Session and Agent Usage

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Illustrates equivalent patterns in the Python SDK for managing sessions using a context manager and running an agent for a specific task. Note the use of `timeout_minutes` for sessions.

```python
from notte_sdk import NotteClient

notte = NotteClient()

# Session context manager
with notte.Session(timeout_minutes=2) as session:
    status = session.status()
    print(status)

# Agent usage
with notte.Session() as session:
    agent = notte.Agent(session=session, max_steps=10)
    response = agent.run(task="Find the best italian restaurant in SF")
    print(f"Agent completed: {response.success}, answer: {response.answer}")
```

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

### Basic Session Usage

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Initialize the NotteClient and use a session with automatic cleanup.

```typescript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient({
  apiKey: 'your-api-key', // pragma: allowlist secret
  baseUrl: 'https://api.notte.cc' // optional, defaults to https://api.notte.cc
});

// Use session with automatic cleanup (mirrors Python's context manager)
await notte.Session({ timeoutMinutes: 30 }).use(async (session) => {
  const status = await session.status();
  console.log('Session status:', status);
});
```

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

### Legacy Client Creation with createClient

Source: https://www.npmjs.com/package/notte-sdk?activeTab=readme

Use the legacy createClient function for backward compatibility to initialize the client with base URL and token.

```typescript
import { createClient, client } from 'notte-sdk';

// Legacy method 1
const legacyClient = createClient({
  baseUrl: 'https://api.notte.cc',
  token: 'your-api-key'
});
```

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

### Create and Manage Personas with Notte SDK

Source: https://www.npmjs.com/package/notte-sdk

Demonstrates creating a new persona, accessing its information, reading emails and SMS, using it with agents for account creation, adding credentials, and cleaning up. Use this for managing digital identities and automating signups.

```javascript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Create a new persona with vault and phone number
const persona = notte.Persona({
  create_vault: true,
  create_phone_number: true
});

// Get persona information
console.log(`Email: ${persona.info.email}`);
console.log(`Phone: ${persona.info.phone_number}`);

// Read emails sent to the persona
const emails = await persona.emails({
  limit: 10,
  only_unread: true
});
console.log(`Received ${emails.length} new emails`);

// Read SMS messages for 2FA codes
const smsMessages = await persona.sms({
  limit: 5,
  only_unread: true
});
console.log(`Received ${smsMessages.length} SMS messages`);

// Use with agents for automated account creation
await notte.Session().use(async (session) => {
  const agent = notte.Agent({
    session,
    vault_id: persona.vault.vaultId // Agent will use persona's vault
  });

  const result = await agent.run(
    `Create an account on GitHub using the persona credentials`
  );
  console.log(`Account created: ${result.success}`);
});

// Access existing persona
const existingPersona = notte.Persona({ persona_id: 'persona-abc-123' });
const personaEmails = await existingPersona.emails();

// Add credentials to persona's vault
await persona.addCredentials('https://github.com/');
// This automatically generates a secure password and stores:
// - Email: persona's email
// - Password: generated secure password

// Cleanup
await persona.stop(); // Deletes persona and all associated data
```

```javascript
const options = {
  limit: 10,
              // Maximum number of messages (default: unlimited)
  only_unread: true,
              // Only return unread messages (default: false)
  timedelta: '1h'         // Maximum age of messages (e.g., '1h', '30m', '24h')
};

const emails = await persona.emails(options);
const sms = await persona.sms(options);
```

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

### Run Notte Functions with Input Variables

Source: https://www.npmjs.com/package/notte-sdk?activeTab=dependencies

Shows how to initialize and run a Notte Function with specific input variables and retrieve its execution results. Use this for executing serverless workflows on Notte's infrastructure.

```javascript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Create a function instance
const fn = notte.NotteFunction({
  function_id: 'your-function-id',
  decryption_key: 'optional-decryption-key' // optional, for encrypted outputs
});

// Run the function with input variables
const result = await fn.run({
  url: 'https://example.com',
  query: 'extract pricing information'
});

console.log('Run ID:', result.function_run_id);

// Retrieve the run result / metadata later
const metadata = await fn.retrieve(result.function_run_id);
console.log('Status:', metadata.status); // 'active' | 'closed' | 'failed' 
console.log('Result:', metadata);
```

```javascript
const fn = notte.NotteFunction({ function_id: 'your-function-id' });
const { function_run_id } = await fn.run({ url: 'https://example.com' });

// Poll until complete
let metadata;
do {
  await new Promise(r => setTimeout(r, 2000)); // wait 2s between checks
  metadata = await fn.retrieve(function_run_id);
} while (metadata.status === 'active');

if (metadata.status === 'closed') {
  console.log('Function completed successfully:', metadata);
} else {
  console.error('Function failed:', metadata);
}
```

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

### Run All SDK Tests

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Executes the entire test suite for the SDK. This is the standard command for verifying the integrity of the codebase.

```bash
# Run all tests
npm test
```

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

### NotteClient Core Classes

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Initialize the main client and instantiate sessions, agents, vaults, and personas.

```typescript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Create sessions
const session = notte.Session({ timeoutMinutes: 30 });

// Create agents
const agent = notte.Agent({ session, max_steps: 15 });

// Create vaults
const vault = notte.Vault({ name: 'My Vault' });

// Create personas
const persona = notte.Persona({ create_vault: true });
```

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

### Run Notte Functions with Input Variables

Source: https://www.npmjs.com/package/notte-sdk

Shows how to instantiate and run a Notte Function with specific input variables and retrieve its results. Use this for executing serverless workflows on Notte's infrastructure.

```javascript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Create a function instance
const fn = notte.NotteFunction({
  function_id: 'your-function-id',
  decryption_key: 'optional-decryption-key' // optional, for encrypted outputs
});

// Run the function with input variables
const result = await fn.run({
  url: 'https://example.com',
  query: 'extract pricing information'
});

console.log('Run ID:', result.function_run_id);

// Retrieve the run result / metadata later
const metadata = await fn.retrieve(result.function_run_id);
console.log('Status:', metadata.status); // 'active' | 'closed' | 'failed'
console.log('Result:', metadata);
```

```javascript
const fn = notte.NotteFunction({ function_id: 'your-function-id' });
const { function_run_id } = await fn.run({ url: 'https://example.com' });

// Poll until complete
let metadata;
do {
  await new Promise(r => setTimeout(r, 2000)); // wait 2s between checks
  metadata = await fn.retrieve(function_run_id);
} while (metadata.status === 'active');

if (metadata.status === 'closed') {
  console.log('Function completed successfully:', metadata);
} else {
  console.error('Function failed:', metadata);
}
```

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

### Configure Agent with Session and Max Steps

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Initialize an agent with a specific session and set the maximum number of steps for its execution. The default max_steps is 10.

```typescript
const agent = notte.Agent({
  session: session,
  max_steps: 20,             // Maximum steps for agent (default: 10)
});
```

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

### Run SDK Tests

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Executes the test suite for the SDK to ensure functionality and stability. This command is crucial for verifying code changes.

```bash
# Run tests
npm test
```

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

### Generate Client from OpenAPI Spec

Source: https://www.npmjs.com/package/notte-sdk?activeTab=dependencies

Command to generate the client code based on the OpenAPI specification.

```bash
npm run generate
```

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

### Legacy Client Configuration with client.setConfig

Source: https://www.npmjs.com/package/notte-sdk?activeTab=readme

Configure the legacy client by setting the base URL and adding an authorization interceptor for the API token.

```typescript
import { client } from 'notte-sdk';
client.setConfig({ baseUrl: 'https://api.notte.cc' });
client.interceptors.request.use((request) => {
  request.headers.set('Authorization', 'Bearer your-api-key');
  return request;
});
```

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

### Session Management Patterns

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Demonstrates context manager, manual, and async iterator patterns for session lifecycle management.

```typescript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Context manager pattern (automatic start/stop)
await notte.Session({ timeoutMinutes: 30 }).use(async (session) => {
  // Session is automatically started
  console.log('Session ID:', session.getId());

  const status = await session.status();
  console.log('Session status:', status);

  // Session is automatically stopped when done
});

// Manual session management
const session = notte.Session();
await session.start();
try {
  const status = await session.status();
  console.log('Session status:', status);
} finally {
  await session.stop();
}

// Async iterator pattern
for await (const session of notte.Session({ timeoutMinutes: 15 })) {
  // Use session here
  const status = await session.status();
  console.log('Session active:', status);
  // Session automatically closed after loop
}
```

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

### Run Tests with Coverage

Source: https://www.npmjs.com/package/notte-sdk?activeTab=dependencies

Command to run tests and generate a code coverage report.

```bash
npm run test -- --coverage
```

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

### Run Tests with Coverage

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Executes the SDK tests and generates a code coverage report. This helps identify parts of the code that are not adequately tested.

```bash
# Run tests with coverage
npm run test -- --coverage
```

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

### Run Specific Test File

Source: https://www.npmjs.com/package/notte-sdk?activeTab=dependencies

Command to execute a specific test file.

```bash
npm run test src/test/client.test.ts
```

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

### TypeScript SDK Session and Agent Usage Equivalence

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Shows the TypeScript SDK's approach to session management using an async context manager (`.use()`) and agent execution, mirroring Python SDK patterns. Pay attention to the `timeoutMinutes` option.

```typescript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Session context manager equivalent
await notte.Session({ timeoutMinutes: 2 }).use(async (session) => {
  const status = await session.status();
  console.log(status);
});

// Agent usage
await notte.Session().use(async (session) => {
  const agent = notte.Agent({ session, max_steps: 10 });
  const response = await agent.run("Find the best italian restaurant in SF");
  console.log(`Agent completed: ${response.success}, answer: ${response.answer}`);
});
```

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

### Compare Python and TypeScript SDKs

Source: https://www.npmjs.com/package/notte-sdk

Demonstrates the functional parity between Python and TypeScript SDK implementations.

```python
from notte_sdk import NotteClient

notte = NotteClient()

# Session context manager
with notte.Session(timeout_minutes=2) as session:
    status = session.status()
    print(status)

# Agent usage
with notte.Session() as session:
    agent = notte.Agent(session=session, max_steps=10)
    response = agent.run(task="Find the best italian restaurant in SF")
    print(f"Agent completed: {response.success}, answer: {response.answer}")
```

```typescript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Session context manager equivalent
await notte.Session({ timeoutMinutes: 2 }).use(async (session) => {
  const status = await session.status();
  console.log(status);
});

// Agent usage
await notte.Session().use(async (session) => {
  const agent = notte.Agent({ session, max_steps: 10 });
  const response = await agent.run("Find the best italian restaurant in SF");
  console.log(`Agent completed: ${response.success}, answer: ${response.answer}`);
});
```

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

### Generate Client from OpenAPI Spec

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Generates the client code for the SDK by processing the OpenAPI specification. This command should be run after updating the API specification.

```bash
# Generate client from OpenAPI spec
npm run generate
```

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

### Execute Notte Functions

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Run serverless workflows by providing a function ID and input variables.

```javascript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Create a function instance
const fn = notte.NotteFunction({
  function_id: 'your-function-id',
  decryption_key: 'optional-decryption-key' // optional, for encrypted outputs
});

// Run the function with input variables
const result = await fn.run({
  url: 'https://example.com',
  query: 'extract pricing information'
});

console.log('Run ID:', result.function_run_id);

// Retrieve the run result / metadata later
const metadata = await fn.retrieve(result.function_run_id);
console.log('Status:', metadata.status); // 'active' | 'closed' | 'failed'
console.log('Result:', metadata);
```

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

### Run Specific Test File

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Executes a single test file within the SDK's test suite. This is useful for focused testing during development or debugging.

```bash
# Run specific test file
npm run test src/test/client.test.ts
```

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

### TypeScript SDK Agent Usage within Session

Source: https://www.npmjs.com/package/notte-sdk?activeTab=readme

This TypeScript code demonstrates agent usage within a session, mirroring the Python SDK pattern. It initializes an agent with specific parameters and runs a task.

```typescript
# Agent usage
await notte.Session().use(async (session) => {
  const agent = notte.Agent({ session, max_steps: 10 });
  const response = await agent.run("Find the best italian restaurant in SF");
  console.log(`Agent completed: ${response.success}, answer: ${response.answer}`);
});
```

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

### Session Configuration

Source: https://www.npmjs.com/package/notte-sdk?activeTab=dependencies

Configure session settings such as timeout.

```APIDOC
## Session Configuration

### Description
Configure session settings such as timeout.

### Request Example
```javascript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

const session = notte.Session({
  timeoutMinutes: 45        // Session timeout (default: 30)
  // Add other session options as supported by the API
});
```
```

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

### Python SDK Agent Usage within Session

Source: https://www.npmjs.com/package/notte-sdk?activeTab=readme

Instantiate and run an agent within a Python session context manager, specifying max steps and printing the task completion status and answer.

```python
# Agent usage
with notte.Session() as session:
    agent = notte.Agent(session=session, max_steps=10)
    response = agent.run(task="Find the best italian restaurant in SF")
    print(f"Agent completed: {response.success}, answer: {response.answer}")
```

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

### TypeScript SDK Agent Usage Equivalent

Source: https://www.npmjs.com/package/notte-sdk?activeTab=dependents

Equivalent to Python's agent usage, this TypeScript code initializes an agent within a session and runs a task, logging the response.

```javascript
// Agent usage
await notte.Session().use(async (session) => {
  const agent = notte.Agent({ session, max_steps: 10 });
  const response = await agent.run("Find the best italian restaurant in SF");
  console.log(`Agent completed: ${response.success}, answer: ${response.answer}`);
});
```

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

### Session Configuration

Source: https://www.npmjs.com/package/notte-sdk

Configure session settings for the Notte client, such as timeout duration.

```APIDOC
## Session Configuration

### Description
Configure session settings for the Notte client, such as timeout duration.

### Request Example

```javascript
const session = notte.Session({
  timeoutMinutes: 45,        // Session timeout (default: 30)
  // Add other session options as supported by the API
});
```
```

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

### Python SDK Session Context Manager

Source: https://www.npmjs.com/package/notte-sdk?activeTab=readme

Manage a session using a context manager in Python, setting a timeout and printing the session status.

```python
from notte_sdk import NotteClient

notte = NotteClient()

# Session context manager
with notte.Session(timeout_minutes=2) as session:
    status = session.status()
    print(status)
```

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

### Agent Methods

Source: https://www.npmjs.com/package/notte-sdk?activeTab=readme

Methods for controlling and interacting with the Notte agent.

```APIDOC
## Agent Methods

### `start(task)`

#### Description
Starts the agent with a given task in a non-blocking manner.

### `run(task, onUpdate?)`

#### Description
Starts the agent, waits for the task to complete, and returns the result. This is a blocking operation.

### `status()`

#### Description
Retrieves the current status of the agent.

### `stop()`

#### Description
Stops the agent.

### `getId()`

#### Description
Retrieves the unique identifier of the agent.

### `isRunning()`

#### Description
Checks if the agent is currently running.
```

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

### Create and Manage Personas with Notte SDK

Source: https://www.npmjs.com/package/notte-sdk?activeTab=versions

Use the NotteClient to create and manage personas, which represent complete digital identities. Personas can have vaults and phone numbers created automatically. Access persona information, read emails and SMS messages, and integrate with agents for automated tasks. Existing personas can also be accessed.

```javascript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Create a new persona with vault and phone number
const persona = notte.Persona({
  create_vault: true,
  create_phone_number: true
});

// Get persona information
console.log(`Email: ${persona.info.email}`);
console.log(`Phone: ${persona.info.phone_number}`);

// Read emails sent to the persona
const emails = await persona.emails({
  limit: 10,
  only_unread: true
});
console.log(`Received ${emails.length} new emails`);

// Read SMS messages for 2FA codes
const smsMessages = await persona.sms({
  limit: 5,
  only_unread: true
});
console.log(`Received ${smsMessages.length} SMS messages`);

// Use with agents for automated account creation
await notte.Session().use(async (session) => {
  const agent = notte.Agent({
    session,
    vault_id: persona.vault.vaultId // Agent will use persona's vault
  });

  const result = await agent.run(
    `Create an account on GitHub using the persona credentials`
  );
  console.log(`Account created: ${result.success}`);
});

// Access existing persona
const existingPersona = notte.Persona({ persona_id: 'persona-abc-123' });
const personaEmails = await existingPersona.emails();

// Add credentials to persona's vault
await persona.addCredentials('https://github.com/');
// This automatically generates a secure password and stores:
// - Email: persona's email
// - Password: generated secure password

// Cleanup
await persona.stop(); // Deletes persona and all associated data
```

```javascript
const options = {
  limit: 10,              // Maximum number of messages (default: unlimited)
  only_unread: true,      // Only return unread messages (default: false)
  timedelta: '1h'         // Maximum age of messages (e.g., '1h', '30m', '24h')
};

const emails = await persona.emails(options);
const sms = await persona.sms(options);
```

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

### Manage Digital Personas with Notte SDK

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Create and manage digital identities including vaults, phone numbers, and automated credential storage.

```javascript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Create a new persona with vault and phone number
const persona = notte.Persona({
  create_vault: true,
  create_phone_number: true
});

// Get persona information
console.log(`Email: ${persona.info.email}`);
console.log(`Phone: ${persona.info.phone_number}`);

// Read emails sent to the persona
const emails = await persona.emails({
  limit: 10,
  only_unread: true
});
console.log(`Received ${emails.length} new emails`);

// Read SMS messages for 2FA codes
const smsMessages = await persona.sms({
  limit: 10,
  only_unread: true
});
console.log(`Received ${smsMessages.length} SMS messages`);

// Use with agents for automated account creation
await notte.Session().use(async (session) => {
  const agent = notte.Agent({
    session,
    vault_id: persona.vault.vaultId // Agent will use persona's vault
  });

  const result = await agent.run(
    `Create an account on GitHub using the persona credentials`
  );
  console.log(`Account created: ${result.success}`);
});

// Access existing persona
const existingPersona = notte.Persona({ persona_id: 'persona-abc-123' });
const personaEmails = await existingPersona.emails();

// Add credentials to persona's vault
await persona.addCredentials('https://github.com/');
// This automatically generates a secure password and stores:
// - Email: persona's email
// - Password: generated secure password

// Cleanup
await persona.stop(); // Deletes persona and all associated data
```

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

### Handle Real-time Agent Updates via WebSocket

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Utilize the agent.run() method to receive real-time updates during task execution. Process different update types like 'step' and 'completion' using a callback function.

```typescript
const response = await agent.run("Your task", (update) => {
  switch (update.type) {
    case 'step':
      console.log(`Step ${update.data.currentStep}:`, update.data);
      break;
    case 'completion':
      console.log('Task completed:', update.data);
      break;
    default:
      console.log('Update:', update);
  }
});
```

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

### Configure Session Settings

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Set custom session parameters such as timeout duration.

```javascript
const session = notte.Session({
  timeoutMinutes: 45,        // Session timeout (default: 30)
  // Add other session options as supported by the API
});
```

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

### Perform Type Checking

Source: https://www.npmjs.com/package/notte-sdk?activeTab=dependencies

Command to check the TypeScript types within the project.

```bash
npm run typecheck
```

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

### Agent Methods

Source: https://www.npmjs.com/package/notte-sdk

Methods for controlling the lifecycle and execution of autonomous agents.

```APIDOC
## Agent Methods

### Description
Methods to manage agent execution, status, and task processing.

### Methods
- **start(task)** - Start agent with task (non-blocking)
- **run(task, onUpdate?)** - Start agent and wait for completion (blocking)
- **status()** - Get agent status
- **stop()** - Stop the agent
- **getId()** - Get agent ID
- **isRunning()** - Check if agent is running
```

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

### Agent Methods

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Methods for controlling the lifecycle and execution of autonomous agents.

```APIDOC
## Agent Methods

### Description
Methods to manage agent execution, status, and task processing.

### Methods
- **start(task)** - Start agent with task (non-blocking)
- **run(task, onUpdate?)** - Start agent and wait for completion (blocking)
- **status()** - Get agent status
- **stop()** - Stop the agent
- **getId()** - Get agent ID
- **isRunning()** - Check if agent is running

### Structured Answers
Both `start()` and `run()` accept a `response_format` (Zod schema) to validate and type the agent's output.
```

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

### Importing SDK Types

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Imports various types exported by the 'notte-sdk' package, which are generated from the OpenAPI specification. These types cover configurations, options, and data structures for different SDK components.

```typescript
import type {
  NotteClientConfig,
  SessionOptions,
  SessionStatus,
  AgentConstructor,
  AgentRunRequest,
  AgentUpdateHandler,
  VaultConstructor,
  CredentialsDict,
  CreditCardDict,
  Credential,
  PersonaConstructor,
  MessageReadOptions,
  PersonaListOptions,
  CreatePhoneNumberOptions
} from 'notte-sdk';
```

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

### Configure Message Reading Options

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Define filtering and pagination options for retrieving persona emails and SMS messages.

```javascript
const options = {
  limit: 10,              // Maximum number of messages (default: unlimited)
  only_unread: true,      // Only return unread messages (default: false)
  timedelta: '1h'         // Maximum age of messages (e.g., '1h', '30m', '24h')
};

const emails = await persona.emails(options);
const sms = await persona.sms(options);
```

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

### Function Execution API

Source: https://www.npmjs.com/package/notte-sdk?activeTab=dependencies

Run pre-built automation workflows (Notte Functions) with a simple API call. Functions are serverless workflows that run on Notte's infrastructure.

```APIDOC
## Function Execution API

### Description
Run pre-built automation workflows (Notte Functions) with a simple API call. Functions are serverless workflows that run on Notte's infrastructure — you provide the `function_id` and input variables, and get the result back.

### Methods

#### `run(variables?)`
Start a function run with optional input variables.

#### `retrieve(functionRunId)`
Get metadata/result for a specific run.

#### `getFunctionId()`
Get the function ID.

#### `functionId` (read-only property)
The function ID.

#### `decryptionKey` (read-only property)
The decryption key, if provided.

### Request Example (Run Function)
```javascript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Create a function instance
const fn = notte.NotteFunction({
  function_id: 'your-function-id',
  decryption_key: 'optional-decryption-key' // optional, for encrypted outputs
});

// Run the function with input variables
const result = await fn.run({
  url: 'https://example.com',
  query: 'extract pricing information'
});

console.log('Run ID:', result.function_run_id);
```

### Response Example (Run Result)
```json
{
  "function_run_id": "run-123-abc"
}
```

### Request Example (Retrieve Run Result)
```javascript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();
const fn = notte.NotteFunction({ function_id: 'your-function-id' });

// Retrieve the run result / metadata later
const metadata = await fn.retrieve('run-123-abc');
console.log('Status:', metadata.status); // 'active' | 'closed' | 'failed'
console.log('Result:', metadata);
```

### Response Example (Run Metadata)
```json
{
  "status": "closed",
  "result": { ... },
  "function_run_id": "run-123-abc"
}
```

### Polling for Completion
```javascript
const fn = notte.NotteFunction({ function_id: 'your-function-id' });
const { function_run_id } = await fn.run({ url: 'https://example.com' });

// Poll until complete
let metadata;
do {
  await new Promise(r => setTimeout(r, 2000)); // wait 2s between checks
  metadata = await fn.retrieve(function_run_id);
} while (metadata.status === 'active');

if (metadata.status === 'closed') {
  console.log('Function completed successfully:', metadata);
} else {
  console.error('Function failed:', metadata);
}
```
```

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

### TypeScript SDK Session Context Manager Equivalent

Source: https://www.npmjs.com/package/notte-sdk?activeTab=readme

Equivalent to Python's session context manager, this TypeScript code uses an async callback to manage the session and retrieve its status.

```typescript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Session context manager equivalent
await notte.Session({ timeoutMinutes: 2 }).use(async (session) => {
  const status = await session.status();
  console.log(status);
});
```

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

### Agent Automation

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Run an agent task within a session and receive real-time updates via WebSocket.

```typescript
import { NotteClient } from 'notte-sdk';

const notte = new NotteClient();

// Run an agent task with live updates
await notte.Session().use(async (session) => {
  const agent = notte.Agent({ session, max_steps: 10 });

  const response = await agent.run(
    "Find the best Italian restaurant in San Francisco and book a table for 2 at 7pm today",
    (update) => {
      // Receive real-time updates via WebSocket
      console.log(`Step ${update.data.currentStep}: ${update.data.message}`);
    }
  );

  console.log(`Agent completed: ${response.success ? 'Success' : 'Failed'}`);
  console.log(`Answer: ${response.answer}`);
});
```

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

### Run Agent and Handle Errors

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Execute an agent within a session context and handle potential errors during session usage or agent execution. Log detailed error messages to the console.

```typescript
try {
  await notte.Session().use(async (session) => {
    const agent = notte.Agent({ session });
    const response = await agent.run("Complete a complex task");

    if (!response.success) {
      console.error('Agent failed:', response.error);
    }
  });
} catch (error) {
  console.error('Session error:', error);
}
```

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

### Vault Methods

Source: https://www.npmjs.com/package/notte-sdk?activeTab=readme

Methods for managing credentials and data within a Secret Vault.

```APIDOC
## Vault Methods

### `addCredentials(url, credentials)`

#### Description
Stores credentials associated with a specific URL.

### `getCredentials(url)`

#### Description
Retrieves stored credentials for a given URL.

### `deleteCredentials(url)`

#### Description
Deletes credentials associated with a specific URL.

### `listCredentials()`

#### Description
Lists all stored credentials within the vault.

### `setCreditCard(card)`

#### Description
Stores credit card information.

### `getCreditCard()`

#### Description
Retrieves stored credit card information.

### `deleteCreditCard()`

#### Description
Deletes stored credit card information.

### `generatePassword(length?, includeSpecialChars?)`

#### Description
Generates a secure password with specified length and character set options.

### `delete()`

#### Description
Deletes the entire vault and all its contents.

### `stop()`

#### Description
Stops and deletes the vault.
```

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

### Regenerate SDK Client Code

Source: https://www.npmjs.com/package/notte-sdk?activeTab=code

Regenerates the client code based on the latest OpenAPI specification. This command ensures the SDK stays synchronized with the API.

```bash
# Regenerate client code
npm run generate
```
Tokens:
Raw