Qwen-Agent：基于通义千问的智能体开发框架全面解析

最近逛 GitHub 时，看到了 Qwen 开源的专用 Agent 框架，Qwen-Agent 。为开发者提供了强大的工具和灵活的接口，支持构建具备指令遵循、工具使用、规划、记忆等能力的智能体应用。本文将深入解析 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 网站上选择需要的工具，并配置相关环境

https://github.com/modelcontextprotocol/servers

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