Qwen-Agent：基于通義千問的智能體開發框架全面解析
最近逛 GitHub 時，看到了 Qwen 開源的專用 Agent 框架，Qwen-Agent 。為開發者提供了強大的工具和靈活的接口，支持構建具備指令遵循、工具使用、規劃、記憶等能力的智能體應用。
本文將深入解析 Qwen-Agent 的核心功能、安裝配置、使用示例及常見問題，幫助開發者快速上手并高效開發。
一、Qwen-Agent 概覽
1.1 核心功能
Qwen-Agent 是一個開發框架，旨在讓開發者充分利用通義千問模型（Qwen）的能力，構建智能化的 Agent 應用。其核心特點包括：
- 指令遵循：支持自然語言指令的解析與執行。
- 工具調用：集成多種工具（如代碼解釋器、圖像生成器等），實現復雜任務的自動化。
- 規劃與記憶：支持多步驟任務規劃及上下文記憶，提升交互連續性。
- 示例應用：提供瀏覽器助手、代碼解釋器、自定義助手等示例，方便開發者快速學習。
1.2 最新更新（截至 2025 年 5 月）
- Qwen3 Tool-call Demo：新增 Qwen3 模型的工具調用示例，展示更高效的推理能力。
- MCP Cookbooks：擴展 Model Context Protocol（MCP）的使用場景，支持更靈活的內存管理。
- QwQ-32B 支持：新增對 QwQ-32B 模型的并行、多步工具調用支持。
- GUI 升級：基于 Gradio 5 的圖形界面優化，要求 Python 3.10+。
- RAG 解決方案：發布高效的 RAG（檢索增強生成）方案，支持超長文檔問答。
二、安裝與配置
2.1 安裝方式
方式一：通過 PyPI 安裝
# 安裝穩定版本（包含常用依賴）
pip install -U "qwen-agent[rag,code_interpreter,gui,mcp]"
# 或安裝最小依賴版本
pip install -U qwen-agent方式二：從源碼安裝
git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e ."[gui,rag,code_interpreter,mcp]"2.2 模型服務配置
Qwen-Agent 支持兩種模型服務接入方式：
1. 阿里云 DashScope 服務
- 配置環境變量
DASHSCOPE_API_KEY：
export DASHSCOPE_API_KEY=your_api_key- 在代碼中指定模型參數：
llm_cfg = {
'model': 'qwen-max-latest',
'model_server': 'dashscope'
}2. 開源模型服務（如 vLLM/Ollama）
- 部署兼容 OpenAI API 的服務后，配置如下：
llm_cfg = {
'model': 'Qwen2.5-7B-Instruct',
'model_server': 'http://localhost:8000/v1',
'api_key': 'EMPTY'
}三、快速開發示例
以下示例演示如何創建一個圖像生成 + 圖像處理的智能體：
3.1 自定義工具：圖像生成
from qwen_agent.agents import Assistant
from qwen_agent.tools.base import BaseTool, register_tool
import json5
import urllib.parse
@register_tool('my_image_gen')
class MyImageGen(BaseTool):
description = 'AI 繪畫服務，輸入文本描述，返回圖像 URL。'
parameters = [{
'name': 'prompt',
'type': 'string',
'description': '圖像內容的詳細描述',
'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}'})3.2 創建智能體
llm_cfg = {
'model': 'qwen-max-latest',
'model_server': 'dashscope'
}
system_instruction = '''收到用戶請求后：
1. 生成圖像 URL；
2. 使用 code_interpreter 下載并處理圖像；
3. 展示處理后的圖像。'''
bot = Assistant(
llm=llm_cfg,
system_message=system_instruction,
function_list=['my_image_gen', 'code_interpreter'],
files=['./examples/resource/doc.pdf'] # 提供文檔知識庫
)
# 運行智能體
messages = []
whileTrue:
query = input('用戶請求: ')
messages.append({'role': 'user', 'content': query})
response = bot.run(messages=messages)
print('機器人回應:', response)3.3 啟動 GUI 界面
from qwen_agent.gui import WebUI
WebUI(bot).run() # 通過 Gradio 啟動 Web 界面四、見問題（FAQ）
4.1 如何使用 MCP？
安裝依賴（Node.js、uv、Git、SQLite）：
- macOS:
brew install uv git sqlite3- Windows:
bash winget install astral-sh.uv git.sqlite sqlite.sqlite配置 MCP 服務器（如內存、文件系統、SQLite）：
可以在開源的 MCP Server 網站上選擇需要的工具，并配置相關環境
MCP 允許智能體管理外部資源（如文件系統、數據庫）。配置示例：
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
}
}
}4.2 是否支持函數調用？
是的！Qwen-Agent 提供了完整的函數調用支持，示例代碼位于 examples/function_calling.py，并支持 FnCallAgent 和 ReActChat 等高級智能體。
4.3 其他示例 - BrowserQwen
BrowserQwen 是一款基于 Qwen-Agent 構建的瀏覽器助手。如需了解詳情，請參閱其文檔。
https://github.com/QwenLM/Qwen-Agent/blob/main/browser_qwen_cn.md
五、結語
Qwen-Agent 以其靈活性、高效性和強大的功能擴展，為開發者提供了構建智能體應用的完整解決方案。無論是圖像生成、代碼執行，還是超長文檔處理，Qwen-Agent 都能勝任。通過本文的詳細解析，相信您已經掌握了 Qwen-Agent 的核心用法。現在，就動手嘗試開發屬于您的智能體應用吧！
?? 官方 GitHub 倉庫：https://github.com/QwenLM/Qwen-Agent
