企业官网建设流程全解析

Qwen-Agent 上手实战：3 步搭一个会调工具的 AI 助手

【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen>=3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent

核心关键词：Qwen-Agent长尾关键词：LLM 框架本地模型接入、函数调用（Function Calling）本地实现、代码解释器沙箱执行、PDF 文档问答、MCP 工具接入

场景：模型跑起来了，却只会说不会做

你在自己的 GPU 机器上起了 vLLM，8B 的 Qwen3 已经能接请求了。然后你问它："帮我算一下这份销售数据的环比。"它回了一段看起来挺对的代码，然后就没有然后了。

想让它真的把代码跑掉、把文件读掉，你得自己写工具调用解析、消息拼装、沙箱执行。Qwen-Agent 就是干这个的：一个基于 Qwen 的 Agent 框架，函数调用、RAG 检索、代码沙箱、MCP 接入全是现成组件。适合想在自己机器上或私有环境里搭 AI 应用的开发者，这篇文章带你跑通最小路径，再看三个实战场景。

先跑起来：装包、接模型、开始对话

三条命令装好框架：

# 从 PyPI 安装，按需选择可选依赖 pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]" # 只要最小依赖的话：pip install -U qwen-agent

方括号里是可选依赖：rag管文档问答，code_interpreter管代码沙箱，mcp管外部工具协议，gui管 Web 界面。用不到就别装。

想看仓库里更多可运行脚本，把源码拉下来：

git clone https://gitcode.com/GitHub_Trending/qw/Qwen-Agent

模型服务这边，本地 vLLM 和云端 DashScope 都行，改的是一处配置。以本地 vLLM 为例，一个能对话的 Agent 长这样：

from qwen_agent.agents import Assistant llm_cfg = { 'model': 'Qwen3-8B', 'model_server': 'http://localhost:8000/v1', # vLLM 服务地址 'api_key': 'EMPTY', } # code_interpreter 是内置工具，按名字引用即可 bot = Assistant(llm=llm_cfg, function_list=['code_interpreter']) messages = [{'role': 'user', 'content': '用代码算 1 到 100 的和'}] for response in bot.run(messages=messages): print(response)

跑完你会看到：模型自己生成 Python 代码，框架把它丢进沙箱执行，再把结果带回对话。全程你没写一行工具解析代码。

想跳过终端，加两行代码就能起 Web 界面：

from qwen_agent.gui import WebUI WebUI(bot).run() # 打开浏览器就能和 Agent 对话

examples/ 目录里有 20 多个可直接跑的脚本，从纯函数调用到群聊、多模态都有，挑一个离你业务近的抄就行。

它替你想好了什么：三层抽象

Qwen-Agent 把 LLM 应用拆成三层，每层都是"你实现一小块，框架管一大块"。

LLM 层。qwen_agent/llm/base.py 里的BaseChatModel类统一了对话接口，它做了三件事：把不同服务商的返回格式拉平、按 token 数截断超长输入、把工具调用模板拼进提示词（默认 nous 模板，原生支持并行工具调用）。你只需要给model+model_server，本地 vLLM、Ollama、云端服务都走同一条路。

工具层。自定义工具只需要三样：description告诉模型这工具干嘛的、parameters列表声明入参、一个call()方法。

import json5 from qwen_agent.tools.base import BaseTool, register_tool @register_tool('my_weather') class MyWeather(BaseTool): description = '查询指定城市的天气' parameters = [{ 'name': 'city', 'type': 'string', 'description': '城市名称', 'required': True, }] def call(self, params: str, **kwargs) -> str: city = json5.loads(params)['city'] # 这里换成你自己的天气 API return json5.dumps({'city': city, 'weather': '晴 26 度'}, ensure_ascii=False)

模型决定调用它时，params就是模型生成的 JSON。解析参数、执行、把结果塞回对话，框架全包了。

Agent 层。qwen_agent/agents/assistant.py 的Assistant是最通用的智能体：角色扮演、自动规划、工具调用、文档 RAG 全配齐。特殊场景再继承Agent基类自己写工作流，框架把_call_llm和_call_tool留给你调用。

场景：让 AI 在沙箱里跑你的数据分析

入门级玩法，接上code_interpreter就行。

要做什么：让模型自己写 pandas 代码、安全执行、返回图表。怎么做：直接把需求说给它。

messages = [{'role': 'user', 'content': '读一下这份 CSV，按月汇总销售额并画柱状图'}] for response in bot.run(messages=messages): print(response)

这里发生了什么：代码解释器底层是一个 Docker 容器，实现在 qwen_agent/tools/code_interpreter.py，代码在隔离环境里跑，只挂载你指定的工作目录。模型写崩了也不会碰你的主机环境。效果是：模型从"给你代码"升级成"给你结果"，图表文件直接落在工作目录。

两个提醒：第一次调用会构建容器镜像，等依赖拉完再说话；生产环境启用前先评估隔离强度，官方 README 明确说了这只是基础沙箱。

场景：把一份 PDF 丢给它，直接提问

进阶玩法，不用自己搭检索管线。

要做什么：让 Agent 读本地 PDF，基于文档内容回答。怎么做：Assistant原生支持文件输入，PDF、Word、PPT、TXT、HTML 都行。

bot = Assistant(llm=llm_cfg) messages = [{'role': 'user', 'content': [{'text': '这份报告的第三章讲了什么？'}, {'file': './report.pdf'}]}] for response in bot.run(messages): print(response)

这里发生了什么：装上[rag]依赖后，框架内置的检索组件自动解析文档、切块、建索引，模型回答前先检索相关段落。完整示例在 examples/assistant_rag.py。官方数据：这套 RAG 方案在两个长文档基准上超过了原生长上下文模型，还在 1M token 的"大海捞针"压力测试里全部命中，成本反而更低。

场景：10 行代码接一个现成的 SQLite 数据库

生产级玩法，把 MCP 生态接进你的 Agent。

要做什么：让 Agent 用自然语言查 SQLite 库，不写任何数据库工具代码。怎么做：function_list里塞一段 MCP 配置。

bot = Assistant( llm=llm_cfg, system_message='你扮演一个数据库助手，你具有查询数据库的能力', function_list=[{ 'mcpServers': { 'sqlite': { 'command': 'uvx', 'args': ['mcp-server-sqlite', '--db-path', 'test.db'], } } }], )

完整示例见 examples/assistant_mcp_sqlite_bot.py。这里发生了什么：Qwen-Agent 按 MCP 协议拉起外部进程（这里是uvx启动的 sqlite server），把它暴露的工具并入 Agent 的工具清单。换 memory、filesystem、fetch 服务器，改配置就行。效果：问一句"数据库里有几张表"，Agent 自己拼 SQL、执行、报结果。

参数与调优：默认配置什么时候要改

LLM 相关参数都写在llm_cfg里传给Assistant，最常动的就这几个：

硬件给两档参考（按 vLLM 部署 Qwen3 估算）：

• 最低能跑：8B 量化版，单卡 8–12G 显存。工具调用、RAG、MCP 全功能可用。
• 推荐：32B 级量化，约 20G 显存。多步规划和长文档场景下工具调用明显更稳。

一个容易翻车的点：QwQ 和 Qwen3 启动 vLLM 时不要加--enable-auto-tool-choice和--tool-call-parser hermes，Qwen-Agent 自己会解析工具输出；Qwen3-Coder 相反，建议开启这两个参数并搭配use_raw_api。

踩坑实录

如果你第一次调 code_interpreter 卡住不动，大概率是在构建 Docker 镜像，等一两分钟再问一次。前提是 Docker 服务已启动，docker ps能跑通。

如果工具调用解析出来是乱码或空，先查两处：vLLM 启动参数里是不是多带了 tool-call-parser 相关参数，以及thought_in_content和模型实际输出格式对不对得上。

如果GUI 起不来，确认 Python 是 3.10 以上，并且别手动升级 gradio。setup.py 里 gradio 锁死在 5.23.1，版本错配会直接崩。

如果读 PDF 报错，八成是只装了最小依赖，加上[rag]重装一次就行。

最后说两句

Qwen-Agent 的价值就一句话：模型服务在哪不重要，工具、RAG、沙箱、MCP 都是现成件，你写的是业务配置，不是基础设施。

下一步建议：翻一遍 examples/ 目录，挑一个离业务最近的脚本改造；想深入工作流，读 qwen-agent-docs/ 下的核心模块文档。顺带留意仓库里开源的 DeepPlanning 评测基准（在 benchmark/ 目录），后面做工具调用类 Agent，大概率要拿它当尺子。

【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen>=3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent