Qwen-Agent 实战教程快速构建支持函数调用、RAG 与代码执行的 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-AgentQwen-Agent 是通义千问团队开源的 Agent 框架它把 Qwen 模型≥3.0在指令遵循、函数调用Function Calling、规划和记忆上的能力封装成可复用的组件并且就是 Qwen Chat 产品背后的底层框架。如果你的目标是做一个会用工具的聊天助手、能读文档的问答系统或一套自动化工作流它帮你省掉了手写工具调用循环、消息拼装和上下文裁剪这些繁琐代码——大约 10 行代码就能跑起第一个 Agent。本文带你从安装、接入模型服务开始逐步完成自定义工具、文档问答、沙箱代码执行、MCP 集成和 Web 界面封装。上手前Qwen-Agent 的能力地图在写第一行代码之前先花两分钟搞清楚它给你提供了什么。三层组件LLM、工具、Agent框架按抽象层级分成三类组件各管各的事LLM 层继承自BaseChatModel源码见 qwen_agent/llm/统一封装不同模型服务的调用并内置函数调用能力包括并行工具调用工具层继承自BaseTool源码见 qwen_agent/tools/代码解释器、文档解析、网页搜索、图像搜索等内置工具都可以一行名字启用也可以自己扩展Agent 层继承自Agent源码见 qwen_agent/agents/Assistant、文档问答、写作、群组对话等现成智能体你只需声明用哪个模型、给哪些工具、读哪些文件。上下文管理由框架代劳Agent 运行时最琐碎的部分是把系统指令、历史对话、工具调用结果按正确格式拼成消息流超长时还要裁剪。Qwen-Agent 把这些收进了框架内部每一轮消息按系统指令、历史轮次、当前用户输入、工具调用与响应等段落分组管理超长自动截断。也就是说你不需要关心底层消息怎么组织专注设计 Agent 的行为就行。环境准备安装与模型服务接入一条命令装好依赖Qwen-Agent 在 PyPI 上发布最小安装只要一行pip install -U qwen-agent想要完整体验建议一次性把可选功能装齐。方括号里是四个可选依赖组按需组合pip install -U qwen-agent[gui,rag,code_interpreter,mcp] # [gui]Gradio 网页界面 # [rag]文档问答 / RAG # [code_interpreter]Docker 沙箱代码执行 # [mcp]MCP 工具接入如果要用最新开发版也可以从源码安装git clone https://gitcode.com/GitHub_Trending/qw/Qwen-Agent cd Qwen-Agent pip install -e ./[gui,rag,code_interpreter,mcp]两种模型接入方式云 API 或本地服务框架不绑定任何一家模型服务。你要么用 DashScope 的云端 API要么用 vLLM、Ollama 之类部署的本地 OpenAI 兼容服务配置都收敛在一个llm_cfg字典里# 方式 ADashScope 云端服务需设置环境变量 DASHSCOPE_API_KEY llm_cfg { model: qwen-max-latest, model_type: qwen_dashscope, } # 方式 B本地 OpenAI 兼容服务vLLM / Ollama / LM Studio 均可 llm_cfg { model: Qwen3-8B, model_server: http://localhost:8000/v1, api_key: EMPTY, }两种方式对上层代码完全透明——后面的 Agent 代码一行都不用改。本地服务怎么部署参考 Qwen 官方的 vLLM / Ollama 章节即可这里不展开。跑通第一个 Agent10 行代码下面这段代码创建了一个启用代码解释器工具的Assistant让它画一张饼图。保存为my_bot.py直接运行from qwen_agent.agents import Assistant bot Assistant(llmllm_cfg, function_list[code_interpreter]) messages [{role: user, content: 绘制 2021 年各大洲人口占比饼图}] for response in bot.run(messages): print(response)几个细节值得注意function_list里填工具名字符串即可code_interpreter是内置工具无需实例化bot.run是流式生成器循环逐段打印就是打字机效果Assistant是全能型智能体自带文件读取能力通过files参数塞入 PDF 等文档也能挂载任意工具绝大多数场景用它就够了。加一个自定义工具一个装饰器的事想让 Agent 调用你的业务接口只需继承BaseTool并用register_tool注册声明好描述和参数实现call方法from qwen_agent.tools.base import BaseTool, register_tool register_tool(my_image_gen) class MyImageGen(BaseTool): description AI 绘画服务输入文本描述返回图像 URL parameters [{name: prompt, type: string, description: 期望图像的详细内容, required: True}] def call(self, params: str, **kwargs) - str: # params 是模型生成的 JSON 参数解析后调用你的服务并返回 JSON 字符串 ...description和parameters是写给模型看的说明书——描述写得越具体模型越知道什么时候该用这个工具、参数怎么填。之后把它和内置工具一起挂上即可Assistant(llmllm_cfg, function_list[my_image_gen, code_interpreter])。能力扩展四个常用玩法让它读文档、读网页RAG 与文档问答给消息内容里混入file项Agent 就会先解析文件再回答支持 PDF、Word、PPT、TXT、HTML 和本地路径或 URLmessages [{role: user, content: [ {text: 这篇论文的核心结论是什么}, {file: ./examples/resource/doc.pdf}, ]}]对于单篇文档这样直接用就够了。要处理超长文档官方方案在 1M token 上下文下做过压测仓库提供了两套现成方案轻量的 examples/assistant_rag.py 和检索质量更高的 examples/parallel_doc_qa.py改几行配置即可运行。让它写代码并安全执行Code InterpreterAgent 需要算数据、画图时代码解释器让它自己写 Python、在隔离环境里跑、把结果拿回来继续推理。启用它只需两步机器上装好 Docker 并启动首次使用会拉取并构建沙箱镜像耗时取决于网速依赖里带上code_interpreter组然后function_list中写code_interpreter。注意沙箱的边界它基于本地 Docker 容器只挂载指定工作目录属于基础隔离。日常开发足够生产环境仍建议按官方 README 的提示谨慎使用。用 MCP 接入外部系统Qwen-Agent 原生支持 MCPModel Context Protocol。不需要写任何适配代码在function_list里传一段mcpServers配置Agent 就能把 MCP 服务器暴露的工具当成自己的工具调用。比如接一个 SQLite 数据库助手tools [{ mcpServers: { sqlite: { command: uvx, args: [mcp-server-sqlite, --db-path, test.db] } } }] bot Assistant(llmllm_cfg, function_listtools)文件系统、内存、各类数据库的 MCP 服务器都可以按同样格式添加完整示例见 examples/assistant_mcp_sqlite_bot.py。前置依赖是 Node.js 和 uv官方 FAQ 里有各系统的安装命令。一行代码套上 Web 界面调试阶段用终端交互交付时通常需要网页。装上gui依赖组后Python 需 3.10任意 Agent 都能变成 Gradio 应用from qwen_agent.gui import WebUI WebUI(bot).run()浏览器打开就能看到带输入框、流式输出和快捷提问的聊天界面不用写任何前端代码。上线前的三个关键细节工具调用解析你的模型服务该怎么起这是新手最常踩的坑。框架解析工具调用有两种模式取决于你用的模型QwQ / Qwen3 系列启动 vLLM 时不要加--enable-auto-tool-choice和--tool-call-parser hermes让 Qwen-Agent 用自己的内置解析器处理工具输出Qwen3-Coder反过来建议开启上述参数使用 vLLM 内置解析并在generate_cfg里设use_raw_api: True走模型 API 的原生工具调用接口。选错模式的表现通常是模型明明输出了工具调用Agent 却看不见。常用生成参数怎么调llm_cfg里的generate_cfg会把参数透传给模型 API几个高频项generate_cfg: { top_p: 0.8, # 采样参数直接传给模型 API max_input_tokens: 58000, # 输入上限超出自动截断按你的模型 API 调整 use_raw_api: True, # 走 API 原生工具调用接口Qwen3-Coder 场景 }安全与合规提醒代码解释器执行的是模型生成的代码生产环境要控制沙箱挂载目录、限制出网权限用云端 API 时敏感文档建议改走本地模型服务数据不出内网。接下来往哪走找现成范例examples/ 目录按场景命名从纯函数调用function_calling.py到多智能体协作group_chat_demo.py、视觉模型assistant_qwen3vl.py都有可直接跑的脚本深入核心源码Agent 实现看 qwen_agent/agents/内置工具看 qwen_agent/tools/模型适配层看 qwen_agent/llm/想写自己的 Agent 就从继承Agent开始浏览器助手仓库里的 browser_qwen/ 是一个构建在 Qwen-Agent 之上的 Chrome 扩展让模型直接读懂并操作你打开的网页可以当作框架能力上限的参考实现离线评测官方开源了 DeepPlanning 基准见 benchmark/用来量化衡量你的 Agent 在多步规划任务上的表现系统文档qwen-agent-docs/ 下有完整的英文文档站源码安装、配置、核心模块都有专门章节。从pip install到WebUI(bot).run()Qwen-Agent 把 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），仅供参考 Qwen-Agent 实战教程：快速构建支持函数调用、RAG 与代码执行的 Agent 应用
Qwen-Agent 实战教程快速构建支持函数调用、RAG 与代码执行的 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-AgentQwen-Agent 是通义千问团队开源的 Agent 框架它把 Qwen 模型≥3.0在指令遵循、函数调用Function Calling、规划和记忆上的能力封装成可复用的组件并且就是 Qwen Chat 产品背后的底层框架。如果你的目标是做一个会用工具的聊天助手、能读文档的问答系统或一套自动化工作流它帮你省掉了手写工具调用循环、消息拼装和上下文裁剪这些繁琐代码——大约 10 行代码就能跑起第一个 Agent。本文带你从安装、接入模型服务开始逐步完成自定义工具、文档问答、沙箱代码执行、MCP 集成和 Web 界面封装。上手前Qwen-Agent 的能力地图在写第一行代码之前先花两分钟搞清楚它给你提供了什么。三层组件LLM、工具、Agent框架按抽象层级分成三类组件各管各的事LLM 层继承自BaseChatModel源码见 qwen_agent/llm/统一封装不同模型服务的调用并内置函数调用能力包括并行工具调用工具层继承自BaseTool源码见 qwen_agent/tools/代码解释器、文档解析、网页搜索、图像搜索等内置工具都可以一行名字启用也可以自己扩展Agent 层继承自Agent源码见 qwen_agent/agents/Assistant、文档问答、写作、群组对话等现成智能体你只需声明用哪个模型、给哪些工具、读哪些文件。上下文管理由框架代劳Agent 运行时最琐碎的部分是把系统指令、历史对话、工具调用结果按正确格式拼成消息流超长时还要裁剪。Qwen-Agent 把这些收进了框架内部每一轮消息按系统指令、历史轮次、当前用户输入、工具调用与响应等段落分组管理超长自动截断。也就是说你不需要关心底层消息怎么组织专注设计 Agent 的行为就行。环境准备安装与模型服务接入一条命令装好依赖Qwen-Agent 在 PyPI 上发布最小安装只要一行pip install -U qwen-agent想要完整体验建议一次性把可选功能装齐。方括号里是四个可选依赖组按需组合pip install -U qwen-agent[gui,rag,code_interpreter,mcp] # [gui]Gradio 网页界面 # [rag]文档问答 / RAG # [code_interpreter]Docker 沙箱代码执行 # [mcp]MCP 工具接入如果要用最新开发版也可以从源码安装git clone https://gitcode.com/GitHub_Trending/qw/Qwen-Agent cd Qwen-Agent pip install -e ./[gui,rag,code_interpreter,mcp]两种模型接入方式云 API 或本地服务框架不绑定任何一家模型服务。你要么用 DashScope 的云端 API要么用 vLLM、Ollama 之类部署的本地 OpenAI 兼容服务配置都收敛在一个llm_cfg字典里# 方式 ADashScope 云端服务需设置环境变量 DASHSCOPE_API_KEY llm_cfg { model: qwen-max-latest, model_type: qwen_dashscope, } # 方式 B本地 OpenAI 兼容服务vLLM / Ollama / LM Studio 均可 llm_cfg { model: Qwen3-8B, model_server: http://localhost:8000/v1, api_key: EMPTY, }两种方式对上层代码完全透明——后面的 Agent 代码一行都不用改。本地服务怎么部署参考 Qwen 官方的 vLLM / Ollama 章节即可这里不展开。跑通第一个 Agent10 行代码下面这段代码创建了一个启用代码解释器工具的Assistant让它画一张饼图。保存为my_bot.py直接运行from qwen_agent.agents import Assistant bot Assistant(llmllm_cfg, function_list[code_interpreter]) messages [{role: user, content: 绘制 2021 年各大洲人口占比饼图}] for response in bot.run(messages): print(response)几个细节值得注意function_list里填工具名字符串即可code_interpreter是内置工具无需实例化bot.run是流式生成器循环逐段打印就是打字机效果Assistant是全能型智能体自带文件读取能力通过files参数塞入 PDF 等文档也能挂载任意工具绝大多数场景用它就够了。加一个自定义工具一个装饰器的事想让 Agent 调用你的业务接口只需继承BaseTool并用register_tool注册声明好描述和参数实现call方法from qwen_agent.tools.base import BaseTool, register_tool register_tool(my_image_gen) class MyImageGen(BaseTool): description AI 绘画服务输入文本描述返回图像 URL parameters [{name: prompt, type: string, description: 期望图像的详细内容, required: True}] def call(self, params: str, **kwargs) - str: # params 是模型生成的 JSON 参数解析后调用你的服务并返回 JSON 字符串 ...description和parameters是写给模型看的说明书——描述写得越具体模型越知道什么时候该用这个工具、参数怎么填。之后把它和内置工具一起挂上即可Assistant(llmllm_cfg, function_list[my_image_gen, code_interpreter])。能力扩展四个常用玩法让它读文档、读网页RAG 与文档问答给消息内容里混入file项Agent 就会先解析文件再回答支持 PDF、Word、PPT、TXT、HTML 和本地路径或 URLmessages [{role: user, content: [ {text: 这篇论文的核心结论是什么}, {file: ./examples/resource/doc.pdf}, ]}]对于单篇文档这样直接用就够了。要处理超长文档官方方案在 1M token 上下文下做过压测仓库提供了两套现成方案轻量的 examples/assistant_rag.py 和检索质量更高的 examples/parallel_doc_qa.py改几行配置即可运行。让它写代码并安全执行Code InterpreterAgent 需要算数据、画图时代码解释器让它自己写 Python、在隔离环境里跑、把结果拿回来继续推理。启用它只需两步机器上装好 Docker 并启动首次使用会拉取并构建沙箱镜像耗时取决于网速依赖里带上code_interpreter组然后function_list中写code_interpreter。注意沙箱的边界它基于本地 Docker 容器只挂载指定工作目录属于基础隔离。日常开发足够生产环境仍建议按官方 README 的提示谨慎使用。用 MCP 接入外部系统Qwen-Agent 原生支持 MCPModel Context Protocol。不需要写任何适配代码在function_list里传一段mcpServers配置Agent 就能把 MCP 服务器暴露的工具当成自己的工具调用。比如接一个 SQLite 数据库助手tools [{ mcpServers: { sqlite: { command: uvx, args: [mcp-server-sqlite, --db-path, test.db] } } }] bot Assistant(llmllm_cfg, function_listtools)文件系统、内存、各类数据库的 MCP 服务器都可以按同样格式添加完整示例见 examples/assistant_mcp_sqlite_bot.py。前置依赖是 Node.js 和 uv官方 FAQ 里有各系统的安装命令。一行代码套上 Web 界面调试阶段用终端交互交付时通常需要网页。装上gui依赖组后Python 需 3.10任意 Agent 都能变成 Gradio 应用from qwen_agent.gui import WebUI WebUI(bot).run()浏览器打开就能看到带输入框、流式输出和快捷提问的聊天界面不用写任何前端代码。上线前的三个关键细节工具调用解析你的模型服务该怎么起这是新手最常踩的坑。框架解析工具调用有两种模式取决于你用的模型QwQ / Qwen3 系列启动 vLLM 时不要加--enable-auto-tool-choice和--tool-call-parser hermes让 Qwen-Agent 用自己的内置解析器处理工具输出Qwen3-Coder反过来建议开启上述参数使用 vLLM 内置解析并在generate_cfg里设use_raw_api: True走模型 API 的原生工具调用接口。选错模式的表现通常是模型明明输出了工具调用Agent 却看不见。常用生成参数怎么调llm_cfg里的generate_cfg会把参数透传给模型 API几个高频项generate_cfg: { top_p: 0.8, # 采样参数直接传给模型 API max_input_tokens: 58000, # 输入上限超出自动截断按你的模型 API 调整 use_raw_api: True, # 走 API 原生工具调用接口Qwen3-Coder 场景 }安全与合规提醒代码解释器执行的是模型生成的代码生产环境要控制沙箱挂载目录、限制出网权限用云端 API 时敏感文档建议改走本地模型服务数据不出内网。接下来往哪走找现成范例examples/ 目录按场景命名从纯函数调用function_calling.py到多智能体协作group_chat_demo.py、视觉模型assistant_qwen3vl.py都有可直接跑的脚本深入核心源码Agent 实现看 qwen_agent/agents/内置工具看 qwen_agent/tools/模型适配层看 qwen_agent/llm/想写自己的 Agent 就从继承Agent开始浏览器助手仓库里的 browser_qwen/ 是一个构建在 Qwen-Agent 之上的 Chrome 扩展让模型直接读懂并操作你打开的网页可以当作框架能力上限的参考实现离线评测官方开源了 DeepPlanning 基准见 benchmark/用来量化衡量你的 Agent 在多步规划任务上的表现系统文档qwen-agent-docs/ 下有完整的英文文档站源码安装、配置、核心模块都有专门章节。从pip install到WebUI(bot).run()Qwen-Agent 把 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），仅供参考