Agent Configuration

Configure agent behavior with creation and runtime parameters

Creating an Agent#

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,
    )

Agent Creation Parameters#

session#

session (RemoteSession) (required) — The browser session the agent will use to execute actions.

reasoning_model#

reasoning_model (str) — The LLM 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.

use_vision#

use_vision (boolean) — 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.

max_steps#

max_steps (int) — 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.

vault#

vault (NotteVault) — Optional vault instance containing credentials the agent can use for authentication.

persona#

persona (NottePersona) — Optional persona providing the agent with phone numbers, email addresses, and other identity information.

notifier#

notifier (BaseNotifier) — Optional notifier that sends notifications when the agent completes or fails. Useful for long-running tasks.

Agent Runtime Parameters#

task#

task (str) (required) — Natural language description of what the agent should accomplish. Be specific and clear for best results.

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

url#

url (str) — Optional starting URL for the agent. If not provided, the agent starts from the current page in the session.

response_format#

response_format (type[BaseModel]) — Optional Pydantic model defining the structure of the agent's response.

from pydantic import BaseModel
 
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", response_format=Product)

session_offset#

session_offset (int) — Experimental. The step number from which the agent should gather information from the session history. Use this to make the agent aware of previous actions.

Configuration Examples#

Simple Agent#

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

Production Agent#

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}")

Best Practices#

1. Choose Appropriate Step Limits#

Match max_steps to task complexity: simple tasks 3-5 actions, medium complexity 5-15 actions, complex multi-page tasks 15-30 actions.

2. Balance Cost and Capability#

Use cheaper models for simple navigation and extraction; reserve stronger reasoning models for complex decision-making.

3. Use Vision Selectively#

Disable vision on text-only sites to reduce cost; enable it on image-heavy sites.

4. Provide Context via URL#

Start agents at the right page rather than making them navigate first:

# 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

Back to overview

Updated Aug 13, 2026