Qwen-Agent: The Complete Guide to Alibaba's Official AI Agent Framework
Qwen-Agent is the official agent framework built by Alibaba's QwenLM team for the Qwen model family (Qwen>=3.0). Function Calling (parallel, multi-step), MCP, Code Interpreter (Docker sandbox), RAG (1M tokens), BrowserQwen Chrome extension, Gradio GUI. 15,200+ stars, 25 releases, Apache 2.0.
What Is Qwen-Agent?
A Python framework providing atomic components (LLMs, Tools) and high-level Agents for building applications powered by Qwen models. The official way to build agents with Qwen3.5, QwQ-32B, Qwen3-VL, and Qwen3-Coder.
- Language: Python
- License: Apache 2.0
- Stars: 15,200+ ⭐
- Forks: 1,456
- Releases: 25
- PyPI: qwen-agent
- By: QwenLM (Alibaba)
Core Architecture
Qwen-Agent uses a layered component architecture:
| Layer | Component | Description |
|---|---|---|
| Low-level | BaseChatModel | LLM wrappers with built-in function calling |
| Low-level | BaseTool | Tool interface with @register_tool decorator |
| High-level | Agent | Base agent class for custom implementations |
| High-level | Assistant | Pre-built agent with tools + file reading |
| High-level | FnCallAgent | Function-calling-optimized agent |
| High-level | ReActChat | ReAct reasoning agent |
| UI | WebUI | Gradio 5 GUI for quick deployment |
Features
Function Calling
- Parallel function calls — Multiple tools in one turn
- Multi-step — Chain tool calls across reasoning steps
- Multi-turn — Maintain tool context across conversation
- Custom tools —
@register_tooldecorator - Native API support — vLLM built-in tool call parsing
MCP (Model Context Protocol)
Full MCP support with standard configuration:
{
"mcpServers": {
"memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] },
"filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"] }
}
}
Code Interpreter
- Docker container-based sandboxed execution
- Agents autonomously write and execute code
- Secure isolation with mounted working directory
RAG (Super-Long Documents)
- Process documents up to 1M tokens
- PDF file reading built into agents
- Document QA with context management
BrowserQwen (Chrome Extension)
A browser assistant built upon Qwen-Agent — web page understanding, extraction, and interaction.
Supported Models
| Model | Capabilities |
|---|---|
| Qwen3.5 | Latest, full agent capabilities |
| QwQ-32B | Reasoning + parallel/multi-step tool calls |
| Qwen3-VL | Vision + tools (zoom, image search, web search) |
| Qwen3-Coder | Native code tool calling |
| Qwen2.5-Math | Tool-integrated reasoning for math |
Model Service Compatibility
- DashScope (Alibaba Cloud) — native
- vLLM — OpenAI-compatible endpoint
- Ollama — local models
Quick Start
from qwen_agent.agents import Assistant
from qwen_agent.tools.base import BaseTool, register_tool
@register_tool('my_tool')
class MyTool(BaseTool):
description = 'My custom tool'
parameters = [{'name': 'query', 'type': 'string', 'required': True}]
def call(self, params, **kwargs):
return "Result"
bot = Assistant(
llm={'model': 'qwen-max-latest', 'model_type': 'qwen_dashscope'},
function_list=['my_tool', 'code_interpreter'],
files=['./doc.pdf']
)
# Launch Gradio UI
from qwen_agent.gui import WebUI
WebUI(bot).run()
Qwen-Agent vs Alternatives
Category: This is an official first-party AI agent framework for the Qwen model family.
| Feature | Qwen-Agent | LangChain | CrewAI |
|---|---|---|---|
| Focus | Official Qwen agent framework | General LLM framework | Multi-agent orchestration |
| Stars | 15.2K ⭐ | 100K+ ⭐ | 25K ⭐ |
| License | Apache 2.0 | MIT | MIT |
| Language | Python | Python | Python |
| First-Party Model Support | ✅ Qwen3.5/QwQ/VL/Coder | ❌ Third-party | ❌ Third-party |
| Function Calling | ✅ Parallel + multi-step | ✅ | ✅ |
| MCP Support | ✅ Native | ✅ | ❌ |
| Code Interpreter | ✅ Docker sandbox | ❌ External | ❌ |
| RAG (1M tokens) | ✅ Built-in | ✅ (external vector DB) | ❌ |
| Chrome Extension | ✅ BrowserQwen | ❌ | ❌ |
| Vision Tool Calls | ✅ Qwen3-VL | ❌ | ❌ |
| Gradio GUI | ✅ Built-in WebUI | ❌ | ❌ |
| Custom Tools | ✅ @register_tool | ✅ | ✅ |
| DeepPlanning Benchmark | ✅ | ❌ | ❌ |
| Reasoning Models | ✅ QwQ-32B | ❌ First-party | ❌ |
When to choose Qwen-Agent: You're building agents with Qwen models and want the official, first-party framework with deep model integration — function calling, MCP, code interpreter, RAG, vision tool calls, Chrome extension, and Gradio GUI all built in.
When to choose LangChain: You want a model-agnostic framework with the largest ecosystem. But it's heavier, more complex, and lacks first-party Qwen integration.
When to choose CrewAI: You want multi-agent role-based orchestration for teams of AI agents. Different focus — team coordination, not model-specific tooling.
Conclusion
Qwen-Agent is the official way to build agents with Alibaba's Qwen model family. First-party integration with Qwen3.5, QwQ-32B, Qwen3-VL, and Qwen3-Coder gives it unmatched depth — parallel function calling, MCP, Docker-sandboxed code interpreter, 1M-token RAG, BrowserQwen Chrome extension, vision tool calls, and one-line Gradio GUI deployment. At 15.2K stars with 25 releases, it's production-ready and actively maintained by the same team that builds the models.