---
title: WebSurferAgent
sidebarTitle: WebSurferAgent
---

### Introduction to WebSurferAgent

If you need an agent that can browse, extract, or interact with the web, [`WebSurferAgent`](/docs/api-reference/autogen/agents/experimental/WebSurferAgent) is a good choice. The agent actions the request(s) given to it by determining what to do on the web and browsing and crawling it, returning the details of what it finds.

The [`WebSurferAgent`](/docs/api-reference/autogen/agents/experimental/WebSurferAgent) has two in-built web tools to choose from:

1. [browser-use](https://github.com/browser-use/browser-use) - uses an actual browser instance (visible or headless), interacting with the web pages in realtime
2. [Crawl4AI](https://github.com/unclecode/crawl4ai) - crawls without a visual browser instance

<Tip>
If you want to add browsing capabilities to your existing agents, see [this notebook for browser-use](/docs/use-cases/notebooks/notebooks/tools_browser_use) and [this notebook for Crawl4AI](/docs/use-cases/notebooks/notebooks/tools_crawl4ai).
</Tip>

<Warning>
[`Browser Use`](https://github.com/browser-use/browser-use) requires **Python 3.11 or higher**.
</Warning>

### Installation and Setup

To get started with [`WebSurferAgent`](/docs/api-reference/autogen/agents/experimental/WebSurferAgent), install AG2 with the `browser-use` and/or `crawl4ai` extras.
```bash
pip install ag2[openai,browser-use]
```
and/or
```bash
pip install ag2[openai,crawl4ai]
```

<Tip>
If you have been using `autogen` or `ag2`, all you need to do is upgrade it using:
```bash
pip install -U autogen[openai,browser-use]
```
or
```bash
pip install -U ag2[openai,browser-use]
```
as `autogen` and `ag2` are aliases for the same PyPI package.
</Tip>

And then setup Playwright:
```bash
# Installs Playwright and browsers for all OS
playwright install
# Additional command, mandatory for Linux only
playwright install-deps
```

Now, you can create an agent, nominating the web tool:
<Tip>
[`Browser Use`](https://github.com/browser-use/browser-use) supports the following models: [Supported Models](https://docs.browser-use.com/customize/supported-models#supported-models)

We had great experience with `OpenAI`, `Anthropic`, and `Gemini`. However, `DeepSeek` and `Ollama` haven't performed as well.
</Tip>
<Tip>
[`Crawl4AI`](https://github.com/unclecode/crawl4ai) is built on top of [LiteLLM](https://github.com/BerriAI/litellm) and supports the same models as LiteLLM.

We had great experience with `OpenAI`, `Anthropic`, `Gemini` and `Ollama`. However, as of this writing, `DeepSeek` is encountering some issues.
</Tip>

### Using WebSurferAgent

<Tabs>
  <Tab title="browser_use">
    ```python
    from autogen import LLMConfig
    from autogen.agents.experimental import WebSurferAgent
    from dotenv import load_dotenv
    import os
    load_dotenv()

    # Put your key in the OPENAI_API_KEY environment variable
    llm_config = llm_config = LLMConfig(config_list={"api_type": "openai", "model": "gpt-5-nano","api_key":os.getenv("OPENAI_API_KEY")})

    # Create our agent
    websurfer = WebSurferAgent(
        name="WebSurfer",
        web_tool="browser_use",
        llm_config=llm_config,
    )
    ```
  </Tab>
  <Tab title="crawl4ai">
    ```python
    from autogen import LLMConfig
    from autogen.agents.experimental import WebSurferAgent
    from dotenv import load_dotenv
    import os
    load_dotenv()

    # Put your key in the OPENAI_API_KEY environment variable
    llm_config = llm_config = LLMConfig(config_list={"api_type": "openai", "model": "gpt-5-nano","api_key":os.getenv("OPENAI_API_KEY")})

    # Create our agent
    websurfer = WebSurferAgent(
        name="WebSurfer",
        web_tool="crawl4ai",
        llm_config=llm_config,
    )
    ```
  </Tab>
</Tabs>


<Tip>
Crawl4AI doesn't always require an LLM configuration, see [this notebook](/docs/use-cases/notebooks/notebooks/tools_crawl4ai) for examples with and without one.
</Tip>

Let's browse the web for news on AG2.

import Example from "/snippets/python-examples/websurferagent.mdx";

<Example/>

Let's break it down:

1. Import [`WebSurferAgent`](/docs/api-reference/autogen/agents/experimental/WebSurferAgent) and create an LLM configuration for the browser-use tool to use.

2. We create a configuration dictionary turning off the headless mode (so we can see what's happening) and saving an animated GIF of the process (shown below).

3. Create the agent, nominating the web tool and passing in the LLM and tool configurations.

4. Run the agent, ensuring we pass the agent's tools through to the `run` method so it can add them to the internal executor agent to execute.

![WebSurferAgent in action](./assets/websurferagent_animated.gif)
