QwenLM / Qwen-Agent

15,0111,436+586 todayPython

基于Qwen>=0构建的智能体框架与应用，支持函数调用、MCP、代码解释器、RAG、Chrome扩展等功能

Qwen-Agent是一个基于通义千问大语言模型构建的智能体开发框架。其核心价值在于将大模型的指令理解、工具调用、任务规划和记忆能力封装成易于使用的模块，帮助开发者快速构建功能丰富的AI应用。该框架原生支持函数调用、代码解释器、检索增强生成等高级功能，并集成了对MCP协议和Chrome浏览器扩展的支持，极大地拓展了智能体的应用边界。通过该框架，开发者可以便捷地开发出类似“浏览器助手”、“代码解释器”和“自定义智能体”等实用应用。目前，Qwen-Agent已成为通义千问官方聊天应用的后端技术支撑，展现了其在生产环境中的可靠性。无论是希望为现有产品添加AI能力，还是构建全新的智能体应用，Qwen-Agent都提供了一个强大且灵活的基础设施。

💡 应用场景

最适合需要AI智能体执行复杂多步任务、调用多种工具并与外部系统交互的场景。

浏览器智能助手

问题：开发者需要让AI助手能够实时浏览网页、获取最新信息并执行操作，但现有工具无法与浏览器深度集成。

方案：使用Qwen-Agent的Chrome扩展功能，让Qwen模型能够控制浏览器、读取网页内容、填写表单、点击按钮等。

示例：让AI助手帮你自动填写在线表格、从多个网页收集数据并整理成报告、或者自动完成重复的网页操作任务。

代码解释与执行

问题：开发者需要让AI不仅能生成代码，还能实际执行代码、查看结果并基于结果继续优化。

方案：利用Qwen-Agent的代码解释器功能，让AI在安全环境中执行Python代码，并根据执行结果进行下一步操作。

示例：让AI分析数据文件：上传CSV文件→AI编写分析代码→执行代码→生成可视化图表→基于结果进一步分析。

多工具协同工作流

问题：开发者需要构建复杂的AI应用，需要模型能够按计划调用多个工具、处理多轮对话并记住上下文。

方案：使用Qwen-Agent的规划、工具调用和记忆能力，构建支持多步推理和工具链调用的智能体。

示例：构建数据分析助手：用户提问→AI规划步骤→调用数据库查询→调用计算工具→调用可视化工具→生成最终报告。

企业知识库问答

问题：企业需要基于内部文档构建智能问答系统，但现有方案难以处理复杂的多文档检索和推理。

方案：结合Qwen-Agent的RAG功能和工具调用能力，构建能够理解上下文、引用准确来源的问答系统。

示例：员工询问公司政策：AI检索相关文档→提取关键信息→结合多个文档内容→生成准确回答并注明出处。

📊 项目信息

语言: Python
Stars: ⭐ 15,011
Forks: 1,436
今日新增: +586
排名: #6
收录: 总榜
趋势日期: 2026年3月7日
最后推送: 2026/3/4

🏷️ 标签

Python大语言模型智能体框架工具调用可扩展开发者

📸 截图

Qwen-Agent 5分钟快速开始

基于Qwen的智能体框架，快速搭建支持工具调用的AI应用

🖥️ 操作系统

macOSWindowsLinux

⚙️ 运行环境

Python>=3.8

🔧 工具

pip— Python包管理

📝 操作步骤

安装Qwen-Agent

使用pip安装稳定版本

安装Qwen-Agent包

$ pip install qwen-agent

✓预期输出：Successfully installed qwen-agent-xxx 等依赖包信息

💡确保网络连接正常，可添加 -i https://pypi.tuna.tsinghua.edu.cn/simple 加速

设置模型服务

配置DashScope API密钥或部署本地模型服务

设置环境变量（Linux/macOS）

$ export DASHSCOPE_API_KEY='your-api-key'

设置环境变量（Windows）

$ set DASHSCOPE_API_KEY=your-api-key

✓预期输出：无错误提示，环境变量设置成功

💡如果没有DashScope API，可跳过此步，但后续需要部署本地模型服务

运行简单示例

创建一个基础智能体并测试对话

运行Python代码测试智能体

$ python -c "from qwen_agent import Assistant; agent = Assistant(); print(agent.chat('你好'))"

✓预期输出：智能体回复如 '你好！我是Qwen智能体，有什么可以帮您的？'

💡首次运行可能需要下载模型，确保网络畅通

✅ 验证成功

智能体正确响应对话请求

✓看到智能体的回复文本
✓无错误信息输出

⚡ 快速提示

模型服务使用DashScope API可免部署，快速体验

进阶学习查看examples目录获取更多应用示例

🔍 常见问题排查

❓ 安装失败，提示网络错误

→ 检查网络或使用国内镜像源如 -i https://pypi.tuna.tsinghua.edu.cn/simple

❓ 运行时报错 'DASHSCOPE_API_KEY not set'

→ 确保正确设置环境变量或部署本地模型服务

🎯 下一步

探索内置工具如代码解释器

参考FAQ启用Docker运行代码解释器

开发自定义智能体

基于BaseTool和Agent类扩展功能

难度

初级

预计时间

1-2天

目标人群

具备Python基础，希望了解大语言模型智能体开发，想快速上手构建AI应用的开发者。对LLM工具调用、智能体框架感兴趣的新手。

🎯 学完你将掌握

能够使用Qwen-Agent框架创建一个具备工具调用能力的智能体，并为其部署一个简单的Web交互界面。

📋 前置知识

Python编程基础熟悉

Qwen-Agent是一个Python框架，需要能理解基本的Python语法、包管理和面向对象概念。

Git与GitHub基础了解

用于克隆项目、查看示例代码和文档。

命令行/终端基础了解

用于安装依赖、设置环境变量和运行Python脚本。

大语言模型（LLM）基本概念了解(可选)

了解什么是提示词（Prompt）、函数调用（Function Call）等，有助于理解框架工作原理。

📚 学习资源

必看

Qwen-Agent Documentation

项目首页提供的官方文档链接，包含更详细的API说明、配置指南和高级用法。

必看

GitHub仓库 `examples/` 目录

最直接的学习材料，包含了Browser Assistant, Code Interpreter, Custom Assistant等多个完整应用示例。

🗺️ 学习阶段

环境准备与基础认知

⏱ 1-2小时

创建Python虚拟环境

使用conda或venv创建一个新的Python环境（建议Python 3.10+），避免包冲突。

💡Gradio 5+需要Python 3.10或更高版本。

安装Qwen-Agent

在虚拟环境中，通过PyPI安装稳定版：`pip install qwen-agent`。或者克隆GitHub仓库，安装开发版。

💡新手建议直接从PyPI安装稳定版。

获取模型访问权限

决定使用DashScope API（阿里云服务）或本地部署开源模型。如果选择DashScope，需要申请API Key并设置环境变量`DASHSCOPE_API_KEY`。

💡对于新手，使用DashScope API是最快开始的方式，无需本地GPU。记得设置环境变量：`export DASHSCOPE_API_KEY='your-key'`（Linux/Mac）或 `set DASHSCOPE_API_KEY=your-key`（Windows）。

浏览项目结构

克隆或下载项目后，快速浏览`examples/`目录，了解官方提供的几个Demo（如Browser Assistant, Code Interpreter），对项目能做什么有个直观印象。

快速入门：创建第一个智能体

⏱ 2-3小时

运行最简单的示例

在`examples/`目录下找一个最简单的示例脚本（例如`basic_demo.py`或类似），尝试运行它，确保环境和API Key配置正确。

💡首次运行可能会下载一些模型或工具依赖，耐心等待。

理解核心组件：LLM与Tool

阅读README中“Developing Your Own Agent”部分的示例代码。重点关注：1. 如何初始化一个LLM对象（如`QwenChat`）。2. 如何定义一个简单的自定义工具（继承`BaseTool`）。3. 如何将工具列表传给Agent。

💡不必完全理解所有细节，先关注代码的整体流程：定义工具 -> 创建Agent -> 调用Agent.run()。

动手实践：创建一个问答智能体

模仿示例，编写一个简单的脚本。创建一个使用DashScope Qwen模型的Agent，并为其添加一个内置工具（如`code_interpreter`或`web_search`，如果可用），然后向它提一个问题，观察其调用工具和回复的过程。

核心功能探索与GUI部署

⏱ 2-3小时

为智能体添加Web界面

使用框架提供的Gradio集成功能。参考README中的GUI示例代码，为你上一步创建的智能体快速启动一个Gradio Web Demo。

💡通常只需要几行代码：`agent.run_gradio()`或类似方法。在浏览器中打开本地链接进行交互。

探索函数调用（工具调用）

仔细阅读FAQ中关于函数调用的部分。尝试创建一个需要多步工具调用的复杂任务（例如：“查询今天的天气，然后根据天气推荐一首歌”），观察Agent的规划和执行过程。

💡理解“Parallel Function Calls”意味着Agent可以同时调用多个工具。

了解代码解释器工具

阅读FAQ中“How to Use the Code Interpreter Tool?”部分。如果本地安装了Docker，尝试在Agent中启用`code_interpreter`工具，让它执行一些简单的Python计算或绘图任务。

💡⚠️ 注意：首次使用会下载Docker镜像，耗时取决于网络。生产环境需谨慎使用。

深入与扩展

⏱ 2-4小时

学习使用MCP（Model Context Protocol）

阅读README和FAQ中关于MCP的部分。按照指引，尝试配置一个简单的MCP服务器工具（如从公开MCP服务器列表中选择一个），并将其集成到你的Agent中。

💡MCP可以极大地扩展Agent能使用的工具范围，是框架的重要特性。

阅读官方文档和博客

访问项目首页提供的文档（Documentation）链接和博客（Blog）链接。重点关注“长文档问答”（1M tokens）解决方案和最新的技术动态（如Qwen3.5 Agent Demo）。

💡博客和文档包含了更深入的技术原理和最佳实践。

研究高级Agent类

不再只使用高级的`Assistant`类，尝试查看`FnCallAgent`或`ReActChat`等内置Agent的实现，理解它们如何继承自基础的`Agent`类，并尝试模仿创建自己的简单Agent子类。

⚠️ 常见错误

❌ 未正确设置API Key环境变量

✅ 确保环境变量名是`DASHSCOPE_API_KEY`（注意下划线），并且已在当前终端会话中设置。可以通过`echo $DASHSCOPE_API_KEY`（Linux/Mac）或 `echo %DASHSCOPE_API_KEY%`（Windows）检查。

❌ Python版本不兼容

✅ 确保使用Python 3.10或更高版本，特别是想要运行Gradio GUI时。使用`python --version`确认。

❌ 直接运行复杂示例失败

✅ 不要一开始就运行最复杂的Demo（如BrowserQwen）。从最简单的脚本开始，确保基础环境无误后，再逐步添加功能。仔细阅读示例代码的注释和依赖要求。

❌ 忽略工具调用的输出格式

✅ 自定义工具时，必须确保`call`方法返回的格式符合框架要求（通常是包含特定键的字典）。仔细阅读`BaseTool`的文档或参考内置工具的实现。

❌ 在未安装Docker的情况下尝试使用代码解释器

✅ 使用`code_interpreter`工具前，务必先安装并启动Docker服务。可以命令行运行`docker --version`测试。

🚀 后续方向

1. 实战项目：尝试用Qwen-Agent复现一个你感兴趣的小应用，如个人知识库助手、自动化数据报告生成器。 2. 集成外部工具：深入学习MCP，将更多外部API（如数据库、Jira、Slack）集成到Agent中。 3. 研究底层：阅读框架核心模块（如`agent.py`, `tools/`, `llm/`）的源码，理解其设计哲学和工作流程。 4. 性能优化：学习如何为本地部署的模型（使用vLLM/Ollama）配置参数，优化推理速度和吞吐量。 5. 探索生态：研究基于Qwen-Agent构建的成熟应用，如BrowserQwen，了解其架构和实现。