Qwen-Agent 快速上手指南基于 Qwen 构建 Function Calling、MCP 与 RAG 智能体【免费下载链接】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-AgentQwen-Agent 是基于 Qwen≥ 3.0 系列模型指令跟随、工具使用、规划与记忆能力构建的 LLM 应用开发框架本文以其官方 Overview 文档为主线系统讲解从环境安装、模型服务配置到编写一个可对话、可调工具、可读文档的智能体的完整路径。读完本文你将掌握 Qwen-Agent 的核心 APIAssistant、BaseTool、WebUI、Tool Calling 解析模式的选择方法以及如何通过几行代码快速搭建并启动一个带 Gradio 界面的智能体应用。Qwen-Agent 是什么Qwen-Agent 是一个用于开发 LLM 应用Agent的框架其核心定位是围绕 Qwen 系列大模型的四类基础能力展开指令跟随instruction following、工具使用tool usage、规划planning与记忆memory。在代码层面框架对外暴露的核心入口位于 qwen_agent/agents/init.py其中既包含可直接使用的通用智能体也包含面向长文档问答、群聊、多智能体路由等场景的专用智能体Assistant集成 RAG 与函数调用能力的通用助手qwen_agent/agents/assistant.pyFnCallAgent集成 LLM 与工具使用能力的函数调用智能体qwen_agent/agents/fncall_agent.pyDocQAAgent/ParallelDocQA长文档问答解决方案GroupChat、GroupChatAutoRouter、GroupChatCreator群聊与多智能体编排ReActChat、Router、TIRMathAgent、VirtualMemoryAgent等。所有智能体最终都继承自class Agentqwen_agent/agent.py。Agent是抽象基类负责消息类型统一转换、系统提示词注入等通用逻辑子类只需在_run方法中实现各自的处理工作流。官方文档将其架构概括为三层原子组件LLM、Tool、高层组件Agent与便捷的 GUI 界面WebUI下文将逐一展开。环境安装Qwen-Agent 可通过 PyPI 安装稳定版本也可从源码安装最新开发版本。两种方式均支持通过双中括号指定可选依赖组# 方式一从 PyPI 安装稳定版推荐 pip install -U qwen-agent[gui,rag,code_interpreter,mcp] # 或者安装最小依赖版本 pip install -U qwen-agent # 方式二从源码安装最新开发版 git clone https://github.com/QwenLM/Qwen-Agent.git cd Qwen-Agent pip install -e ./[gui,rag,code_interpreter,mcp] # 或 pip install -e ./ 安装最小依赖各可选依赖组的用途与 setup.py 中extras_require的定义一致可选依赖用途关键第三方包节选gui基于 Gradio 的图形界面支持gradio5.23.1、pydantic2.9.2、modelscope_studiorag检索增强生成支持rank_bm25、jieba、pdfminer.six、pdfplumber、python-docx、python-pptxcode_interpreter代码解释器支持jupyter、fastapi、uvicornmcpModel Context ProtocolMCP支持mcp此外 setup.py 还单独定义了python_executor可选组面向数学求解场景包含pebble、sympy、numpy等而最小依赖仅包含dashscope、openai、pydantic2.3.0、tiktoken等函数调用所需的核心包。模型服务准备两种接入方式使用智能体前需要先准备模型服务官方提供两条路径使用阿里云 DashScope 提供的模型服务先设置环境变量DASHSCOPE_API_KEY为你的 DashScope API Key。自部署开源 Qwen 模型按照 Qwen3 官方 README 的指引部署 OpenAI 兼容的 API 服务GPU 高吞吐部署可参考 SGLang 或 vLLM 的方案。在代码中通过llm_cfg字典即可灵活切换下文第 5 节有完整示例使用 DashScope 时配置model: qwen-max-latest与model_type: qwen_dashscope使用 vLLM/Ollama 等自部署服务时配置model_server: http://localhost:8000/v1指定base_url。如果不在llm_cfg中显式传入api_key框架会读取DASHSCOPE_API_KEY环境变量。Tool Call 解析器原生解析 vs 框架内置解析Qwen-Agent 支持两种 Tool Call函数调用响应解析方式选择取决于你的模型部署方式模型服务端原生 Tool Call 解析器部分模型部署服务原生支持 Tool Calling此时需在部署时开启对应参数Qwen3-Coder 推荐使用模型服务端的工具解析器即在 vLLM / SGLang 服务上添加--enable-auto-tool-choice与--tool-call-parser qwen3_coder参数该模式与use_raw_api参数配合使用详见下文配置小节官方表示这即将成为默认模式。Qwen-Agent 内置 Tool Call 解析器部分部署方式不具备原生工具调用能力或原生工具调用支持不完整此时可以使用 Qwen-Agent 内置的解析器Qwen-Agent 默认提供hermes解析格式支持 QwQ 与 Qwen3 系列模型的工具调用解析当前这是默认模式对于 QwQ 和 Qwen3 系列模型推荐使用 Qwen-Agent 内置解析器即不要在 vLLM/SGLang 服务端添加--enable-auto-tool-choice与--tool-call-parser hermes参数。从源码看qwen_agent/llm/base.py 中use_raw_api的取值逻辑如下默认读取环境变量QWEN_AGENT_USE_RAW_API默认false也可以通过generate_cfg中的use_raw_api键覆盖特别地当model_type qwen_dashscope且未显式设置时使用Qwen3-Max会自动将其置为True。此外use_raw_api仅支持全量流式full stream输出模式。第一个智能体Chat with an Agent官方 Overview 给出了一个开箱即用的示例——创建一个既能通过 MCP 服务器获取时间/抓取网页、又能调用内置绘图工具的Assistant并分别以命令行流式输出和 Gradio Web UI 两种方式与它对话from qwen_agent.agents import Assistant from qwen_agent.gui import WebUI from qwen_agent.utils.output_beautify import typewriter_print # 定义 LLM 配置 llm_cfg { model: qwen3-max, model_type: qwen_dashscope, } # 定义工具列表 tools [ { mcpServers: { # 可以直接在工具列表中指定 MCP 配置文件 time: { command: uvx, args: [mcp-server-time, --local-timezoneAsia/Shanghai] }, fetch: { command: uvx, args: [mcp-server-fetch] } } }, image_gen, # 内置示例工具 ] # 定义智能体 bot Assistant(llmllm_cfg, function_listtools, nameQwen3 Tool-calling Demo, descriptionIm a demo using the Qwen3 tool calling. Welcome to add and play with your own tools!) # 命令行对话 messages [{role: user, content: draw a cute dog}] response_plain_text for response in bot.run(messagesmessages): response_plain_text typewriter_print(response, response_plain_text) # 图形界面对话 chatbot_config { prompt.suggestions: [ draw a cute dog ] } WebUI( bot, chatbot_configchatbot_config, ).run()这个示例同时展示了 Qwen-Agent 的三个核心用法function_list混合配置列表项既可以是内置工具名字符串如image_gen也可以是携带mcpServers的 MCP 配置字典。关于 MCP 配置qwen_agent/tools/mcp_manager.py 中is_valid_mcp_servers校验的格式为{mcpServers: {服务器名: {command: ..., args: [...]}}}每个服务器子项必须包含command字段。MCPManager以单例形式运行会在独立线程中维护 asyncio 事件循环管理 MCP 客户端并通过 monkey patch 记录子进程以便在退出时清理。流式返回bot.run()返回生成器Iterator[List[Message]]每次 yield 当前已产生的完整增量回复序列。这一行为在 qwen_agent/agents/fncall_agent.py 的_run主循环中实现循环内调用 LLM、检测工具调用、执行工具并把FUNCTION角色消息追加回消息历史直到某轮没有使用任何工具才结束同时受全局MAX_LLM_CALL_PER_RUN调用次数上限约束。流式美化输出typewriter_printqwen_agent/utils/output_beautify.py会把带reasoning_content、content、function_call的助手消息与带工具名/内容的FUNCTION消息格式化为[THINK]、[ANSWER]、[TOOL_CALL]、[TOOL_RESPONSE]等标记的打印文本并只打印新增部分形成打字机效果。仓库还提供了multimodal_typewriter_print可在 Jupyter 中同步展示文本与图片。开发自己的智能体从自定义工具到 PDF 问答QuickStart 文档给出了一个完整的实战案例让智能体先画图、再下载图片、最后对图片做处理其中既包含自定义工具注册也包含内置code_interpreter工具与本地 PDF 文件的组合使用import urllib.parse import json5 from qwen_agent.agents import Assistant from qwen_agent.tools.base import BaseTool, register_tool from qwen_agent.utils.output_beautify import typewriter_print # Step 1可选注册一个名为 my_image_gen 的自定义工具 register_tool(my_image_gen) class MyImageGen(BaseTool): # description 告诉智能体该工具的功能 description AI painting (image generation) service, input text description, and return the image URL drawn based on text information. # parameters 告诉智能体该工具有哪些输入参数 parameters { type: object, properties: { prompt: { type: string, description: Detailed description of the desired image content, in English, } }, required: [prompt], } def call(self, params: str, **kwargs) - str: # params 是由 LLM 智能体生成的参数 prompt json5.loads(params)[prompt] prompt urllib.parse.quote(prompt) return json5.dumps( {image_url: fhttps://image.pollinations.ai/prompt/{prompt}}, ensure_asciiFalse) # Step 2: 配置所使用的 LLM llm_cfg { # 使用 DashScope 提供的模型服务 model: qwen-max-latest, model_type: qwen_dashscope, # api_key: YOUR_DASHSCOPE_API_KEY, # 若此处不设置 api_key则会读取 DASHSCOPE_API_KEY 环境变量 # 使用与 OpenAI API 兼容的模型服务如 vLLM、Ollama # model: Qwen3-8B, # model_server: http://localhost:8000/v1, # base_url即 api_base # api_key: EMPTY, # 可选LLM 生成超参数 generate_cfg: { top_p: 0.8 } } # Step 3: 创建智能体。这里以 Assistant 为例它支持使用工具并读取文件 system_instruction After receiving the users request, you should: - first draw an image and obtain the image url, - then run code request.get(image_url) to download the image, - and finally select an image operation from the given document to process the image. Please show the image using plt.show(). tools [my_image_gen, code_interpreter] # code_interpreter 是内置的代码执行工具 files [./examples/resource/doc.pdf] # 给智能体一个可读取的 PDF 文件 bot Assistant(llmllm_cfg, system_messagesystem_instruction, function_listtools, filesfiles) # Step 4: 以聊天机器人的方式运行智能体 messages [] # 存储聊天历史 while True: # 例如输入 draw a dog and rotate it 90 degrees query input(\nuser query: ) # 将用户问题追加到聊天历史 messages.append({role: user, content: query}) response [] response_plain_text print(bot response:) for response in bot.run(messagesmessages): # 流式输出 response_plain_text typewriter_print(response, response_plain_text) # 将智能体回复追加到聊天历史 messages.extend(response)该示例对应的仓库测试位于 tests/agents/test_assistant.py其中对Assistant的system_message、function_list、files等参数均有覆盖用例test_custom_tool_object.py则展示了通过BaseTool子类对象直接传入function_list的用法。自定义工具的本质register_tool装饰器与BaseTool基类定义在 qwen_agent/tools/base.py每个工具必须实现call(params, **kwargs)抽象方法params为 LLM 生成的参数字符串或字典BaseTool.__init__会校验工具名非空且parameters为字典时必须是合法的 OpenAI 兼容 JSON Schema_verify_json_format_args用于在调用前校验参数格式与必填项通过register_tool(name)注册的工具会被写入全局TOOL_REGISTRYqwen_agent/tools/init.py 中同时导出了CodeInterpreter、DocParser、ImageGen、WebSearch、Storage、Retrieval、MCPManager等内置工具之后在function_list中用字符串名字即可引用若工具需要访问文件可继承BaseToolWithFileAccess它会将远程文件拷贝到自己的工作目录再调用call并在FnCallAgent._call_tool中自动注入消息中携带的文件列表。Assistant相比FnCallAgent额外集成了 RAG 能力qwen_agent/agents/assistant.py 的_prepend_knowledge_prompt当传入files且没有外部knowledge时会先通过self.mem.run()从文件中检索知识再按# Knowledge Base模板把知识片段拼接到系统提示词中从而实现边检索边生成的文档问答。一键启动 GUIWebUI 快速部署除命令行交互外框架提供了基于 Gradio 的图形界面组件WebUI可对任意智能体快速部署 Demofrom qwen_agent.gui import WebUI WebUI(bot).run() # bot 为上文中定义的智能体此处不再重复定义WebUIqwen_agent/gui/web_ui.py的构造函数接收agent与可选的chatbot_config两个参数agent可以是单个智能体Assistant、GroupChat、Router等也可以是MultiAgentHub或智能体列表chatbot_config支持user.name、user.avatar、agent.avatar、input.placeholder、prompt.suggestions等键用于自定义用户昵称、头像、输入框占位符和提示建议词。WebUI的导入路径为qwen_agent.gui.WebUIqwen_agent/gui/init.py底层使用 Gradio 实现。注意 GUI 功能需要额外安装gui可选依赖组见上文安装小节。常用配置参数一览结合 Overview 与 QuickStart 文档将llm_cfg与Assistant的常用参数整理如下参数取值示例说明modelqwen3-max、qwen-max-latest、Qwen3-8B使用的模型名自部署场景填本地模型名model_typeqwen_dashscopeDashScope 模型服务类型使用 OpenAI 兼容服务时可省略model_serverhttp://localhost:8000/v1自部署服务的base_url即api_baseapi_keyYOUR_DASHSCOPE_API_KEY未设置时读取DASHSCOPE_API_KEY环境变量generate_cfg{top_p: 0.8}生成超参数如top_p、max_input_tokens等function_list[image_gen, {...mcpServers...}]工具名、工具配置字典或BaseTool对象组成的列表system_messagestr指定系统提示词用于约束智能体行为files[./examples/resource/doc.pdf]初始化时注入给智能体的文件 URL 列表从源码角度补充两点其一llm_cfg中model_type含dashscope时框架会自动在generate_cfg中开启incremental_output增量流式输出其二当模型为 QwQ/QVQ/Qwen3 系列且使用 DashScope 时FnCallAgent会为内存/检索组件单独分配一个qwen-turbo小模型以节省开销。仓库中 examples/assistant_qwen3.py、examples/function_calling.py、examples/assistant_weather_bot.py 等示例提供了更多组合玩法可作为继续探索的起点。小结从 Overview 文档出发我们完整走通了 Qwen-Agent 的使用闭环安装最小依赖 vs 可选依赖组→ 准备模型服务DashScope 或自部署并选择 Tool Call 解析模式→ 用Assistant写第一个对话智能体CLI 流式 GUI→ 通过BaseTool注册自定义工具并让智能体读写 PDF → 用WebUI一键发布 Gradio 应用。无论是快速原型还是生产级应用这套原子组件 Agent GUI的框架都能显著降低基于 Qwen 的智能体开发门槛。【免费下载链接】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），仅供参考 Qwen-Agent 快速上手指南：基于 Qwen 构建 Function Calling、MCP 与 RAG 智能体
Qwen-Agent 快速上手指南基于 Qwen 构建 Function Calling、MCP 与 RAG 智能体【免费下载链接】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-AgentQwen-Agent 是基于 Qwen≥ 3.0 系列模型指令跟随、工具使用、规划与记忆能力构建的 LLM 应用开发框架本文以其官方 Overview 文档为主线系统讲解从环境安装、模型服务配置到编写一个可对话、可调工具、可读文档的智能体的完整路径。读完本文你将掌握 Qwen-Agent 的核心 APIAssistant、BaseTool、WebUI、Tool Calling 解析模式的选择方法以及如何通过几行代码快速搭建并启动一个带 Gradio 界面的智能体应用。Qwen-Agent 是什么Qwen-Agent 是一个用于开发 LLM 应用Agent的框架其核心定位是围绕 Qwen 系列大模型的四类基础能力展开指令跟随instruction following、工具使用tool usage、规划planning与记忆memory。在代码层面框架对外暴露的核心入口位于 qwen_agent/agents/init.py其中既包含可直接使用的通用智能体也包含面向长文档问答、群聊、多智能体路由等场景的专用智能体Assistant集成 RAG 与函数调用能力的通用助手qwen_agent/agents/assistant.pyFnCallAgent集成 LLM 与工具使用能力的函数调用智能体qwen_agent/agents/fncall_agent.pyDocQAAgent/ParallelDocQA长文档问答解决方案GroupChat、GroupChatAutoRouter、GroupChatCreator群聊与多智能体编排ReActChat、Router、TIRMathAgent、VirtualMemoryAgent等。所有智能体最终都继承自class Agentqwen_agent/agent.py。Agent是抽象基类负责消息类型统一转换、系统提示词注入等通用逻辑子类只需在_run方法中实现各自的处理工作流。官方文档将其架构概括为三层原子组件LLM、Tool、高层组件Agent与便捷的 GUI 界面WebUI下文将逐一展开。环境安装Qwen-Agent 可通过 PyPI 安装稳定版本也可从源码安装最新开发版本。两种方式均支持通过双中括号指定可选依赖组# 方式一从 PyPI 安装稳定版推荐 pip install -U qwen-agent[gui,rag,code_interpreter,mcp] # 或者安装最小依赖版本 pip install -U qwen-agent # 方式二从源码安装最新开发版 git clone https://github.com/QwenLM/Qwen-Agent.git cd Qwen-Agent pip install -e ./[gui,rag,code_interpreter,mcp] # 或 pip install -e ./ 安装最小依赖各可选依赖组的用途与 setup.py 中extras_require的定义一致可选依赖用途关键第三方包节选gui基于 Gradio 的图形界面支持gradio5.23.1、pydantic2.9.2、modelscope_studiorag检索增强生成支持rank_bm25、jieba、pdfminer.six、pdfplumber、python-docx、python-pptxcode_interpreter代码解释器支持jupyter、fastapi、uvicornmcpModel Context ProtocolMCP支持mcp此外 setup.py 还单独定义了python_executor可选组面向数学求解场景包含pebble、sympy、numpy等而最小依赖仅包含dashscope、openai、pydantic2.3.0、tiktoken等函数调用所需的核心包。模型服务准备两种接入方式使用智能体前需要先准备模型服务官方提供两条路径使用阿里云 DashScope 提供的模型服务先设置环境变量DASHSCOPE_API_KEY为你的 DashScope API Key。自部署开源 Qwen 模型按照 Qwen3 官方 README 的指引部署 OpenAI 兼容的 API 服务GPU 高吞吐部署可参考 SGLang 或 vLLM 的方案。在代码中通过llm_cfg字典即可灵活切换下文第 5 节有完整示例使用 DashScope 时配置model: qwen-max-latest与model_type: qwen_dashscope使用 vLLM/Ollama 等自部署服务时配置model_server: http://localhost:8000/v1指定base_url。如果不在llm_cfg中显式传入api_key框架会读取DASHSCOPE_API_KEY环境变量。Tool Call 解析器原生解析 vs 框架内置解析Qwen-Agent 支持两种 Tool Call函数调用响应解析方式选择取决于你的模型部署方式模型服务端原生 Tool Call 解析器部分模型部署服务原生支持 Tool Calling此时需在部署时开启对应参数Qwen3-Coder 推荐使用模型服务端的工具解析器即在 vLLM / SGLang 服务上添加--enable-auto-tool-choice与--tool-call-parser qwen3_coder参数该模式与use_raw_api参数配合使用详见下文配置小节官方表示这即将成为默认模式。Qwen-Agent 内置 Tool Call 解析器部分部署方式不具备原生工具调用能力或原生工具调用支持不完整此时可以使用 Qwen-Agent 内置的解析器Qwen-Agent 默认提供hermes解析格式支持 QwQ 与 Qwen3 系列模型的工具调用解析当前这是默认模式对于 QwQ 和 Qwen3 系列模型推荐使用 Qwen-Agent 内置解析器即不要在 vLLM/SGLang 服务端添加--enable-auto-tool-choice与--tool-call-parser hermes参数。从源码看qwen_agent/llm/base.py 中use_raw_api的取值逻辑如下默认读取环境变量QWEN_AGENT_USE_RAW_API默认false也可以通过generate_cfg中的use_raw_api键覆盖特别地当model_type qwen_dashscope且未显式设置时使用Qwen3-Max会自动将其置为True。此外use_raw_api仅支持全量流式full stream输出模式。第一个智能体Chat with an Agent官方 Overview 给出了一个开箱即用的示例——创建一个既能通过 MCP 服务器获取时间/抓取网页、又能调用内置绘图工具的Assistant并分别以命令行流式输出和 Gradio Web UI 两种方式与它对话from qwen_agent.agents import Assistant from qwen_agent.gui import WebUI from qwen_agent.utils.output_beautify import typewriter_print # 定义 LLM 配置 llm_cfg { model: qwen3-max, model_type: qwen_dashscope, } # 定义工具列表 tools [ { mcpServers: { # 可以直接在工具列表中指定 MCP 配置文件 time: { command: uvx, args: [mcp-server-time, --local-timezoneAsia/Shanghai] }, fetch: { command: uvx, args: [mcp-server-fetch] } } }, image_gen, # 内置示例工具 ] # 定义智能体 bot Assistant(llmllm_cfg, function_listtools, nameQwen3 Tool-calling Demo, descriptionIm a demo using the Qwen3 tool calling. Welcome to add and play with your own tools!) # 命令行对话 messages [{role: user, content: draw a cute dog}] response_plain_text for response in bot.run(messagesmessages): response_plain_text typewriter_print(response, response_plain_text) # 图形界面对话 chatbot_config { prompt.suggestions: [ draw a cute dog ] } WebUI( bot, chatbot_configchatbot_config, ).run()这个示例同时展示了 Qwen-Agent 的三个核心用法function_list混合配置列表项既可以是内置工具名字符串如image_gen也可以是携带mcpServers的 MCP 配置字典。关于 MCP 配置qwen_agent/tools/mcp_manager.py 中is_valid_mcp_servers校验的格式为{mcpServers: {服务器名: {command: ..., args: [...]}}}每个服务器子项必须包含command字段。MCPManager以单例形式运行会在独立线程中维护 asyncio 事件循环管理 MCP 客户端并通过 monkey patch 记录子进程以便在退出时清理。流式返回bot.run()返回生成器Iterator[List[Message]]每次 yield 当前已产生的完整增量回复序列。这一行为在 qwen_agent/agents/fncall_agent.py 的_run主循环中实现循环内调用 LLM、检测工具调用、执行工具并把FUNCTION角色消息追加回消息历史直到某轮没有使用任何工具才结束同时受全局MAX_LLM_CALL_PER_RUN调用次数上限约束。流式美化输出typewriter_printqwen_agent/utils/output_beautify.py会把带reasoning_content、content、function_call的助手消息与带工具名/内容的FUNCTION消息格式化为[THINK]、[ANSWER]、[TOOL_CALL]、[TOOL_RESPONSE]等标记的打印文本并只打印新增部分形成打字机效果。仓库还提供了multimodal_typewriter_print可在 Jupyter 中同步展示文本与图片。开发自己的智能体从自定义工具到 PDF 问答QuickStart 文档给出了一个完整的实战案例让智能体先画图、再下载图片、最后对图片做处理其中既包含自定义工具注册也包含内置code_interpreter工具与本地 PDF 文件的组合使用import urllib.parse import json5 from qwen_agent.agents import Assistant from qwen_agent.tools.base import BaseTool, register_tool from qwen_agent.utils.output_beautify import typewriter_print # Step 1可选注册一个名为 my_image_gen 的自定义工具 register_tool(my_image_gen) class MyImageGen(BaseTool): # description 告诉智能体该工具的功能 description AI painting (image generation) service, input text description, and return the image URL drawn based on text information. # parameters 告诉智能体该工具有哪些输入参数 parameters { type: object, properties: { prompt: { type: string, description: Detailed description of the desired image content, in English, } }, required: [prompt], } def call(self, params: str, **kwargs) - str: # params 是由 LLM 智能体生成的参数 prompt json5.loads(params)[prompt] prompt urllib.parse.quote(prompt) return json5.dumps( {image_url: fhttps://image.pollinations.ai/prompt/{prompt}}, ensure_asciiFalse) # Step 2: 配置所使用的 LLM llm_cfg { # 使用 DashScope 提供的模型服务 model: qwen-max-latest, model_type: qwen_dashscope, # api_key: YOUR_DASHSCOPE_API_KEY, # 若此处不设置 api_key则会读取 DASHSCOPE_API_KEY 环境变量 # 使用与 OpenAI API 兼容的模型服务如 vLLM、Ollama # model: Qwen3-8B, # model_server: http://localhost:8000/v1, # base_url即 api_base # api_key: EMPTY, # 可选LLM 生成超参数 generate_cfg: { top_p: 0.8 } } # Step 3: 创建智能体。这里以 Assistant 为例它支持使用工具并读取文件 system_instruction After receiving the users request, you should: - first draw an image and obtain the image url, - then run code request.get(image_url) to download the image, - and finally select an image operation from the given document to process the image. Please show the image using plt.show(). tools [my_image_gen, code_interpreter] # code_interpreter 是内置的代码执行工具 files [./examples/resource/doc.pdf] # 给智能体一个可读取的 PDF 文件 bot Assistant(llmllm_cfg, system_messagesystem_instruction, function_listtools, filesfiles) # Step 4: 以聊天机器人的方式运行智能体 messages [] # 存储聊天历史 while True: # 例如输入 draw a dog and rotate it 90 degrees query input(\nuser query: ) # 将用户问题追加到聊天历史 messages.append({role: user, content: query}) response [] response_plain_text print(bot response:) for response in bot.run(messagesmessages): # 流式输出 response_plain_text typewriter_print(response, response_plain_text) # 将智能体回复追加到聊天历史 messages.extend(response)该示例对应的仓库测试位于 tests/agents/test_assistant.py其中对Assistant的system_message、function_list、files等参数均有覆盖用例test_custom_tool_object.py则展示了通过BaseTool子类对象直接传入function_list的用法。自定义工具的本质register_tool装饰器与BaseTool基类定义在 qwen_agent/tools/base.py每个工具必须实现call(params, **kwargs)抽象方法params为 LLM 生成的参数字符串或字典BaseTool.__init__会校验工具名非空且parameters为字典时必须是合法的 OpenAI 兼容 JSON Schema_verify_json_format_args用于在调用前校验参数格式与必填项通过register_tool(name)注册的工具会被写入全局TOOL_REGISTRYqwen_agent/tools/init.py 中同时导出了CodeInterpreter、DocParser、ImageGen、WebSearch、Storage、Retrieval、MCPManager等内置工具之后在function_list中用字符串名字即可引用若工具需要访问文件可继承BaseToolWithFileAccess它会将远程文件拷贝到自己的工作目录再调用call并在FnCallAgent._call_tool中自动注入消息中携带的文件列表。Assistant相比FnCallAgent额外集成了 RAG 能力qwen_agent/agents/assistant.py 的_prepend_knowledge_prompt当传入files且没有外部knowledge时会先通过self.mem.run()从文件中检索知识再按# Knowledge Base模板把知识片段拼接到系统提示词中从而实现边检索边生成的文档问答。一键启动 GUIWebUI 快速部署除命令行交互外框架提供了基于 Gradio 的图形界面组件WebUI可对任意智能体快速部署 Demofrom qwen_agent.gui import WebUI WebUI(bot).run() # bot 为上文中定义的智能体此处不再重复定义WebUIqwen_agent/gui/web_ui.py的构造函数接收agent与可选的chatbot_config两个参数agent可以是单个智能体Assistant、GroupChat、Router等也可以是MultiAgentHub或智能体列表chatbot_config支持user.name、user.avatar、agent.avatar、input.placeholder、prompt.suggestions等键用于自定义用户昵称、头像、输入框占位符和提示建议词。WebUI的导入路径为qwen_agent.gui.WebUIqwen_agent/gui/init.py底层使用 Gradio 实现。注意 GUI 功能需要额外安装gui可选依赖组见上文安装小节。常用配置参数一览结合 Overview 与 QuickStart 文档将llm_cfg与Assistant的常用参数整理如下参数取值示例说明modelqwen3-max、qwen-max-latest、Qwen3-8B使用的模型名自部署场景填本地模型名model_typeqwen_dashscopeDashScope 模型服务类型使用 OpenAI 兼容服务时可省略model_serverhttp://localhost:8000/v1自部署服务的base_url即api_baseapi_keyYOUR_DASHSCOPE_API_KEY未设置时读取DASHSCOPE_API_KEY环境变量generate_cfg{top_p: 0.8}生成超参数如top_p、max_input_tokens等function_list[image_gen, {...mcpServers...}]工具名、工具配置字典或BaseTool对象组成的列表system_messagestr指定系统提示词用于约束智能体行为files[./examples/resource/doc.pdf]初始化时注入给智能体的文件 URL 列表从源码角度补充两点其一llm_cfg中model_type含dashscope时框架会自动在generate_cfg中开启incremental_output增量流式输出其二当模型为 QwQ/QVQ/Qwen3 系列且使用 DashScope 时FnCallAgent会为内存/检索组件单独分配一个qwen-turbo小模型以节省开销。仓库中 examples/assistant_qwen3.py、examples/function_calling.py、examples/assistant_weather_bot.py 等示例提供了更多组合玩法可作为继续探索的起点。小结从 Overview 文档出发我们完整走通了 Qwen-Agent 的使用闭环安装最小依赖 vs 可选依赖组→ 准备模型服务DashScope 或自部署并选择 Tool Call 解析模式→ 用Assistant写第一个对话智能体CLI 流式 GUI→ 通过BaseTool注册自定义工具并让智能体读写 PDF → 用WebUI一键发布 Gradio 应用。无论是快速原型还是生产级应用这套原子组件 Agent GUI的框架都能显著降低基于 Qwen 的智能体开发门槛。【免费下载链接】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），仅供参考