Qwen-Agent 上手实战3 步搭一个会调工具的 AI 助手【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen3.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 机器上起了 vLLM8B 的 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(llmllm_cfg, function_list[code_interpreter]) messages [{role: user, content: 用代码算 1 到 100 的和}] for response in bot.run(messagesmessages): 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 模板原生支持并行工具调用。你只需要给modelmodel_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_asciiFalse)模型决定调用它时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(messagesmessages): print(response)这里发生了什么代码解释器底层是一个 Docker 容器实现在 qwen_agent/tools/code_interpreter.py代码在隔离环境里跑只挂载你指定的工作目录。模型写崩了也不会碰你的主机环境。效果是模型从给你代码升级成给你结果图表文件直接落在工作目录。两个提醒第一次调用会构建容器镜像等依赖拉完再说话生产环境启用前先评估隔离强度官方 README 明确说了这只是基础沙箱。场景把一份 PDF 丢给它直接提问进阶玩法不用自己搭检索管线。要做什么让 Agent 读本地 PDF基于文档内容回答。怎么做Assistant原生支持文件输入PDF、Word、PPT、TXT、HTML 都行。bot Assistant(llmllm_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( llmllm_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最常动的就这几个参数写在哪里默认什么时候改model_type顶层—接 DashScope 用qwen_dashscope本地 OpenAI 兼容服务可不写model_server顶层—本地 vLLM/Ollama 必写如http://localhost:8000/v1fncall_prompt_typegenerate_cfgnousQwen3 系列用默认即可旧模板按官方示例传参thought_in_contentgenerate_cfgFalse思考内容混在 content 的 think 标签里时设True影响工具调用解析max_input_tokensgenerate_cfg较大值输入可能超模型窗口时设上限超出自动截断use_raw_apigenerate_cfgFalseQwen3-Coder 搭配 vLLM 原生 tool-call 解析时设Truetop_p等生成参数generate_cfg—直接透传给模型 API按服务商规范传硬件给两档参考按 vLLM 部署 Qwen3 估算最低能跑8B 量化版单卡 8–12G 显存。工具调用、RAG、MCP 全功能可用。推荐32B 级量化约 20G 显存。多步规划和长文档场景下工具调用明显更稳。一个容易翻车的点QwQ 和 Qwen3 启动 vLLM 时不要加--enable-auto-tool-choice和--tool-call-parser hermesQwen-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 Qwen3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考