Agent Configuration

AI agent instructions

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

Configure agents with parameters that control their reasoning model, step limits, vision capabilities, and more.

Creating an Agent

Create an agent with configuration parameters:

from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    agent = client.Agent(
        session=session,
        reasoning_model="gemini/gemini-3.5-flash",
        use_vision=True,
        max_steps=15,
        # vault=vault,  # Optional
        # persona=persona,  # Optional
    )

await client.Session().use(async session => {
  const agent = client.Agent({
    session,
    reasoning_model: 'gemini/gemini-3.5-flash',
    use_vision: true,
    max_steps: 15,
    // vault, // Optional
    // persona, // Optional
  });
  // Use the agent here, while its session is active.
});

Agent Creation Parameters

Parameters set when creating the agent instance.

session

RemoteSession

required

The browser session the agent will use to execute actions. Must be a Notte session instance.

with client.Session(open_viewer=True) as session:
    agent = client.Agent(session=session)

await client.Session({ open_viewer: true }).use(async session => {
  const agent = client.Agent({ session });
  // Use the agent here, while its session is active.
});

reasoning_model

str

default:"gemini/gemini-3.5-flash"

The large language model used for agent reasoning and decision-making. Supported models: gemini/gemini-3.5-flash, vertex_ai/gemini-3.5-flash, openai/gpt-4o, anthropic/claude-sonnet-4-5-20250929, openrouter/google/gemma-3-27b-it, cerebras/gpt-oss-120b, groq/gpt-oss-120b, perplexity/sonar-pro, deepseek/deepseek-r1, together_ai/meta-llama/llama-3.3-70b-instruct, moonshot/kimi-k2.5, xai/grok-4.3, and minimax/minimax-m2.5.

agent = client.Agent(session=session, reasoning_model="anthropic/claude-sonnet-4-5-20250929")

const agent = client.Agent({ session, reasoning_model: 'anthropic/claude-sonnet-4-5-20250929' });

use_vision

boolean

default:true

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.

agent = client.Agent(
    session=session,
    use_vision=True,  # Agent can understand images
)

const agent = client.Agent({
  session,
  use_vision: true, // Agent can understand images
});

max_steps

int

default:"20"

Maximum number of steps the agent can take before stopping. Must be between 1 and 150. Higher values allow more complex tasks but increase cost and execution time.

agent = client.Agent(
    session=session,
    max_steps=40,  # Allow up to 40 steps (default: 20)
)

const agent = client.Agent({
  session,
  max_steps: 40, // Allow up to 40 steps (default: 20)
});

vault

NotteVault

Optional vault instance containing credentials the agent can use for authentication. See Vaults for details.

param_vault.py

vault = client.Vault(vault_id="vault_123")

agent = client.Agent(
    session=session,
    vault=vault,  # Agent can access vault credentials
)

persona

NottePersona

Optional persona providing the agent with phone numbers, email addresses, and other identity information. See Personas for details.

param_persona.py

persona = client.Persona(persona_id="persona_456")

agent = client.Agent(
    session=session,
    persona=persona,  # Agent can use persona information
)

notifier

BaseNotifier

Optional notifier that sends a message with the agent’s result when it completes or fails. Useful for long-running tasks. Email, Slack, and Discord notifiers are available in the notte-integrations package (EmailNotifier, SlackNotifier, DiscordNotifier in notte_integrations.notifiers). The notifier configuration, including any credentials it contains, is sent to Notte so the notification can be delivered when the agent finishes. You can also pass the configuration as a plain dict with notifier_config, as in the example below.

with client.Session() as session:
    # Sends an email with the result when the agent finishes
    agent = client.Agent(
        session=session,
        notifier_config={
            "type": "email",
            "config": {
                "smtp_server": "smtp.example.com",
                "sender_email": "agent@example.com",
                "sender_password": "your-smtp-password",
                "receiver_email": "you@example.com",
            },
        },
    )

await client.Session().use(async session => {
  // Sends an email with the result when the agent finishes
  const agent = client.Agent({
    session,
    notifier_config: {
      type: 'email',
      config: {
        smtp_server: 'smtp.example.com',
        sender_email: 'agent@example.com',
        sender_password: 'your-smtp-password',
        receiver_email: 'you@example.com',
      },
    },
  });
  // Use the agent here, while its session is active.
});

Agent Runtime Parameters

Parameters provided when running the agent.

task

str

required

Natural language description of what the agent should accomplish. Be specific and clear for best results.

param_task.py

result = agent.run(task="Find the cheapest laptop under $1000 and add it to cart")

url

str

Optional starting URL for the agent. If not provided, the agent starts from the current page in the session.

param_url.py

result = agent.run(task="Extract pricing information", url="https://example.com/products")

response_format

type[BaseModel]

Optional Pydantic model defining the structure of the agent’s response. Use this to get type-safe, structured output. See Structured Output for details.

param_response_format.py

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)

Advanced Configuration

session_offset

int

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.

param_session_offset.py

# 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:

simple_agent.py

with client.Session() as session:
    agent = client.Agent(session=session)
    result = agent.run(task="Find contact email")

Production Agent

Full configuration for production use:

production_agent.py

from notte_sdk import NotteClient

client = NotteClient()

vault = client.Vault(vault_id="prod_vault")
persona = client.Persona(persona_id="prod_persona")

with client.Session(proxies=True) as session:
    agent = client.Agent(
        session=session,
        reasoning_model="anthropic/claude-sonnet-4-5-20250929",
        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:

structured_extraction.py

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-3.5-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:

# 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

// Simple task (3-5 actions)
let maxSteps = 5;

// Medium complexity (5-15 actions)
maxSteps = 15;

// Complex multi-page task (15-30 actions)
maxSteps = 30;

2. Balance Cost and Capability

Use cheaper models for simple tasks:

# Simple navigation and extraction
reasoning_model = "gemini/gemini-3.5-flash"

# Complex reasoning and decision-making
reasoning_model = "anthropic/claude-sonnet-4-5-20250929"

// Simple navigation and extraction
let reasoningModel = 'gemini/gemini-3.5-flash';

// Complex reasoning and decision-making
reasoningModel = 'anthropic/claude-sonnet-4-5-20250929';

3. Use Vision Selectively

Disable vision when not needed to reduce costs:

# Text-only site
text_agent = client.Agent(session=session, use_vision=False)

# Image-heavy site
agent = client.Agent(session=session, use_vision=True)

// Text-only site
const textAgent = client.Agent({ session, use_vision: false });

// Image-heavy site
const agent = client.Agent({ session, use_vision: true });

4. Provide Context via URL

Start agents at the right page:

bp_url_context.py

# 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

Lifecycle

Learn about agent execution modes

Replay & Debugging

Debug agents with visual replays

Structured Output

Get typed responses from agents

Vaults

Store credentials for agent use

Getting Started

Sessions

Authentication

Functions

Web API

Guides

Agent Configuration

Creating an Agent

Agent Creation Parameters

session

reasoning_model

use_vision

max_steps

vault

persona

notifier

Agent Runtime Parameters

task

url

response_format

session_offset

Configuration Examples

Simple Agent

Production Agent

Structured Data Extraction

Best Practices

1. Choose Appropriate Step Limits

2. Balance Cost and Capability

3. Use Vision Selectively

4. Provide Context via URL

Next Steps

Lifecycle

Replay & Debugging

Structured Output

Vaults

​Creating an Agent

​Agent Creation Parameters

​session

​reasoning_model

​use_vision

​max_steps

​vault

​persona

​notifier

​Agent Runtime Parameters

​task

​url

​response_format

​session_offset

​Configuration Examples

​Simple Agent

​Production Agent

​Structured Data Extraction

​Best Practices

​1. Choose Appropriate Step Limits

​2. Balance Cost and Capability

​3. Use Vision Selectively

​4. Provide Context via URL

​Next Steps

Lifecycle

Replay & Debugging

Structured Output

Vaults

Creating an Agent

Agent Creation Parameters

session

reasoning_model

use_vision

max_steps

vault

persona

notifier

Agent Runtime Parameters

task

url

response_format

session_offset

Configuration Examples

Simple Agent

Production Agent

Structured Data Extraction

Best Practices

1. Choose Appropriate Step Limits

2. Balance Cost and Capability

3. Use Vision Selectively

4. Provide Context via URL

Next Steps