# How to Use Qwen-Agent for Web Browsing: A Complete Guide to BrowserQwen

> Learn to use Qwen-Agent for web browsing with BrowserQwen. Deploy the server, load the Chrome extension, and chat with AI about web content. A complete guide for efficient online interaction.

- Repository: [Qwen/Qwen-Agent](https://github.com/qwenlm/Qwen-Agent)
- Tags: how-to-guide
- Published: 2026-03-09

---

**To use Qwen-Agent for web browsing, deploy the workstation server with your LLM credentials, load the BrowserQwen Chrome extension in developer mode, and add web pages to Qwen’s reading list to chat with the AI about their content.**

The Qwen-Agent framework (available at `QwenLM/Qwen-Agent`) provides **BrowserQwen**, a browser assistant that transforms web browsing into an interactive AI experience. This system allows you to capture web pages, PDFs, and Office documents directly from Chrome, then query them using Qwen LLMs with optional code interpretation capabilities. Understanding how to use Qwen-Agent for web browsing requires familiarity with its three-tier architecture bridging your browser and local LLM infrastructure.

## Understanding the BrowserQwen Architecture

BrowserQwen consists of three tightly integrated components working together to bridge your browser and the Qwen LLM.

### The Workstation Server

The core orchestration logic resides in [`qwen_server/workstation_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_server/workstation_server.py). This Flask-based server manages conversation history, renders the browsing list UI, and coordinates plugin execution.

Key functions include:

- **`update_browser_list()`** (lines 153-170): Retrieves persisted browsing records using `read_meta_data_by_condition` and renders them as an HTML checklist in the UI.
- **`bot()` and `pure_bot()`** (lines 45-108): Handle chat pipelines by assembling message history, attaching uploaded files, and invoking the LLM via `Assistant` or `ReActChat` classes.
- **`choose_plugin()`** (lines 89-96): Toggles the **Code Interpreter** (`CI_OPTION`) and **Document QA** (`DOC_OPTION`) based on user selection.

The server maintains global state in an `app_global_para` dictionary that tracks messages, uploaded files, and filtering parameters.

### The Database Service

The [`run_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/run_server.py) entry point launches a FastAPI service that persists browsing metadata and conversation logs. It exposes endpoints for saving page data (`save_browsing_meta_data`) and retrieving records (`read_meta_data_by_condition`).

### The Chrome Extension

Located in the `browser_qwen/` directory, the unpacked extension injects UI elements into web pages and forwards content to the workstation. Key files include:

- **[`manifest.json`](https://github.com/QwenLM/Qwen-Agent/blob/main/manifest.json)**: Declares permissions for `activeTab`, `scripting`, and `storage`.
- **[`src/content.js`](https://github.com/QwenLM/Qwen-Agent/blob/main/src/content.js)**: Extracts DOM snapshots and captures screenshots, sending payloads to the workstation via HTTP POST requests.
- **[`src/popup.js`](https://github.com/QwenLM/Qwen-Agent/blob/main/src/popup.js)**: Manages the extension popup interface for user interactions.

## Setting Up Qwen-Agent for Web Browsing

### Starting the Backend Services

Launch the database and workstation services using the CLI entry point. For **DashScope** (Alibaba Cloud) models:

```bash
python run_server.py --llm qwen-max \
    --model_server dashscope \
    --workstation_port 7864 \
    --api_key YOUR_DASHSCOPE_API_KEY

```

For **self-hosted** models via vLLM:

```bash
python run_server.py --llm Qwen1.5-72B-Chat \
    --model_server http://localhost:8000/v1 \
    --api_key EMPTY \
    --workstation_port 7864

```

The workstation UI becomes available at `http://127.0.0.1:7864/`, presenting **Editor** and **Chat** tabs for different interaction modes.

### Installing the Browser Extension

1. Open Chrome and navigate to `chrome://extensions/`.
2. Enable **Developer mode** using the toggle in the top-right corner.
3. Click **Load unpacked** and select the `browser_qwen` folder from your local repository.

The BrowserQwen icon appears in your toolbar, ready to capture page content.

## Capturing and Interacting with Web Content

### Adding Pages to Your Reading List

When browsing, click the **"Add to Qwen’s Reading List"** button in the extension popup. The [`content.js`](https://github.com/QwenLM/Qwen-Agent/blob/main/content.js) script extracts the page metadata and sends a JSON payload to the workstation:

```javascript
fetch('http://127.0.0.1:7864/add_page', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
        url: location.href,
        title: document.title,
        html: document.documentElement.outerHTML,
        screenshot: base64ImageData  // optional
    })
});

```

The `/add_page` endpoint stores this data via the database service, making the page appear in the workstation’s browsing list panel.

### Querying Content with Code Interpretation

Interact with saved content through the workstation UI or extension popup. The system constructs message payloads combining your query with page references:

```python
content = [
    {'text': user_query},
    {'file': page_url}
]

```

Enable the **Code Interpreter** plugin from the UI dropdown to allow data visualization. The backend invokes `ReActChat` with `function_list=['code_interpreter']`, enabling Qwen to generate and execute Python code against the captured content.

## Managing Browsing History

The workstation automatically refreshes your reading list using `update_browser_list()`. You can also query records programmatically:

```bash
curl http://127.0.0.1:7864/browsing_records?start=2024-01-01&end=2024-01-31

```

This returns metadata for pages saved within the specified date range, which the UI renders as interactive checkboxes alongside their URLs.

## Summary

- **BrowserQwen** combines a workstation server, database service, and Chrome extension to enable AI-augmented web browsing according to the `QwenLM/Qwen-Agent` source code.
- Deploy the backend using [`run_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/run_server.py) with either DashScope or self-hosted model endpoints.
- Install the `browser_qwen` extension in Chrome developer mode to capture page DOM and screenshots.
- Use the **Code Interpreter** plugin for data analysis tasks on saved web content.
- Browse history persists in a local FastAPI service, accessible via REST endpoints or the workstation UI.

## Frequently Asked Questions

### What models does Qwen-Agent support for web browsing?

The system supports both cloud-hosted models via **DashScope** (such as `qwen-max`) and self-hosted models (such as `Qwen1.5-72B-Chat`) through OpenAI-compatible endpoints like vLLM. Specify your model using the `--llm` and `--model_server` flags when starting [`run_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/run_server.py).

### How does the Chrome extension extract page content?

The extension's [`src/content.js`](https://github.com/QwenLM/Qwen-Agent/blob/main/src/content.js) script injects into web pages and captures the full DOM via `document.documentElement.outerHTML`, along with the page title and URL. It can optionally capture screenshots as base64-encoded images, transmitting this data to the workstation's `/add_page` endpoint.

### Can I use Qwen-Agent with a self-hosted LLM?

Yes. Set `--model_server` to your local endpoint (e.g., `http://localhost:8000/v1` for vLLM) and use `--api_key EMPTY` or your local API key. This configuration routes all inference requests to your private infrastructure rather than DashScope.

### Where is the browsing history stored?

The FastAPI database service persists browsing metadata locally. The `update_browser_list()` function in [`qwen_server/workstation_server.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_server/workstation_server.py) retrieves these records using `read_meta_data_by_condition`, displaying them in the workstation UI with checkboxes for selection during chat sessions.