news 2026/9/14 6:40:47

Qwen-Agent 如何启动 Gradio WebUI 与 Agent 交互并配置 prompt.suggestions？

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
Qwen-Agent 如何启动 Gradio WebUI 与 Agent 交互并配置 prompt.suggestions？

Qwen-Agent 如何启动 Gradio WebUI 与 Agent 交互并配置 prompt.suggestions？

【免费下载链接】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（例如Assistant），现在想把它放进浏览器里做交互式对话，并在页面上预置几条"推荐对话"，让使用者点击即可发起提问。这个场景用 Qwen-Agent 自带的WebUI组件即可完成：一行WebUI(bot, chatbot_config=chatbot_config).run()启动基于 Gradio 的 Web 服务，chatbot_config里的prompt.suggestions控制页面右侧显示的推荐提示词。前提是你已准备好模型服务——使用阿里云 DashScope 时设置环境变量DASHSCOPE_API_KEY，或使用自部署的 OpenAI 兼容模型服务（vLLM、SGLang 等）。

准备环境

从 安装说明 看，WebUI 依赖[gui]可选依赖组（Gradio-based GUI support，文档说明基于 Gradio 5 构建）：

pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"

只需要 Gradio 界面的话，最小安装可用：

pip install -U "qwen-agent[gui]"

模型服务方面，按 QuickStart 的说明二选一：

  • 使用 DashScope 服务：设置环境变量DASHSCOPE_API_KEY为你的 API key；
  • 使用自部署的 Qwen 模型服务（OpenAI 兼容接口）：在 LLM 配置中填model_server地址。

定义 Agent

下面是最短主路径：一个不带工具的Assistant。llm_cfg使用 DashScope 的qwen3-max模型；name和description会显示在 WebUI 右侧的 Agent 信息区。

from qwen_agent.agents import Assistant from qwen_agent.gui import WebUI llm_cfg = { 'model': 'qwen3-max', 'model_type': 'qwen_dashscope', # 'api_key': 'YOUR_DASHSCOPE_API_KEY', # 未设置 'api_key' 时，会使用 DASHSCOPE_API_KEY 环境变量 } bot = Assistant(llm=llm_cfg, name='Qwen3 Tool-calling Demo', description="I'm a demo using the Qwen3 tool calling.")

如果 Agent 需要工具（内置工具、自定义工具或 MCP 服务），按 QuickStart 中的方式传入function_list即可，WebUI 启动方式不受影响。使用 OpenAI 兼容服务时，把llm_cfg换成文档给出的形式，例如'model': 'Qwen3-8B'、'model_server': 'http://localhost:8000/v1'、'api_key': 'EMPTY'。

启动 Gradio WebUI

WebUI接受一个 Agent（也接受 Agent 列表或MultiAgentHub），可选的chatbot_config用于定制页面。run()会启动并阻塞运行 Gradio 服务：

chatbot_config = { 'prompt.suggestions': [ 'draw a cute dog' ] } WebUI(bot, chatbot_config=chatbot_config).run()

run()的签名参数（来自 web_ui.py）及默认值：

  • messages：初始聊天历史，默认None；
  • share：默认False；
  • server_name/server_port：默认None，即 Gradio 默认监听；
  • concurrency_limit：默认10，对应 Gradio 队列的并发上限；
  • enable_mention：默认False，仅多 Agent 场景下配合@agent选择使用；
  • 其余**kwargs会原样透传给 Agent 的run()方法。

脚本运行后即可在 Web 界面中与 Agent 对话（QuickStart 文档的表述是 "Now you can chat with the Agent in the web UI"）。

配置 prompt.suggestions

在chatbot_config中，prompt.suggestions是一个列表。WebUI.__init__的文档注释（web_ui.py）给出的完整配置键为：

{'user.name': '', 'user.avatar': '', 'agent.avatar': '', 'input.placeholder': '', 'prompt.suggestions': []}

prompt.suggestions支持两种元素格式，examples/目录下的示例中均有实际使用：

纯字符串：每一项就是一条推荐提问，适合最直接的用法（guide/index.md 中的官方示例即此格式）：

chatbot_config = { 'prompt.suggestions': [ 'draw a cute dog' ] }

字典形式：可指定text，并可附带files（推荐项携带的文件路径），react_data_analysis.py 的用法：

chatbot_config = { 'prompt.suggestions': [{ 'text': 'pd.head the file first and then help me draw a line chart to show the changes in stock prices', 'files': [os.path.join(ROOT_RESOURCE, 'stock_prices.csv')] }, 'Draw a line graph y=x^2'] }

只带text不带files的字典写法也常见，见 assistant_rag.py：

chatbot_config = { 'prompt.suggestions': [ {'text': '介绍图一'}, {'text': '第二章第一句话是什么？'}, ] }

在 WebUI 的实现里，prompt.suggestions被渲染为标签"推荐对话"的gr.Examples区块，绑定到输入框组件（web_ui.py）；只有该列表非空时区块才会出现，所以不配置或传空列表时页面上看不到推荐对话。另外输入框占位文本由input.placeholder控制，未设置时默认显示"跟我聊聊吧～"。

验证效果

  1. 运行上述脚本，Gradio 服务启动后在浏览器打开对应页面；
  2. 页面右侧应出现 Agent 名称、描述与头像信息区，以及"推荐对话"区块，列出了你在prompt.suggestions中配置的条目；
  3. 点击某一条推荐项，提示词会填入输入框并触发对话，Agent 以流式方式返回回复；
  4. 如需调试，可在chatbot_config中加入'verbose': True，WebUI 会用 logger 打印每轮agent_run的输入与响应内容（见 web_ui.py）。

可选：多 Agent 与启动参数

  • WebUI也可以传入 Agent 列表（或MultiAgentHub），此时页面会多出一个 "Agents" 下拉选择器；启用enable_mention=True后，可在输入框用@agent_name指定对话对象（@后紧跟 Agent 名称）。
  • 需要固定端口或生成分享链接时，通过run(server_port=..., share=...)传参即可。
  • 更多完整可运行的写法可参考 examples 目录，其中几乎所有示例（如 assistant_qwen3.py、tir_math.py、gpt_mentions.py）都以WebUI(bot, chatbot_config=...)收尾。

【免费下载链接】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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/14 6:37:19

企业级Agent落地指南：从超级个体到超级团队的关键能力与实战

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/14 6:37:01

Meilisearch vs Elasticsearch选型指南：速度背后的代价与边界

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/14 6:36:55

ChatGPT 5.4性能评测与专业应用解析

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/14 6:36:12

主从博弈在综合能源系统优化调度中的Matlab实现

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/14 6:36:04

ESP32 Arduino 串口 RX 内部上拉详解：RxPull_Demo 实战指南

ESP32 Arduino 串口 RX 内部上拉详解：RxPull_Demo 实战指南 【免费下载链接】arduino-esp32 Arduino core for the ESP32 family of SoCs 项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32 本篇文章围绕 arduino-esp32 仓库中的 RxPull_Demo…

作者头像 李华
网站建设 2026/9/14 6:36:00

Klipper：从克隆到输入整形三步走，消掉你3D打印机的振纹

Klipper：从克隆到输入整形三步走，消掉你3D打印机的振纹 【免费下载链接】klipper Klipper is a 3d-printer firmware 项目地址: https://gitcode.com/GitHub_Trending/kl/klipper Klipper是一款把复杂运动计算从打印机主板搬到树莓派上的3D打印机…

作者头像 李华