Skip to main content

​
Overview

Qwen-Agent is a framework for developing LLM applications based on the instruction following, tool usage, planning, and memory capabilities of Qwen. This guide will walk you through the installation process and initial setup.

​
Prerequisites

Before installing Qwen-Agent, ensure you have:
  • Python 3.8 or higher (Python 3.10+ required for GUI features)
  • pip package manager
  • (Optional) Docker installed and running for Code Interpreter functionality

​
Installation Methods

​
Install from PyPI

Install the stable version with all optional dependencies:
pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"
The -U flag ensures you get the latest version. If you encounter any issues, try running the command without quotes.

​
Optional Dependencies

Qwen-Agent supports modular installation with optional dependencies for specific features:

Minimal Installation

pip install -U qwen-agent
Includes only core function calling capabilities with these dependencies:
  • dashscope>=1.11.0
  • json5, jsonlines, jsonschema
  • openai, pydantic>=2.3.0
  • requests, tiktoken, pillow

GUI Support

pip install -U "qwen-agent[gui]"
Adds Gradio-based web interface:
  • gradio==5.23.1
  • gradio-client==1.8.0
  • modelscope_studio==1.1.7
  • pydantic==2.9.2
GUI requires Python 3.10 or higher due to Gradio 5 dependencies.

RAG Support

pip install -U "qwen-agent[rag]"
Enables Retrieval-Augmented Generation:
  • charset-normalizer
  • rank_bm25, jieba, snowballstemmer
  • beautifulsoup4
  • pdfminer.six, pdfplumber
  • python-docx, python-pptx
  • pandas, tabulate

Code Interpreter

pip install -U "qwen-agent[code_interpreter]"
Enables secure code execution in Docker:
  • anyio>=3.7.1
  • fastapi>=0.103.1
  • jupyter>=1.0.0
  • uvicorn>=0.23.2
Requires Docker to be installed and running on your system.

MCP Support

pip install -U "qwen-agent[mcp]"
Adds Model Context Protocol support:
  • mcp
Additional system requirements:
  • Node.js (latest version)
  • uv 0.4.18 or higher
  • Git

All Features

pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"
Installs all optional dependencies for complete functionality.

​
Model Service Configuration

Qwen-Agent requires a model service to function. You have two options:

​
Option 1: DashScope (Alibaba Cloud)

1

Get API Key

Sign up for DashScope and obtain your API key from the dashboard.
2

Set Environment Variable

Configure your API key as an environment variable:
export DASHSCOPE_API_KEY="your-api-key-here"
Add this to your shell profile (.bashrc, .zshrc, etc.) to persist across sessions.
3

Configure in Code

Use DashScope models in your agent configuration:
llm_cfg = {
    'model': 'qwen-max-latest',
    'model_type': 'qwen_dashscope',
    # 'api_key': 'YOUR_DASHSCOPE_API_KEY',  # Optional if env var is set
}

​
Option 2: Self-Hosted Models

Deploy your own OpenAI-compatible model service using open-source Qwen models.

​
Deploy with vLLM

Recommended for high-throughput production deployments.
1

Install vLLM

pip install vllm
2

Start Server

python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-7B-Instruct \
  --served-model-name Qwen2.5-7B-Instruct \
  --host 0.0.0.0 \
  --port 8000
For Qwen3 and QwQ models, do not add --enable-auto-tool-choice or --tool-call-parser hermes parameters. Qwen-Agent will handle tool parsing.
For Qwen3-Coder, enable both parameters and use use_raw_api: True in your configuration.
3

Configure in Code

llm_cfg = {
    'model': 'Qwen2.5-7B-Instruct',
    'model_server': 'http://localhost:8000/v1',  # base_url
    'api_key': 'EMPTY',
}

​
Docker Setup for Code Interpreter

The Code Interpreter tool requires Docker for secure code execution in isolated containers.
1

Install Docker

Download and install Docker Desktop from docker.com
2

Verify Installation

docker --version
docker ps
3

Start Docker

Ensure Docker daemon is running before using the Code Interpreter tool.
Security Notice: The Docker-based code interpreter mounts only the specified working directory with basic sandbox isolation. Use with caution in production environments.

​
MCP Additional Setup

For Model Context Protocol (MCP) support, install additional system dependencies: 
brew install uv git sqlite3
Verify installations: 
node --version
uv --version
git --version
sqlite3 --version

​
Verification

Verify your installation by running a simple test:
test_installation.py
import qwen_agent
from qwen_agent.agents import Assistant

print(f"Qwen-Agent version: {qwen_agent.__version__}")
print("Installation successful!")

​
Next Steps

Quickstart Guide

Build your first agent in 5 minutes

Examples

Explore example implementations

API Reference

Dive into the API documentation

GitHub

View source code and contribute

​
Troubleshooting

This usually indicates missing dependencies. Try reinstalling with all optional features:
pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]" --force-reinstall
The GUI requires Python 3.10 or higher due to Gradio 5 dependencies. Upgrade Python or use the CLI interface:
python --version  # Check your version
Ensure Docker is installed and running:
docker ps  # Should not return an error
On macOS/Windows, make sure Docker Desktop is running.
Verify your environment variable is set:
echo $DASHSCOPE_API_KEY  # Linux/macOS
echo %DASHSCOPE_API_KEY%  # Windows CMD
If empty, set it again and restart your terminal/IDE.

Build docs developers (and LLMs) love

Get started for freeTalk to us