通义千问 Agent 框架：让大模型真正"动起来"的利器

2026年2月，阿里通义千问团队开源 Qwen3.5，再次刷新开源大模型性能榜单。而鲜为人知的是，在 Qwen 背后，有一套同样来自阿里团队、专门为 Qwen 模型量身打造的智能体开发框架——这就是 GitHub 星标超 16,000 颗的 Qwen-Agent。

Qwen-Agent 官方 Logo

图1：Qwen-Agent 官方 Logo

如果你对 AI 的认知还停留在"调 API 生成文字"的阶段，Qwen-Agent 将彻底刷新你的想象：它让 Qwen 模型不仅能说，更能执行任务——自动调用工具、搜索网页、写代码并运行、读写本地文件、控制浏览器、操作数据库。换句话说，它把大模型从"高级复读机"变成了真正的数字工作者。

一、项目起源：为什么阿里要自研 Agent 框架？

时间拨回 2023 年 9 月。彼时大语言模型（LLM）正如火如荼，但开发者们面临一个共同的痛点：模型虽强，却不知道怎么让它真正完成任务。

一个典型场景是：用户对 AI 说"帮我查一下北京今天的天气，然后写一封邮件告诉王总明天要带伞"。这需要 AI 连续完成三个操作——天气查询（调用工具）、邮件撰写（生成内容）、邮件发送（调用工具）——这可不是单次 API 调用能搞定的。

通义千问团队正是看到了这一需求，推出了 Qwen-Agent。它的定位很明确：基于 Qwen 模型的指令遵循、工具调用、任务规划和记忆管理能力，构建一套完整的 LLM 应用开发框架。从架构设计上，它既服务于阿里内部的 Qwen Chat 产品，也为外部开发者提供了一套开箱即用的智能体构建工具链。

二、架构拆解：两层设计如何让开发变简单？

Qwen-Agent 采用了精心设计的两层架构，这是它区别于其他 Agent 框架的核心亮点。

底层（LLM + 工具基础层）：包含 Qwen 系列模型的核心调用封装（llm/ 目录）、基础工具接口（tools/）、记忆管理（memory/）。开发者无需深入了解底层细节，直接调用上层 API 即可。

顶层（Agent 组件层）：提供了多种开箱即用的智能体实现：

Assistant：通用助手，最基础的智能体类型
BrowserAssistant：浏览器助手，能自动操作 Chrome 浏览器抓取网页、执行搜索
CodeInterpreter：代码解释器，内置 Jupyter 集成，可执行 Python 代码并返回结果
CustomAssistant：自定义助手模板，开发者可在此基础上定制自己的智能体

这种"底层标准化 + 顶层组件化"的设计，让 Qwen-Agent 的学习曲线极为平滑。即使你不懂 LangChain 的复杂链式调用，只要会 Python，就能用几行代码构建一个功能完整的智能体。

Qwen 团队 GitHub 头像

图2：Qwen 团队 GitHub 头像

qwen_agent/ 核心目录速览：

目录/文件	职责	开发者价值
`llm/`	大模型调用封装	支持 DashScope、OpenAI 兼容 API、vLLM、Ollama
`agents/`	多种智能体实现	直接继承使用，无需从零开发
`tools/`	工具集（搜索/代码解释器/MCP/图像等）	按需组合，灵活扩展
`memory/`	对话记忆管理	支持多轮上下文保持
`gui/web_ui.py`	Gradio Web UI	快速搭建演示界面
`qwen_server/`	完整后端服务	一键部署生产级应用

三、核心能力：从"聊天"到"干活"的关键一步

3.1 函数调用（Function Calling）

这是 Qwen-Agent 最基础也最重要的能力。传统的 AI 对话只能返回文字，而 Function Calling 让模型能结构化地输出工具调用指令。例如，当用户说"帮我把这份 PDF 翻译成英文"，模型可以输出：

tool_call: {
  name: "doc_parser",
  arguments: {"file_path": "report.pdf", "target_lang": "en"}
}

Qwen-Agent 内置了 Nous Function Call 模板，对 Qwen2.5 系列和 QwQ-32B 推理模型做了专门优化，同时也支持 vLLM 的原生工具调用解析。

3.2 检索增强生成（RAG）

对于需要处理私有知识库的企业用户，Qwen-Agent 提供了完整的 RAG 能力链：文档解析（PDF/DOCX/PPT/TXT）→ 向量检索（BM25 + jieba 分词）→ 答案生成。配套的 rag 扩展包（pip install qwen-agent[rag]）一次性安装所有依赖。

3.3 代码解释器（Code Interpreter）

这是 Qwen-Agent 最令人惊艳的功能之一。它在后台运行一个 Jupyter Notebook 服务器，智能体可以：

生成并执行 Python 代码：数据分析、数学计算、图像处理……Python 能做的，它都能做
返回执行结果：包括文本输出、图表、数据表格
处理复杂多步推理：例如"先计算这道数学题，再把结果写入文件"

该功能依赖 code_interpreter 扩展包（pip install qwen-agent[code_interpreter]），包含 Jupyter、FastAPI、anyio 等组件。

3.4 MCP（Model Context Protocol）支持

MCP 是 Anthropic 提出的模型上下文协议，Qwen-Agent 在 2025 年 5 月添加了对 MCP 的完整支持，包括 mcp_manager.py 和多个 MCP 使用示例（examples/mcp_*.py）。这让 Qwen-Agent 可以无缝连接外部数据源和工具——Notion 数据库、GitHub 仓库、企业微信……只要支持 MCP，就能接入。

3.5 浏览器控制（Browser Assistant）

内置浏览器自动化能力，能自动操作 Chrome 浏览器：

打开指定网页
执行搜索
提取网页内容（通过 web_extractor.py）
支持 JavaScript 渲染页面的内容提取

对于需要实时获取网页数据的场景（如竞品监控、舆情分析），这是非常实用的能力。

3.6 Qwen3 系列深度集成

2026 年 2 月配合 Qwen3.5 开源，Qwen-Agent 同步更新了对 Qwen3 系列的全方位支持：

新增 examples/assistant_qwen3.5.py 示例
支持 Qwen3-VL 多模态工具调用（图像缩放、图像搜索、网页搜索联动）
支持 Qwen3-Coder 编程助手模式，结合 vLLM 可实现端到端代码生成+执行

四、部署体验：上手有多难？

对于普通用户，Qwen-Agent 提供了一条零门槛的启动路径——DashScope 云端 API。只需：

pip install qwen-agent
export DASHSCOPE_API_KEY="your-api-key"
python run_server.py

然后打开浏览器访问 http://localhost:8080，就能看到基于 Gradio 的 Web UI，支持多轮对话、文件上传、工具调用结果展示。

对于有更高定制需求的开发者（如企业内网部署、私有模型调用），Qwen-Agent 同时支持：

OpenAI 兼容 API：连接 vLLM、Ollama 等本地部署的模型
自定义工具注册：通过继承 BaseTool 类，5 分钟就能写一个新工具
服务器部署：qwen_server/ 目录提供了完整的 FastAPI 后端，可对接企业 IT 系统

硬件要求方面，核心框架本身不需要 GPU，但如果你想让模型在本地运行推理（而非调用云端 API），则需要参考 Qwen 模型本身的硬件需求（通常 7B 模型需要 16GB+ VRAM）。

五、局限与挑战：好东西也有不完美的地方

诚实地讲，Qwen-Agent 也有它需要正视的短板：

无容器化支持：没有提供 Dockerfile 或 docker-compose。对于需要一键部署到 Kubernetes 或 Docker 环境的企业用户，需要自己编写 Dockerfile。好在 setup.py 规范清晰，pip install -e . 即可完成安装。
依赖管理较复杂：核心功能拆成了多个可选扩展包（RAG、MCP、Code Interpreter、GUI），初学者可能需要花时间理解它们之间的依赖关系。基础包约 11 个依赖，全量安装可能超过 50 个包。
工具调用的稳定性：在复杂多步任务中，工具调用的错误率会随步骤增加而累积。例如代码解释器中执行的代码如果含有 bug，智能体需要通过多次迭代才能修复，对话轮次会明显增多。
对 Qwen 模型的强依赖：虽然理论上支持 OpenAI 兼容接口，但在实际使用中，针对 Qwen 模型的 Function Call 模板和工具调用解析做了深度优化，换用其他模型可能需要额外的适配工作。

六、行业意义：开源 Agent 框架的标杆之作

Qwen-Agent 的价值不仅在于它本身，更在于它代表了一种趋势：基础模型公司向下延伸，提供完整应用开发栈。

从数字上看，该项目在 GitHub 拥有 16,408 颗星标、1,617 个 Fork、495 个 open issue，说明它已经形成了活跃的开发者社区。更值得注意的是，它是 Qwen Chat（chat.qwen.ai）的后端，这意味着它经受了阿里亿级用户的生产环境验证。

2025 年 1 月，Qwen-Agent 团队还开源了 DeepPlanning 评测基准，专门评估智能体的长程规划能力，这进一步巩固了其在 AI Agent 研究领域的影响力。对比 LangChain、AutoGen 等同类框架，Qwen-Agent 的优势在于与 Qwen 模型的无缝集成和中文场景的深度优化（如中文分词、文档解析对中文 PDF 的支持）。

七、总结：谁应该关注 Qwen-Agent？

角色	推荐理由
AI 爱好者	通过 Web UI 体验 AI 自动执行任务的能力，了解大模型"工具调用"的工作原理
Python 开发者	快速构建 AI 原生应用，无需学习复杂的 LangChain 概念，用熟悉的工具链开发
企业 IT/AI 团队	基于 Qwen-Agent 构建客服机器人、文档问答、数据分析等生产级应用
AI 研究者	DeepPlanning 评测基准和丰富的 Agent 实现源码是研究智能体规划能力的好素材

Qwen-Agent 用实力证明：AI 的下一阶段，不是更强的模型，而是能让模型真正"干活"的框架。

如果你对 AI Agent 感兴趣，Qwen-Agent 无疑是一个值得深入研究的起点。它既有阿里团队背书的稳定性，又保持了对社区完全开源的姿态。无论你是想快速搭一个 AI 助手原型，还是在企业级场景中构建复杂的自动化工作流，Qwen-Agent 都值得一试。

项目地址：https://github.com/QwenLM/Qwen-Agent 官网体验：https://chat.qwen.ai/ 文档：https://qwenlm.github.io/Qwen-Agent/en/

通义千问 Agent 框架：让大模型真正"动起来"的利器

Qwen-Agent 官方 Logo

图1：Qwen-Agent 官方 Logo

一、项目起源：为什么阿里要自研 Agent 框架？

时间拨回 2023 年 9 月。彼时大语言模型（LLM）正如火如荼，但开发者们面临一个共同的痛点：模型虽强，却不知道怎么让它真正完成任务。

二、架构拆解：两层设计如何让开发变简单？

Qwen-Agent 采用了精心设计的两层架构，这是它区别于其他 Agent 框架的核心亮点。

顶层（Agent 组件层）：提供了多种开箱即用的智能体实现：

Assistant：通用助手，最基础的智能体类型
BrowserAssistant：浏览器助手，能自动操作 Chrome 浏览器抓取网页、执行搜索
CodeInterpreter：代码解释器，内置 Jupyter 集成，可执行 Python 代码并返回结果
CustomAssistant：自定义助手模板，开发者可在此基础上定制自己的智能体

Qwen 团队 GitHub 头像

图2：Qwen 团队 GitHub 头像

qwen_agent/ 核心目录速览：

目录/文件	职责	开发者价值
`llm/`	大模型调用封装	支持 DashScope、OpenAI 兼容 API、vLLM、Ollama
`agents/`	多种智能体实现	直接继承使用，无需从零开发
`tools/`	工具集（搜索/代码解释器/MCP/图像等）	按需组合，灵活扩展
`memory/`	对话记忆管理	支持多轮上下文保持
`gui/web_ui.py`	Gradio Web UI	快速搭建演示界面
`qwen_server/`	完整后端服务	一键部署生产级应用

三、核心能力：从"聊天"到"干活"的关键一步

3.1 函数调用（Function Calling）

tool_call: {
  name: "doc_parser",
  arguments: {"file_path": "report.pdf", "target_lang": "en"}
}

Qwen-Agent 内置了 Nous Function Call 模板，对 Qwen2.5 系列和 QwQ-32B 推理模型做了专门优化，同时也支持 vLLM 的原生工具调用解析。

3.2 检索增强生成（RAG）

3.3 代码解释器（Code Interpreter）

这是 Qwen-Agent 最令人惊艳的功能之一。它在后台运行一个 Jupyter Notebook 服务器，智能体可以：

生成并执行 Python 代码：数据分析、数学计算、图像处理……Python 能做的，它都能做
返回执行结果：包括文本输出、图表、数据表格
处理复杂多步推理：例如"先计算这道数学题，再把结果写入文件"

该功能依赖 code_interpreter 扩展包（pip install qwen-agent[code_interpreter]），包含 Jupyter、FastAPI、anyio 等组件。

3.4 MCP（Model Context Protocol）支持

3.5 浏览器控制（Browser Assistant）

内置浏览器自动化能力，能自动操作 Chrome 浏览器：

打开指定网页
执行搜索
提取网页内容（通过 web_extractor.py）
支持 JavaScript 渲染页面的内容提取

对于需要实时获取网页数据的场景（如竞品监控、舆情分析），这是非常实用的能力。

3.6 Qwen3 系列深度集成

2026 年 2 月配合 Qwen3.5 开源，Qwen-Agent 同步更新了对 Qwen3 系列的全方位支持：

新增 examples/assistant_qwen3.5.py 示例
支持 Qwen3-VL 多模态工具调用（图像缩放、图像搜索、网页搜索联动）
支持 Qwen3-Coder 编程助手模式，结合 vLLM 可实现端到端代码生成+执行

四、部署体验：上手有多难？

对于普通用户，Qwen-Agent 提供了一条零门槛的启动路径——DashScope 云端 API。只需：

pip install qwen-agent
export DASHSCOPE_API_KEY="your-api-key"
python run_server.py

然后打开浏览器访问 http://localhost:8080，就能看到基于 Gradio 的 Web UI，支持多轮对话、文件上传、工具调用结果展示。

对于有更高定制需求的开发者（如企业内网部署、私有模型调用），Qwen-Agent 同时支持：

OpenAI 兼容 API：连接 vLLM、Ollama 等本地部署的模型
自定义工具注册：通过继承 BaseTool 类，5 分钟就能写一个新工具
服务器部署：qwen_server/ 目录提供了完整的 FastAPI 后端，可对接企业 IT 系统

五、局限与挑战：好东西也有不完美的地方

诚实地讲，Qwen-Agent 也有它需要正视的短板：

无容器化支持：没有提供 Dockerfile 或 docker-compose。对于需要一键部署到 Kubernetes 或 Docker 环境的企业用户，需要自己编写 Dockerfile。好在 setup.py 规范清晰，pip install -e . 即可完成安装。
依赖管理较复杂：核心功能拆成了多个可选扩展包（RAG、MCP、Code Interpreter、GUI），初学者可能需要花时间理解它们之间的依赖关系。基础包约 11 个依赖，全量安装可能超过 50 个包。
工具调用的稳定性：在复杂多步任务中，工具调用的错误率会随步骤增加而累积。例如代码解释器中执行的代码如果含有 bug，智能体需要通过多次迭代才能修复，对话轮次会明显增多。
对 Qwen 模型的强依赖：虽然理论上支持 OpenAI 兼容接口，但在实际使用中，针对 Qwen 模型的 Function Call 模板和工具调用解析做了深度优化，换用其他模型可能需要额外的适配工作。

六、行业意义：开源 Agent 框架的标杆之作

Qwen-Agent 的价值不仅在于它本身，更在于它代表了一种趋势：基础模型公司向下延伸，提供完整应用开发栈。

七、总结：谁应该关注 Qwen-Agent？

角色	推荐理由
AI 爱好者	通过 Web UI 体验 AI 自动执行任务的能力，了解大模型"工具调用"的工作原理
Python 开发者	快速构建 AI 原生应用，无需学习复杂的 LangChain 概念，用熟悉的工具链开发
企业 IT/AI 团队	基于 Qwen-Agent 构建客服机器人、文档问答、数据分析等生产级应用
AI 研究者	DeepPlanning 评测基准和丰富的 Agent 实现源码是研究智能体规划能力的好素材

Qwen-Agent 用实力证明：AI 的下一阶段，不是更强的模型，而是能让模型真正"干活"的框架。

项目地址：https://github.com/QwenLM/Qwen-Agent 官网体验：https://chat.qwen.ai/ 文档：https://qwenlm.github.io/Qwen-Agent/en/