Skip to main content

10 · Qwen-Agent：模型厂自带框架长什么样

Qwen-Agent

图片来源：QwenLM/Qwen-Agent

仓库QwenLM/Qwen-Agent
Star17.0k
最后提交2026-03-04（节奏偏慢，但仍在更新，2026-02 刚适配 Qwen3.5）
语言Python
许可证Apache 2.0
层级Framework
一句话阿里通义团队围绕 Qwen 模型能力做的官方 Agent 框架，也是 Qwen Chat 的后端

一、它的特殊身份：不是「通用框架」，是「模型的配套」​

本专题里其他框架都在追求模型中立，Qwen-Agent 反过来 —— 它的设计前提就是「你在用 Qwen」。官方自述：

基于 Qwen 的指令遵循、工具使用、规划、记忆能力开发 LLM 应用的框架。

这个定位带来一个很实在的好处：框架里的 function call 模板是跟着 Qwen 各代模型手工调过的。

README 里有一段细节很能说明问题：

  • QwQ / Qwen3：建议 vLLM 部署时不要加 --enable-auto-tool-choice 和 --tool-call-parser hermes，因为 Qwen-Agent 会自己解析工具输出
  • Qwen3-Coder：建议开启这两个参数，用 vLLM 内置解析，配合 use_raw_api

这种「哪代模型该用哪种解析方式」的知识，通用框架里是拿不到的。 如果你在自建 vLLM 上跑 Qwen 系列做工具调用，这一条能省掉好几天的调试。相关部署细节可以对照 vLLM 快速部署入门。

二、核心抽象：Agent / BaseTool / BaseChatModel​

它的分层很传统，也很好懂：

层基类说明
模型BaseChatModel自带 function calling
工具BaseTool@register_tool 注册，类属性声明 description / parameters
AgentAgentAssistant 等预置实现，也可继承自定义

完整例子​

import json5, urllib.parse
from qwen_agent.agents import Assistant
from qwen_agent.tools.base import BaseTool, register_tool

# 1. 自定义工具：继承 BaseTool + 用类属性声明，而不是从函数签名推断
@register_tool('my_image_gen')          # 注册到全局工具表，后面用这个名字引用
class MyImageGen(BaseTool):
    # description 给模型看，决定它「什么时候调这个工具」
    description = 'AI painting (image generation) service, input text description, and return the image URL.'
    # parameters 手写 JSON Schema —— 比装饰器方案啰嗦，但你写什么模型就看到什么
    parameters = [{
        'name': 'prompt',
        'type': 'string',
        'description': 'Detailed description of the desired image content, in English',
        'required': True
    }]

    def call(self, params: str, **kwargs) -> str:
        # 注意 params 是模型生成的 JSON 字符串，要自己解析。
        # 用 json5 而不是 json，是因为模型偶尔会输出单引号、尾逗号这类不严格的 JSON
        prompt = urllib.parse.quote(json5.loads(params)['prompt'])
        # 返回值也必须是字符串，会被原样塞回对话历史给模型看
        return json5.dumps({'image_url': f'https://image.pollinations.ai/prompt/{prompt}'},
                           ensure_ascii=False)

# 2. 配置模型：DashScope 或任意 OpenAI 兼容服务
llm_cfg = {
    'model': 'qwen-max-latest',
    'model_type': 'qwen_dashscope',      # 走阿里云百炼；API Key 从 DASHSCOPE_API_KEY 读

    # 换成自建 vLLM / Ollama：注释掉上面两行，改用下面三行（OpenAI 兼容协议）
    # 'model': 'Qwen3-8B',
    # 'model_server': 'http://localhost:8000/v1',   # 也就是 base_url
    # 'api_key': 'EMPTY',                           # 本地服务通常不校验

    'generate_cfg': {'top_p': 0.8},      # 采样参数，直接透传给模型
}

# 3. 创建 Agent —— 注意 files 参数：直接喂 PDF，内置 RAG
bot = Assistant(
    llm=llm_cfg,
    system_message='...',
    # function_list 传的是工具「名字」，其中 code_interpreter 是内置的
    # 代码执行工具（基于本地 Docker 沙箱），不用你自己实现
    function_list=['my_image_gen', 'code_interpreter'],
    # files 一传，框架自动做切分 + 向量化 + 检索 —— 内置 RAG，
    # 不用自己搭向量库。这是 Qwen-Agent 最省事的地方之一
    files=['./examples/resource/doc.pdf'],
)

# 4. 跑起来（流式）
messages = [{'role': 'user', 'content': '画一只狗然后旋转 90 度'}]
# bot.run() 是生成器：每产生一点内容就 yield 一次当前的完整响应列表，
# 所以做打字机效果时是「整体替换」而不是「追加」，这点和别的框架不同
for response in bot.run(messages=messages):
    ...
# 想接着多轮对话，就把 response 追加回 messages 再调一次

BaseTool 用类属性声明参数，而不是从函数签名推断 —— 这比 LangChain 的 @tool 或 Pydantic AI 啰嗦，但胜在显式，schema 里写什么就是什么。

三、开箱即用的三件套​

Qwen-Agent 的实用主义体现在：几个最常用的能力是内置的，不用自己拼。

能力怎么用说明
Code Interpreterfunction_list=['code_interpreter']基于本地 Docker 容器的沙箱执行
RAGfiles=['doc.pdf']直接把文件交给 Agent，内置切分 + 检索
GUIWebUI(bot).run()一行代码起 Gradio 界面
from qwen_agent.gui import WebUI
# 一行起一个 Gradio 聊天界面，自带文件上传、流式输出、工具调用展示。
# 做内部工具或给业务方演示时，这一行能省掉一整个前端
WebUI(bot).run()

这三行相加，等于别的框架里好几天的活。 尤其是 WebUI(bot).run() —— 做内部工具、做 Demo 给业务方看的时候，这一行的价值被严重低估。

安装时按需选：

# 方括号里是可选依赖，按需装：
#   gui              → Gradio 界面
#   rag              → 文件问答（files 参数要用它）
#   code_interpreter → 代码执行沙箱
#   mcp              → MCP 协议支持
# 只要最小依赖就 pip install -U qwen-agent
pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"
Code Interpreter 的两件事
  1. 需要本机装好 Docker 并运行，首次构建镜像取决于网络
  2. 早期示例里的 python executor 不是沙箱，README 明说只适合本地测试

生产环境跑代码执行，无论用哪个框架，都要认真做沙箱隔离 —— 这和 DeepAgents 的 LocalShellBackend 警告 是同一件事。

四、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"] }
  }
}

怎么读这段配置：

字段含义
mcpServers 的键MCP server 的别名，工具名会以它作前缀
command + args怎么把这个 server 进程启动起来
npx -y临时下载并运行 Node 包，不用预先全局安装
uvxPython 版的 npx，用来跑 Python 写的 MCP server
/path/to/allowed/files文件服务的白名单目录，Agent 只能读写这个目录

到 2026 年，MCP 支持已经是及格线而非加分项 —— 本专题 11 个框架全都支持。

五、DeepPlanning：它还产出评测基准​

2026-01 开源的 DeepPlanning 是一个 Agent 规划能力评测基准。框架团队自己做 benchmark，说明他们的关注点在「模型的 Agent 能力」而不只是「框架的易用性」 —— 这也符合它「模型配套」的身份。

六、优势与短板​

优势​

  • Qwen 适配最好 —— function call 模板、vLLM 参数建议、各代模型差异，都是一手信息
  • 国内可用性 —— DashScope 直连，不用处理网络问题
  • 开箱即用度高 —— Code Interpreter + RAG + WebUI 三件套
  • 代码量小、可读 —— 想看懂一个 Agent 框架内部怎么工作，它是个好读本
  • Apache 2.0

短板（必须说清楚）​

短板影响
迭代节奏慢最后提交 2026-03，本领域 5 个月是一代半
缺少持久执行 / checkpoint长任务崩了从头再来，对比 LangGraph
缺少结构化 HITL没有工具级审批中断机制
多智能体弱有 GroupChat 等，但成熟度远不及 LangGraph / MAF
可观测性弱无内置 tracing，要自己接
生态小17k star 但集成数量和 LangChain 不在一个量级

七、模型厂自带框架这一类，该怎么看​

Qwen-Agent 是一个典型样本。同类还有 OpenAI 的 Agents SDK、Google 的 ADK、Anthropic 的 Claude Agent SDK。

共同规律：

判断标准：这家厂把框架当战略产品（OpenAI、Google、Anthropic 都在持续重投），还是当模型的配套工具（Qwen-Agent 更接近后者）？前者可以长期押注，后者更适合「用它的适配知识，但架构上留退路」。

八、什么时候用 / 什么时候别用​

用它，如果​

  • 主力模型是 Qwen 系列，尤其是自建 vLLM 部署
  • 要快速做内部工具 / Demo —— WebUI(bot).run() 一行起界面
  • 需要开箱即用的 Code Interpreter 和文件问答
  • 有信创 / 数据不出境要求 —— 全链路国产可控
  • 想读一个体量适中的 Agent 框架源码

别用它，如果​

  • 要跑生产级长时任务 —— 缺持久化、缺 HITL、缺可观测性
  • 要做复杂多智能体编排 —— 用 LangGraph
  • 在意迭代速度 —— 5 个月无提交在这个领域是个信号
  • 模型可能会换 —— 它的价值有相当一部分绑在 Qwen 上
一个折中方案

用 Qwen-Agent 的模型适配知识（function call 模板、vLLM 参数），但用 LangGraph 或 LangChain 做编排。 Qwen 在这些框架里都有一等公民的集成（langchain-qwq、DashScope 兼容 OpenAI 协议），你能同时拿到国产模型和成熟运行时。

参考资料