Qwen-Agent Project Detailed Introduction

Project Overview

Qwen-Agent is an intelligent agent development framework based on the Qwen large language model, specifically designed for developing LLM applications with instruction following, tool usage, planning, and memory capabilities. This project is developed and maintained by the Alibaba Qwen team and currently serves as the backend support for the Qwen Chat service.

Core Features

1. Multifunctional Agent Support

• Browser Assistant: Web browsing and operation capabilities
• Code Interpreter: Python code execution and analysis
• Custom Assistant: Personalized agent customization
• RAG Retrieval Augmentation: Document question answering and knowledge retrieval
• Chrome Extension: Intelligent assistant in the form of a browser plugin

2. Advanced Technology Integration

• Function Calling: Support for tool and API integration
• MCP Protocol Support: Model Context Protocol compatibility
• Parallel Tool Calling: Multi-step, multi-turn tool usage
• Reasoning Ability: Integrated with reasoning models such as QwQ-32B

Latest Updates

• March 18, 2025: Supports the reasoning_content field, adjusts the default function calling template
• March 7, 2025: Added QwQ-32B tool calling demo, supports parallel and multi-step calling
• December 3, 2024: Upgraded GUI to Gradio 5, requires Python 3.10+
• September 18, 2024: Added Qwen2.5-Math demo, showcasing tool-integrated reasoning capabilities

Installation Instructions

Stable Version Installation

pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"
# Or minimal installation
pip install -U qwen-agent

Development Version Installation

git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e ./"[gui,rag,code_interpreter,mcp]"

Optional Dependencies

• [gui]: Gradio graphical interface support
• [rag]: RAG retrieval augmentation functionality
• [code_interpreter]: Code interpreter functionality
• [mcp]: MCP protocol support

Model Service Configuration

Method 1: Using DashScope Service

llm_cfg = {
    'model': 'qwen-max-latest',
    'model_server': 'dashscope',
    # 'api_key': 'YOUR_DASHSCOPE_API_KEY',
    'generate_cfg': {
        'top_p': 0.8
    }
}

Method 2: Self-Deployed Model Service

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

Core Component Architecture

Basic Components

• BaseChatModel: LLM base class, supports function calling
• BaseTool: Tool base class, extensible for custom functions
• Agent: Agent base class, supports inheritance and customization

Advanced Components

• Assistant: General-purpose assistant agent
• FnCallAgent: Function calling agent
• ReActChat: Reasoning action dialogue agent

Practical Application Example

Creating a Custom Tool Agent

import pprint
import urllib.parse
import json5
from qwen_agent.agents import Assistant
from qwen_agent.tools.base import BaseTool, register_tool
from qwen_agent.utils.output_beautify import typewriter_print

# Step 1: Add a custom tool
@register_tool('my_image_gen')
class MyImageGen(BaseTool):
    description = 'AI painting (image generation) service, input text description, and return the image URL drawn based on text information.'
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description': 'Detailed description of the desired image content, in English',
        'required': True
    }]
    
    def call(self, params: str, **kwargs) -> str:
        prompt = json5.loads(params)['prompt']
        prompt = urllib.parse.quote(prompt)
        return json5.dumps(
            {'image_url': f'https://image.pollinations.ai/prompt/{prompt}'},
            ensure_ascii=False)

# Step 2: Configure LLM
llm_cfg = {
    'model': 'qwen-max-latest',
    'model_server': 'dashscope',
    'generate_cfg': {
        'top_p': 0.8
    }
}

# Step 3: Create an agent
system_instruction = '''After receiving the user's request, you should:
- first draw an image and obtain the image url,
- then run code `request.get(image_url)` to download the image,
- and finally select an image operation from the given document to process the image.
Please show the image using `plt.show()`.'''

tools = ['my_image_gen', 'code_interpreter']
files = ['./examples/resource/doc.pdf']
bot = Assistant(llm=llm_cfg,
                system_message=system_instruction,
                function_list=tools,
                files=files)

# Step 4: Run the agent chat
messages = []
while True:
    query = input('\nuser query: ')
    messages.append({'role': 'user', 'content': query})
    response = []
    response_plain_text = ''
    print('bot response:')
    for response in bot.run(messages=messages):
        response_plain_text = typewriter_print(response, response_plain_text)
    messages.extend(response)

Launching the Web UI

from qwen_agent.gui import WebUI
WebUI(bot).run()

MCP Protocol Integration

MCP Server Configuration Example

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    },
    "sqlite": {
      "command": "uvx",
      "args": [
        "mcp-server-sqlite",
        "--db-path",
        "test.db"
      ]
    }
  }
}

Dependent Environment Requirements

• Node.js (latest version)
• uv 0.4.18 or higher
• Git
• SQLite

RAG Document Question Answering Capability

The project provides a fast RAG solution, as well as competitive agents for ultra-long documents, outperforming native long-context models in two challenging benchmarks and performing perfectly in a single-shot "needle in a haystack" stress test involving 1 million token contexts.

BrowserQwen Browser Assistant

BrowserQwen is a browser assistant built on Qwen-Agent, providing web browsing, operation, and information extraction capabilities.

Technical Features and Advantages

1. Modular Design: Atomic components, easy to extend and customize
2. Multi-Model Support: Compatible with various versions of the Qwen series models
3. Rich Tool Ecosystem: Built-in multiple practical tools
4. Flexible Deployment: Supports cloud service and local deployment
5. Active Maintenance: Continuous updates and feature enhancements

Related Resource Links

• GitHub Repository: https://github.com/QwenLM/Qwen-Agent
• Official Documentation: https://qwen.readthedocs.io/
• Online Experience: https://chat.qwen.ai/
• Technical Blog: https://qwenlm.github.io/blog/qwen-agent-2405/
• Hugging Face: https://huggingface.co/Qwen
• ModelScope: https://modelscope.cn/organization/qwen

Summary

Qwen-Agent is a powerful and easy-to-use intelligent agent development framework that provides developers with a complete toolchain for building complex LLM applications. Whether it's a simple chatbot or a complex multifunctional intelligent assistant, it can be quickly implemented and deployed through this framework.