最近逛 GitHub 時(shí)，看到了 Qwen 開(kāi)源的專用 Agent 框架，Qwen-Agent 。為開(kāi)發(fā)者提供了強(qiáng)大的工具和靈活的接口，支持構(gòu)建具備指令遵循、工具使用、規(guī)劃、記憶等能力的智能體應(yīng)用。

本文將深入解析 Qwen-Agent 的核心功能、安裝配置、使用示例及常見(jiàn)問(wèn)題，幫助開(kāi)發(fā)者快速上手并高效開(kāi)發(fā)。

一、Qwen-Agent 概覽

1.1 核心功能

Qwen-Agent 是一個(gè)開(kāi)發(fā)框架，旨在讓開(kāi)發(fā)者充分利用通義千問(wèn)模型（Qwen）的能力，構(gòu)建智能化的 Agent 應(yīng)用。其核心特點(diǎn)包括：

• 指令遵循：支持自然語(yǔ)言指令的解析與執(zhí)行。
• 工具調(diào)用：集成多種工具（如代碼解釋器、圖像生成器等），實(shí)現(xiàn)復(fù)雜任務(wù)的自動(dòng)化。
• 規(guī)劃與記憶：支持多步驟任務(wù)規(guī)劃及上下文記憶，提升交互連續(xù)性。
• 示例應(yīng)用：提供瀏覽器助手、代碼解釋器、自定義助手等示例，方便開(kāi)發(fā)者快速學(xué)習(xí)。

1.2 最新更新（截至 2025 年 5 月）

• Qwen3 Tool-call Demo：新增 Qwen3 模型的工具調(diào)用示例，展示更高效的推理能力。
• MCP Cookbooks：擴(kuò)展 Model Context Protocol（MCP）的使用場(chǎng)景，支持更靈活的內(nèi)存管理。
• QwQ-32B 支持：新增對(duì) QwQ-32B 模型的并行、多步工具調(diào)用支持。
• GUI 升級(jí)：基于 Gradio 5 的圖形界面優(yōu)化，要求 Python 3.10+。
• RAG 解決方案：發(fā)布高效的 RAG（檢索增強(qiáng)生成）方案，支持超長(zhǎng)文檔問(wèn)答。

二、安裝與配置

2.1 安裝方式

方式一：通過(guò) PyPI 安裝

# 安裝穩(wěn)定版本（包含常用依賴）
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 模型服務(wù)配置

Qwen-Agent 支持兩種模型服務(wù)接入方式：

1. 阿里云 DashScope 服務(wù)

• 配置環(huán)境變量 DASHSCOPE_API_KEY：

export DASHSCOPE_API_KEY=your_api_key

• 在代碼中指定模型參數(shù)：

llm_cfg = {
    'model': 'qwen-max-latest',
    'model_server': 'dashscope'
}

2. 開(kāi)源模型服務(wù)（如 vLLM/Ollama）

• 部署兼容 OpenAI API 的服務(wù)后，配置如下：

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

三、快速開(kāi)發(fā)示例

以下示例演示如何創(chuàng)建一個(gè)圖像生成 + 圖像處理的智能體：

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 繪畫(huà)服務(wù)，輸入文本描述，返回圖像 URL。'
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description': '圖像內(nèi)容的詳細(xì)描述',
        '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 創(chuàng)建智能體

llm_cfg = {
    'model': 'qwen-max-latest',
    'model_server': 'dashscope'
}

system_instruction = '''收到用戶請(qǐng)求后：
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']  # 提供文檔知識(shí)庫(kù)
)

# 運(yùn)行智能體
messages = []
whileTrue:
    query = input('用戶請(qǐng)求: ')
    messages.append({'role': 'user', 'content': query})
    response = bot.run(messages=messages)
    print('機(jī)器人回應(yīng):', response)

3.3 啟動(dòng) GUI 界面

from qwen_agent.gui import WebUI
WebUI(bot).run()  # 通過(guò) Gradio 啟動(dòng) Web 界面

四、見(jiàn)問(wèn)題（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 服務(wù)器（如內(nèi)存、文件系統(tǒng)、SQLite）：

可以在開(kāi)源的 MCP Server 網(wǎng)站上選擇需要的工具，并配置相關(guān)環(huán)境

https://github.com/modelcontextprotocol/servers

MCP 允許智能體管理外部資源（如文件系統(tǒng)、數(shù)據(jù)庫(kù)）。配置示例：

{
    "mcpServers": {
        "memory": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-memory"]
        },
        "filesystem": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"]
        }
    }
}

4.2 是否支持函數(shù)調(diào)用？

是的！Qwen-Agent 提供了完整的函數(shù)調(diào)用支持，示例代碼位于 examples/function_calling.py，并支持 FnCallAgent 和 ReActChat 等高級(jí)智能體。

4.3 其他示例 - BrowserQwen

BrowserQwen 是一款基于 Qwen-Agent 構(gòu)建的瀏覽器助手。如需了解詳情，請(qǐng)參閱其文檔。

https://github.com/QwenLM/Qwen-Agent/blob/main/browser_qwen_cn.md

五、結(jié)語(yǔ)

Qwen-Agent 以其靈活性、高效性和強(qiáng)大的功能擴(kuò)展，為開(kāi)發(fā)者提供了構(gòu)建智能體應(yīng)用的完整解決方案。無(wú)論是圖像生成、代碼執(zhí)行，還是超長(zhǎng)文檔處理，Qwen-Agent 都能勝任。通過(guò)本文的詳細(xì)解析，相信您已經(jīng)掌握了 Qwen-Agent 的核心用法?，F(xiàn)在，就動(dòng)手嘗試開(kāi)發(fā)屬于您的智能體應(yīng)用吧！

?? 官方 GitHub 倉(cāng)庫(kù)：https://github.com/QwenLM/Qwen-Agent