Qwen-Agent 项目详细介绍

项目概述

Qwen-Agent 是一个基于千问大语言模型的智能体开发框架，专门用于开发具备指令遵循、工具使用、规划和记忆能力的 LLM 应用程序。该项目由阿里巴巴千问团队开发维护，目前作为千问聊天服务 (Qwen Chat) 的后端支撑。

核心特性

1. 多功能智能体支持

浏览器助手 (Browser Assistant): 网页浏览和操作能力
代码解释器 (Code Interpreter): Python 代码执行和分析
自定义助手 (Custom Assistant): 个性化智能体定制
RAG 检索增强: 文档问答和知识检索
Chrome 扩展: 浏览器插件形式的智能助手

2. 先进技术集成

函数调用 (Function Calling): 支持工具和 API 集成
MCP 协议支持: 模型上下文协议兼容
并行工具调用: 多步骤、多轮次工具使用
推理能力: 集成 QwQ-32B 等推理模型

安装方式

稳定版本安装

pip install -U "qwen-agent[gui,rag,code_interpreter,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]"

可选依赖说明

[gui]: Gradio 图形界面支持
[rag]: RAG 检索增强功能
[code_interpreter]: 代码解释器功能
[mcp]: MCP 协议支持

模型服务配置

方式一：使用 DashScope 服务

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

方式二：自部署模型服务

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

核心组件架构

基础组件

BaseChatModel: LLM 基础类，支持函数调用
BaseTool: 工具基础类，可扩展自定义功能
Agent: 智能体基础类，支持继承定制

高级组件

Assistant: 通用助手智能体
FnCallAgent: 函数调用智能体
ReActChat: 推理行动对话智能体

实际应用示例

创建自定义工具智能体

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

# 步骤1: 添加自定义工具
@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)

# 步骤2: 配置 LLM
llm_cfg = {
    'model': 'qwen-max-latest',
    'model_server': 'dashscope',
    'generate_cfg': {
        'top_p': 0.8
    }
}

# 步骤3: 创建智能体
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)

# 步骤4: 运行智能体聊天
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)

启动 Web UI 界面

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

MCP 协议集成

MCP 服务器配置示例

{
  "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"
      ]
    }
  }
}

依赖环境要求

Node.js (最新版本)
uv 0.4.18 或更高版本
Git
SQLite

RAG 文档问答能力

项目提供了快速 RAG 解决方案，以及针对超长文档的竞争性智能体，在两个具有挑战性的基准测试中表现优于原生长上下文模型，并在涉及 100万 token 上下文的单针"大海捞针"压力测试中表现完美。

BrowserQwen 浏览器助手

BrowserQwen 是基于 Qwen-Agent 构建的浏览器助手，提供网页浏览、操作和信息提取能力。

技术特点与优势

模块化设计: 原子级组件，便于扩展和定制
多模型支持: 兼容千问系列各版本模型
丰富的工具生态: 内置多种实用工具
灵活部署: 支持云服务和本地部署
活跃维护: 持续更新和功能增强

总结

Qwen-Agent 是一个功能强大、易于使用的智能体开发框架，为开发者提供了构建复杂 LLM 应用的完整工具链。无论是简单的聊天机器人还是复杂的多功能智能助手，都可以通过该框架快速实现和部署。

Qwen-Agent