README

中文 ｜ English


    




          💜 Qwen Chat&nbsp&nbsp | &nbsp&nbsp🤗 Hugging Face&nbsp&nbsp | &nbsp&nbsp🤖 ModelScope&nbsp&nbsp | &nbsp&nbsp 📑 Blog &nbsp&nbsp ｜ &nbsp&nbsp📖 Documentation


📊 Benchmark&nbsp&nbsp | &nbsp&nbsp💬 WeChat (微信)&nbsp&nbsp | &nbsp&nbsp🫨 Discord&nbsp&nbsp


Qwen-Agent是一个开发框架。开发者可基于本框架开发Agent应用，充分利用基于通义千问模型（Qwen）的指令遵循、工具使用、规划、记忆能力。本项目也提供了浏览器助手、代码解释器、自定义助手等示例应用。
现在，Qwen-Agent 作为 Qwen Chat 的后端运行。

 更新
 🔥🔥🔥Feb 16, 2026: 开源Qwen3.5，调用实例参考 Qwen3.5 Agent Demo。
 Jan 27, 2026: 开源Agent评测基准DeepPlanning，增加Qwen-Agent文档。
 Sep 23, 2025: 新增 Qwen3-VL Tool-call Demo，支持使用抠图、图搜、文搜等工具。
 Jul 23, 2025: 新增 Qwen3-Coder Tool-call Demo；新增原生API工具调用接口支持，例如可使用vLLM自带的工具调用解析。
 May 1, 2025: 新增 Qwen3 Tool-call Demo；新增 MCP cookbooks。
 Mar 18, 2025: 支持reasoning_content字段；调整默认的Function Call模版（适用于Qwen2.5系列通用模型、QwQ-32B）。如果需要使用旧版模版：请参考样例传递参数。
 Mar 7, 2025: 新增QwQ-32B Tool-call Demo，支持并行、多步、多轮工具调用。
 Dec 3, 2024: GUI 升级为基于 Gradio 5。注意：如果需要使用GUI，Python版本需要3.10及以上。
 Sep 18, 2024: 新增Qwen2.5-Math Demo以展示Qwen2.5-Math基于工具的推理能力。注意：代码执行工具未进行沙箱保护，仅适用于本地测试，不可用于生产。

 开始上手

 安装

- 从 PyPI 安装稳定版本：
bash
pip install -U "qwen-agent[rag,code_interpreter,gui,mcp]"
 或者，使用 pip install -U qwen-agent 来安装最小依赖。
 可使用双括号指定如下的可选依赖：
   [gui] 用于提供基于 Gradio 的 GUI 支持；
   [rag] 用于支持 RAG；
   [code_interpreter] 用于提供代码解释器相关支持；
   [mcp] 用于支持 MCP。


- 或者，你可以从源码安装最新的开发版本：
bash
git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e ./"[gui,rag,code_interpreter,mcp]"
 或者，使用 pip install -e ./ 安装最小依赖。



 准备：模型服务

Qwen-Agent支持接入阿里云DashScope服务提供的Qwen模型服务，也支持通过OpenAI API方式接入开源的Qwen模型服务。

- 如果希望接入DashScope提供的模型服务，只需配置相应的环境变量DASHSCOPE_API_KEY为您的DashScope API Key。

- 或者，如果您希望部署并使用您自己的模型服务，请按照Qwen2的README中提供的指导进行操作，以部署一个兼容OpenAI接口协议的API服务。
具体来说，请参阅vLLM一节了解高并发的GPU部署方式，或者查看Ollama一节了解本地CPU（+GPU）部署。

注意对于QwQ和Qwen3模型，建议启动服务时不加--enable-auto-tool-choice和--tool-call-parser hermes两个参数，因为Qwen-Agent会自行解析vLLM的工具输出。
对于Qwen3-Coder，则建议开启以上两个参数，使用vLLM自带的工具解析，并搭配use_raw_api参数使用。

 快速开发

框架提供了大模型（LLM，继承自class BaseChatModel，并提供了Function Calling功能）和工具（Tool，继承自class BaseTool）等原子组件，也提供了智能体（Agent）等高级抽象组件（继承自class Agent）。

以下示例演示了如何增加自定义工具，并快速开发一个带有设定、知识库和工具使用能力的智能体：

py
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（可选）：添加一个名为 my_image_gen 的自定义工具。
@register_tool('my_image_gen')
class MyImageGen(BaseTool):
     description 用于告诉智能体该工具的功能。
    description = 'AI 绘画（图像生成）服务，输入文本描述，返回基于文本信息绘制的图像 URL。'
     parameters 告诉智能体该工具有哪些输入参数。
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description': '期望的图像内容的详细描述',
        'required': True
    }]

    def call(self, params: str, kwargs) - str:
         params 是由 LLM 智能体生成的参数。
        prompt = json5.loads(params)['prompt']
        prompt = urllib.parse.quote(prompt)
        return json5.dumps(
            {'image_url': f'https://image.pollinations.ai/prompt/{prompt}'},