> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notte.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Configuration

> Configure agent behavior with creation and runtime parameters

<Tip>
  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.
</Tip>

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

## Creating an Agent

Create an agent with configuration parameters:

{/* @sniptest testers/agents/config/creating_agent.py */}

```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

<ParamField path="session" type="RemoteSession" required>
  The browser session the agent will use to execute actions. Must be a Notte session instance.
</ParamField>

{/* @sniptest testers/agents/config/param_session.py */}

```python param_session.py theme={null}
with client.Session(headless=False) as session:
    agent = client.Agent(session=session)
```

### reasoning\_model

<ParamField path="reasoning_model" type="str" default="gemini/gemini-2.0-flash">
  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`.
</ParamField>

{/* @sniptest testers/agents/config/param_reasoning_model.py */}

```python param_reasoning_model.py theme={null}
agent = client.Agent(session=session, reasoning_model="anthropic/claude-3.5-sonnet")
```

### use\_vision

<ParamField path="use_vision" type="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.
</ParamField>

{/* @sniptest testers/agents/config/param_use_vision.py */}

```python param_use_vision.py theme={null}
agent = client.Agent(
    session=session,
    use_vision=True,  # Agent can understand images
)
```

### max\_steps

<ParamField path="max_steps" type="int" default="varies">
  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.
</ParamField>

{/* @sniptest testers/agents/config/param_max_steps.py */}

```python param_max_steps.py theme={null}
agent = client.Agent(
    session=session,
    max_steps=20,  # Allow up to 20 actions
)
```

### vault

<ParamField path="vault" type="NotteVault">
  Optional vault instance containing credentials the agent can use for authentication. See [Vaults](/concepts/vaults) for details.
</ParamField>

{/* @sniptest testers/agents/config/param_vault.py */}

```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

<ParamField path="persona" type="NottePersona">
  Optional persona providing the agent with phone numbers, email addresses, and other identity information. See [Personas](/concepts/personas) for details.
</ParamField>

{/* @sniptest testers/agents/config/param_persona.py */}

```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

<ParamField path="notifier" type="BaseNotifier">
  Optional notifier that sends notifications when the agent completes or fails. Useful for long-running tasks.
</ParamField>

{/* @sniptest testers/agents/config/param_notifier.py */}

```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

<ParamField path="task" type="str" required>
  Natural language description of what the agent should accomplish. Be specific and clear for best results.
</ParamField>

{/* @sniptest testers/agents/config/param_task.py */}

```python param_task.py theme={null}
result = agent.run(task="Find the cheapest laptop under $1000 and add it to cart")
```

### url

<ParamField path="url" type="str">
  Optional starting URL for the agent. If not provided, the agent starts from the current page in the session.
</ParamField>

{/* @sniptest testers/agents/config/param_url.py */}

```python param_url.py theme={null}
result = agent.run(task="Extract pricing information", url="https://example.com/products")
```

### response\_format

<ParamField path="response_format" type="type[BaseModel]">
  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.
</ParamField>

{/* @sniptest testers/agents/config/param_response_format.py */}

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

<Accordion title="Advanced Configuration">
  ### session\_offset

  <ParamField path="session_offset" type="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.
  </ParamField>

  {/* @sniptest testers/agents/config/param_session_offset.py */}

  ```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)
  ```
</Accordion>

## Configuration Examples

### Simple Agent

Minimal configuration for basic tasks:

{/* @sniptest testers/agents/config/simple_agent.py */}

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

{/* @sniptest testers/agents/production.py */}

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

{/* @sniptest testers/agents/structured_extraction.py */}

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

{/* @sniptest testers/agents/config/bp_step_limits.py */}

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

{/* @sniptest testers/agents/config/bp_model_selection.py */}

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

{/* @sniptest testers/agents/config/bp_vision.py */}

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

{/* @sniptest testers/agents/config/bp_url_context.py */}

```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

<CardGroup cols={2}>
  <Card title="Lifecycle" icon="rotate" href="/features/agents/lifecycle">
    Learn about agent execution modes
  </Card>

  <Card title="Replay & Debugging" icon="circle-play" href="/features/agents/replay">
    Debug agents with visual replays
  </Card>

  <Card title="Structured Output" icon="brackets-curly" href="/features/agents/structured-output">
    Get typed responses from agents
  </Card>

  <Card title="Vaults" icon="vault" href="/concepts/vaults">
    Store credentials for agent use
  </Card>
</CardGroup>