> ## 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>
  Read [the Notte skill](https://notte.cc/skill.md) 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.
</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:

<CodeGroup>
  ```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-3.5-flash",
          use_vision=True,
          max_steps=15,
          # vault=vault,  # Optional
          # persona=persona,  # Optional
      )
  ```

  ```typescript creating_agent.ts theme={null}
  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.
  });
  ```
</CodeGroup>

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

<CodeGroup>
  ```python param_session.py theme={null}
  with client.Session(open_viewer=True) as session:
      agent = client.Agent(session=session)
  ```

  ```typescript param_session.ts theme={null}
  await client.Session({ open_viewer: true }).use(async session => {
    const agent = client.Agent({ session });
    // Use the agent here, while its session is active.
  });
  ```
</CodeGroup>

### reasoning\_model

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

<CodeGroup>
  ```python param_reasoning_model.py theme={null}
  agent = client.Agent(session=session, reasoning_model="anthropic/claude-sonnet-4-5-20250929")
  ```

  ```typescript param_reasoning_model.ts theme={null}
  const agent = client.Agent({ session, reasoning_model: 'anthropic/claude-sonnet-4-5-20250929' });
  ```
</CodeGroup>

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

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

  ```typescript param_use_vision.ts theme={null}
  const agent = client.Agent({
    session,
    use_vision: true, // Agent can understand images
  });
  ```
</CodeGroup>

### max\_steps

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

<CodeGroup>
  ```python param_max_steps.py theme={null}
  agent = client.Agent(
      session=session,
      max_steps=40,  # Allow up to 40 steps (default: 20)
  )
  ```

  ```typescript param_max_steps.ts theme={null}
  const agent = client.Agent({
    session,
    max_steps: 40, // Allow up to 40 steps (default: 20)
  });
  ```
</CodeGroup>

### vault

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

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

```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 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.
</ParamField>

<CodeGroup>
  ```python param_notifier.py theme={null}
  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",
              },
          },
      )
  ```

  ```typescript param_notifier.ts theme={null}
  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.
  });
  ```
</CodeGroup>

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

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

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

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

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

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

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

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

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

  ```typescript bp_step_limits.ts theme={null}
  // Simple task (3-5 actions)
  let maxSteps = 5;

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

  // Complex multi-page task (15-30 actions)
  maxSteps = 30;
  ```
</CodeGroup>

### 2. Balance Cost and Capability

Use cheaper models for simple tasks:

<CodeGroup>
  ```python bp_model_selection.py theme={null}
  # Simple navigation and extraction
  reasoning_model = "gemini/gemini-3.5-flash"

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

  ```typescript bp_model_selection.ts theme={null}
  // Simple navigation and extraction
  let reasoningModel = 'gemini/gemini-3.5-flash';

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

### 3. Use Vision Selectively

Disable vision when not needed to reduce costs:

<CodeGroup>
  ```python bp_vision.py theme={null}
  # Text-only site
  text_agent = client.Agent(session=session, use_vision=False)

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

  ```typescript bp_vision.ts theme={null}
  // Text-only site
  const textAgent = client.Agent({ session, use_vision: false });

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

### 4. Provide Context via URL

Start agents at the right page:

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.