> ## Documentation Index
> Fetch the complete documentation index at: https://notte-experiment-visibility-md-links.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser Agents

> AI-powered agents that autonomously complete browser tasks

Browser Agents are AI-powered systems that can autonomously navigate websites, complete tasks, and extract information using natural language instructions.

## What is a Browser Agent?

A Browser Agent combines:

* **Large Language Models (LLMs)** for reasoning and decision-making
* **Browser Sessions** for executing actions
* **Vision capabilities** to understand web pages
* **Autonomous planning** to complete multi-step tasks

Unlike scripted automation, agents can adapt to changes, handle unexpected scenarios, and complete tasks without predefined workflows.

## Quick Start

Create and run an agent in a few lines:

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

```python agent_quickstart.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", max_steps=10)

    result = agent.run(task="Go to example.com and find the contact email")

    print(result.answer)
```

<Tip>
  Agents run within [browser sessions](/concepts/sessions.md). Use context managers to ensure sessions are automatically stopped when done. This prevents orphaned sessions and unexpected costs.
</Tip>

## How Agents Work

### 1. Observation

The agent observes the current page state:

* Visible elements and their properties
* Interactive components (buttons, forms, links)
* Text content and structure
* Current URL and page metadata

### 2. Reasoning

Using the LLM, the agent:

* Understands the current page
* Plans the next action to complete the task
* Decides which element to interact with
* Determines when the task is complete

### 3. Action

The agent executes browser actions:

* Navigate to URLs
* Click buttons and links
* Fill forms
* Extract data
* Scroll and interact with dynamic content

### 4. Iteration

This cycle repeats until:

* The task is successfully completed
* Maximum steps are reached
* An error occurs that can't be resolved

## Agents vs Scripted Automation

Both agents and scripted automation run on [browser sessions](/concepts/sessions.md)—the cloud browser infrastructure. The difference is how you control what happens in that session.

| Aspect          | Scripted Automation     | Agent                           |
| --------------- | ----------------------- | ------------------------------- |
| **Control**     | You write the code      | AI decides each step            |
| **Flexibility** | Fixed workflow          | Adapts to changes               |
| **Speed**       | Fast (direct execution) | Slower (LLM reasoning per step) |
| **Cost**        | Browser minutes only    | Browser minutes + LLM calls     |
| **Reliability** | Deterministic           | Can vary based on page state    |
| **Use Case**    | Known, stable workflows | Unknown or dynamic workflows    |

**Use scripted automation when:**

* You know the exact steps to take
* Speed and cost are critical
* The target pages rarely change

**Use agents when:**

* You don't know the exact steps
* Pages change frequently
* You need intelligent decision-making

<Note>
  You can combine both approaches: use an agent to figure out a workflow, then [convert it to a function](/features/agents/workflows.md) for faster, cheaper repeated execution.
</Note>

## Agent Capabilities

Agents come with powerful built-in capabilities:

<CardGroup cols={2}>
  <Card title="Structured Output" icon="brackets-curly" href="/features/agents/structured-output.md">
    Get type-safe responses using Pydantic models
  </Card>

  <Card title="Vaults & Personas" icon="lock" href="/concepts/vaults.md">
    Use credentials and identities in automations
  </Card>

  <Card title="Visual Understanding" icon="eye" href="/features/agents/configuration.md#use_vision">
    Analyze images and visual page elements
  </Card>

  <Card title="Replay & Debugging" icon="circle-play" href="/features/agents/replay.md">
    Debug with MP4 replays of agent execution
  </Card>

  <Card title="Agent Fallback" icon="shield" href="/features/agents/fallback.md">
    Automatic recovery from script failures
  </Card>
</CardGroup>

## Key Concepts

### Natural Language Tasks

Give instructions in plain English:

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

```python natural_language_task.py theme={null}
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    agent = client.Agent(session=session)
    agent.run(task="Find the cheapest laptop under $1000 and add it to cart")
```

### Structured Output

Get responses in a specific format:

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

```python structured_output_example.py theme={null}
from notte_sdk import NotteClient
from pydantic import BaseModel

client = NotteClient()


class ContactInfo(BaseModel):
    email: str
    phone: str | None


with client.Session() as session:
    agent = client.Agent(session=session)
    result = agent.run(task="Extract contact information", response_format=ContactInfo)
```

### Starting URL

Begin at a specific page:

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

```python starting_url.py theme={null}
agent = client.Agent(session=session)
agent.run(task="Find pricing information", url="https://example.com/products")
```

### Step Limits

Control maximum actions:

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

```python step_limits.py theme={null}
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    agent = client.Agent(
        session=session,
        max_steps=20,  # Limit to 20 actions
    )
```

## Error Handling

Agents can fail for various reasons. Always check the result:

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

```python error_handling.py theme={null}
agent = client.Agent(session=session)
result = agent.run(task="Complete task")

if result.success:
    print(result.answer)
else:
    print(f"Agent failed: {result.answer}")
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Agent Lifecycle" icon="rotate" href="/features/agents/lifecycle.md">
    Create, manage, and stop agents
  </Card>

  <Card title="Agent Configuration" icon="gear" href="/features/agents/configuration.md">
    All configuration options
  </Card>

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

  <Card title="Convert to Functions" icon="flower" href="/features/agents/workflows.md">
    Turn agent runs into reusable code
  </Card>
</CardGroup>