企业官网建设流程全解析

Qwen-Agent 快速入门：从零构建一个能读 PDF、画图并执行代码的智能体

【免费下载链接】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 的官方快速入门指南。你将用十几行代码，在几分钟内搭建一个完整的 Agent：它既能读取 PDF 文档、通过内置工具执行 Python 代码，又能调用你自定义的"AI 绘画"工具完成"先画图、再下载、再处理图片"的多步任务。读完本文，你将掌握：模型服务的两种接入方式与工具调用解析器的选型、基于Assistant与自定义BaseTool的 Agent 开发全流程，以及一行代码启动 Gradio Web 界面的方法，并可进一步在 examples 目录中探索更多实战用例。

准备工作：选择并配置模型服务

在编写任何代码之前，你需要先准备好一个可用的 LLM 服务。Qwen-Agent 支持两条路线：

1. 使用阿里云 DashScope 提供的模型服务：需设置环境变量DASHSCOPE_API_KEY为你专属的 DashScope API Key。
2. 使用开源的 Qwen 模型自行部署模型服务：可参考 Qwen3 的 README 中部署 OpenAI 兼容 API 服务的方法，例如使用 SGLang 或 vLLM 进行高吞吐 GPU 部署，然后通过model_server指向本地服务地址。

两种方式在代码中的差异仅体现在llm_cfg配置上（下文示例会同时给出）。安装 Qwen-Agent 的方式可参考 安装指南。

工具调用解析器的两种选型

当模型在对话中需要调用工具时，存在"谁来解析模型输出的工具调用"的问题。Qwen-Agent 提供两种方案：

模型服务端原生工具调用解析器

• Qwen-Agent 支持直接读取模型服务返回的工具调用结果，但这要求在部署模型时开启模型服务的工具调用解析参数。
• 对于 Qwen3-Coder，官方建议使用模型服务自带的工具解析器，即在 vLLM / SGLang 服务端添加--enable-auto-tool-choice与--tool-call-parser qwen3_coder参数。
• 该方式需要与generate_cfg中的use_raw_api参数配合使用（详见 配置文档），未来将成为默认模式。

Qwen-Agent 内置工具调用解析器

• 由于部分模型部署方式不提供原生工具调用能力，或工具调用支持不完整，可以使用 Qwen-Agent 内置的工具调用解析。
• Qwen-Agent 默认提供hermes解析格式，支持 QwQ 与 Qwen3 系列模型的工具调用解析，这也是当前默认模式。
• 对 QwQ 与 Qwen3 系列模型，建议使用 Qwen-Agent 内置解析器，即不要在 vLLM / SGLang 服务端添加--enable-auto-tool-choice与--tool-call-parser hermes参数，避免服务端与客户端双重解析导致冲突。

下表总结了两种方案的适用场景：

开发你自己的 Agent

架构总览：从原子组件到高层 Agent

Qwen-Agent 提供了一系列原子组件：LLM（继承自BaseChatModel，自带函数调用能力）和工具（继承自BaseTool），以及高层组件：Agent（继承自class Agent）。从源码看，Agent基类定义在 agent.py，它将 LLM 与工具统一封装：Agent.__init__会通过get_chat_model解析llm配置，并通过_init_tool将function_list中的每一项注册进function_map（见 agent.py）；Agent.run()负责消息格式统一与系统提示词注入，然后交给子类实现的_run()方法产出流式响应（见 agent.py）。

Assistant是FnCallAgent的子类（见 assistant.py），在函数调用能力之上集成了 RAG（检索增强生成）：_run会先调用_prepend_knowledge_prompt从文件中检索知识，把命中的文档片段以"知识库"模板拼接到系统提示词中，再进入工具调用循环（见 assistant.py）。因此传入files参数的 PDF 会先经过文档解析与检索，模型可据此回答问题，同时仍具备工具调用能力。

下面的示例展示了如何创建一个能读取 PDF、使用内置工具并接入自定义工具的 Agent。

完整示例：可读 PDF 且能"画图-下载-处理"的 Agent

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` 告诉 Agent 这个工具的功能。 description = 'AI painting (image generation) service, input text description, and return the image URL drawn based on text information.' # `parameters` 告诉 Agent 该工具有哪些输入参数。 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': f'https://image.pollinations.ai/prompt/{prompt}'}, ensure_ascii=False) # 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: 创建 Agent。这里以 `Assistant` 为例，它具备使用工具和读取文件的能力。 system_instruction = '''After receiving the user's 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'] # 给 Agent 一个可以阅读的 PDF 文件。 bot = Assistant(llm=llm_cfg, system_message=system_instruction, function_list=tools, files=files) # Step 4: 以聊天机器人的方式运行 Agent。 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(messages=messages): # 流式输出。 response_plain_text = typewriter_print(response, response_plain_text) # 将 Agent 的响应追加到聊天历史。 messages.extend(response)

示例中使用的doc.pdf存在于仓库的 examples/resource/doc.pdf，可直接作为测试文档运行。

自定义工具是如何被注册与调用的

@register_tool装饰器会把工具类写入全局TOOL_REGISTRY字典（见 base.py）。Assistant初始化时，_init_tool对字符串形式的'my_image_gen'会从TOOL_REGISTRY中取出对应类并实例化（见 agent.py）。当模型输出工具调用后，FnCallAgent._run会通过_detect_tool识别函数调用，并用_call_tool执行工具、把结果作为function角色的消息追加回对话（见 fncall_agent.py）。BaseTool的call()是必须实现的抽象方法，description与parameters则会被框架收集成模型可读的工具 schema（见 base.py）。

另外，function_list除了字符串，还支持字典（为已注册工具传配置，或以mcpServers键动态挂载 MCP 服务器）和BaseTool实例三种形式，具体可参考 配置文档。

继承class Agent开发自己的 Agent

除了直接使用Assistant等内置实现，你也可以继承class Agent自定义 Agent。开发时只需实现_run(self, messages, lang='en', **kwargs)方法——它接收消息列表，返回消息列表的迭代器；过程中可以使用_call_llm(...)与_call_tool(...)调用 LLM 或工具，甚至嵌套其他 Agent（例如直接调用Assistant.run(...)复用其规划能力）。详细的开发模式（嵌套式开发与非嵌套式开发）可参考 Agent 介绍文档。

一行代码启动 Gradio Web 界面

框架还提供了便捷的 GUI 接口，支持快速部署 Agent 的 Gradio Demo。以上面的bot为例，只需两行代码即可启动 Web 界面：

from qwen_agent.gui import WebUI WebUI(bot).run() # bot 即上文定义的 Agent，此处省略其定义以节省篇幅

WebUI定义于 web_ui.py，支持传入单个 Agent、Agent 列表或MultiAgentHub，其run()方法基于 Gradio 5 构建聊天界面并支持share、server_name、server_port、concurrency_limit、enable_mention等参数（见 web_ui.py）。启动后你就可以在浏览器中与 Agent 直接对话。

运行前提与注意事项

• 安装：GUI 依赖需要在安装时包含gui选项（pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"），可参考 安装指南。
• API Key：若使用 DashScope，请先export DASHSCOPE_API_KEY=你的Key；若使用本地 OpenAI 兼容服务，则将llm_cfg切换为model_server指向本地地址（如http://localhost:8000/v1）。
• 工具调用解析：QwQ / Qwen3 系列模型请保持默认的内置解析器；Qwen3-Coder 若在服务端开启了原生解析，请同时在generate_cfg中设置use_raw_api=True。
• 运行目录：示例中的files路径相对于运行脚本的当前工作目录，请按实际情况调整。

进一步探索

本示例只是起点。更多基于Assistant的单 Agent 用例、多 Agent 协作（GroupChat）、RAG 文档问答、MCP 集成等实战代码，均可在 examples 目录中找到；相关组件的底层原理请参阅 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