Qwen-Agent 入门指南：快速构建智能体应用

什么是 Qwen-Agent？

Qwen-Agent 是阿里云通义千问团队开发的智能体开发框架，专门用于快速构建基于大语言模型的 AI 智能体（Agent）应用。它提供了开箱即用的组件和工具，让开发者能够轻松实现对话系统、工具调用、GUI 界面等功能。

核心特性

简单易用：极简的 API 设计，几行代码即可启动智能体
工具集成：内置工具注册机制，支持自定义工具扩展
多模态支持：支持文本、图像等多种输入输出
GUI 界面：内置 Gradio 集成，快速生成 Web 界面
流式输出：支持流式响应，提升用户体验
多轮对话：原生支持对话历史管理

为什么选择 Qwen-Agent？

1. 原生集成通义千问模型

Qwen-Agent 与 DashScope API 深度集成，无需复杂配置即可调用通义千问系列模型（qwen-turbo、qwen-plus、qwen-max 等）。

import dashscope
from qwen_agent.agents import Assistant

# 设置 API 密钥
dashscope.api_key = "your-api-key"

# 配置模型
llm_cfg = {
    'model': 'qwen-turbo',
    'timeout': 30,
    'retry_count': 3,
}

2. 极简的工具注册机制

使用 @register_tool 装饰器即可注册自定义工具，无需复杂的配置：

from qwen_agent.tools.base import BaseTool, register_tool

@register_tool('query_shanghai_index')
class QueryShanghaiIndexTool(BaseTool):
    description = '查询上证指数的最新行情数据'
    parameters = []  # 工具参数定义

    def call(self, params: str, **kwargs) -> str:
        # 实现工具逻辑
        return "上证指数 当前点位: 3125.62"

3. 内置 GUI 支持

一行代码即可启动 Web 界面，支持实时对话：

from qwen_agent.gui import WebUI

WebUI(agent).run()

4. 灵活的消息处理

支持流式输出，可以实时获取智能体的中间状态：

messages = [{'role': 'user', 'content': '你好'}]
for response in agent.run(messages):
    print(response)  # 每次迭代获取最新响应

如何使用 Qwen-Agent？

环境准备

1. 安装依赖

pip install qwen-agent dashscope python-dotenv

2. 配置 API 密钥

创建 .env 文件：

DASHSCOPE_API_KEY=your-api-key-here

或在代码中直接设置：

import os
import dashscope

dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

基础使用示例

示例 1：最简单的智能体

from qwen_agent.agents import Assistant

# 配置模型
llm_cfg = {'model': 'qwen-turbo'}

# 创建智能体
agent = Assistant(
    llm=llm_cfg,
    name='我的助手',
    system_message='你是一个友好的AI助手。'
)

# 运行对话
messages = [{'role': 'user', 'content': '你好，请介绍一下你自己'}]
for response in agent.run(messages):
    print(response)

示例 2：带工具的智能体

步骤 1：定义工具

from qwen_agent.tools.base import BaseTool, register_tool
import json

@register_tool('get_weather')
class WeatherTool(BaseTool):
    """天气查询工具"""
    description = '查询指定城市的天气情况'
    parameters = [{
        'name': 'city',
        'type': 'string',
        'description': '城市名称',
        'required': True
    }]

    def call(self, params: str, **kwargs) -> str:
        args = json.loads(params)
        city = args.get('city', '未知')
        return f"{city}今天天气晴朗，温度25°C"

步骤 2：创建智能体并使用工具

from qwen_agent.agents import Assistant

llm_cfg = {'model': 'qwen-turbo'}

agent = Assistant(
    llm=llm_cfg,
    name='天气助手',
    system_message='你是一个天气查询助手。',
    function_list=['get_weather']  # 注册工具
)

messages = [{'role': 'user', 'content': '北京今天天气怎么样？'}]
for response in agent.run(messages):
    print(response)

示例 3：完整的财富管理投顾应用

下面是一个实际应用场景的完整示例：

#!/usr/bin/env python
# -*- coding: utf-8 -*-

import os
import json
from dotenv import load_dotenv
import dashscope
from qwen_agent.agents import Assistant
from qwen_agent.gui import WebUI
from qwen_agent.tools.base import BaseTool, register_tool

# 加载环境变量
load_dotenv()
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

# 1. 定义工具
@register_tool('query_shanghai_index')
class QueryShanghaiIndexTool(BaseTool):
    description = '查询上证指数的最新行情数据'
    parameters = []

    def call(self, params: str, **kwargs) -> str:
        return "上证指数 当前点位: 3125.62，涨跌: 6.32，涨跌幅: 0.20%"

# 2. 定义系统提示词
SYSTEM_PROMPT = """你是一个专业的财富管理投顾AI助手。

你可以：
- 查询市场行情（使用 query_shanghai_index 工具）
- 提供投资建议
- 分析投资组合

请根据用户问题，提供专业的建议。"""

# 3. 初始化智能体
def init_agent():
    llm_cfg = {
        'model': 'qwen-turbo',
        'timeout': 30,
        'retry_count': 3,
    }
    
    agent = Assistant(
        llm=llm_cfg,
        name='财富管理投顾AI助手',
        system_message=SYSTEM_PROMPT,
        function_list=['query_shanghai_index'],
    )
    return agent

# 4. 启动 Web 界面
if __name__ == "__main__":
    agent = init_agent()
    
    # 配置建议问题
    chatbot_config = {
        'prompt.suggestions': [
            '今天上证指数的表现如何？',
            '我的投资组合中科技股占比是多少？',
            '根据当前市场情况，我应该如何调整投资组合？',
        ]
    }
    
    WebUI(agent, chatbot_config=chatbot_config).run()

核心组件解析

1. Assistant（助手）

Assistant 是最核心的智能体类，负责管理对话、工具调用和模型推理。

agent = Assistant(
    llm=llm_cfg,                    # 模型配置
    name='助手名称',                 # 智能体名称
    description='功能描述',          # 智能体描述
    system_message='系统提示词',     # 系统提示词
    function_list=['tool1', 'tool2'] # 工具列表
)

2. BaseTool（工具基类）

所有自定义工具都需要继承 BaseTool 并使用 @register_tool 装饰器：

@register_tool('工具名称')
class MyTool(BaseTool):
    description = '工具描述'  # 告诉 LLM 这个工具的作用
    parameters = [...]        # 参数定义（JSON Schema 格式）
    
    def call(self, params: str, **kwargs) -> str:
        # 实现工具逻辑
        # params 是 JSON 字符串
        args = json.loads(params)
        return "工具返回结果"

3. WebUI（图形界面）

快速生成基于 Gradio 的 Web 聊天界面：

WebUI(
    agent,                              # 智能体实例
    chatbot_config={                    # 可选配置
        'prompt.suggestions': [...]     # 建议问题列表
    }
).run()

消息格式

Qwen-Agent 使用标准的 OpenAI 消息格式：

messages = [
    {'role': 'user', 'content': '你好'},
    {'role': 'assistant', 'content': '你好！有什么可以帮助你的？'},
    {'role': 'user', 'content': '今天天气怎么样？'}
]

流式响应处理：

messages = [{'role': 'user', 'content': '你好'}]
response_messages = []

# agent.run() 返回一个生成器，每次迭代返回最新的完整消息列表
for response in agent.run(messages):
    response_messages = response  # 更新为最新响应

# 提取助手回复
for msg in response_messages:
    if msg.get('role') == 'assistant':
        print(msg.get('content'))

高级特性

1. 多轮对话

通过维护消息历史实现上下文对话：

messages = []

while True:
    query = input("用户: ")
    messages.append({'role': 'user', 'content': query})
    
    response = []
    for response in agent.run(messages):
        pass
    
    messages.extend(response)
    print("助手:", response[-1].get('content'))

2. 自定义系统提示词

通过 system_message 定制智能体行为：

system_prompt = """你是一个专业的投资顾问。

客户信息：
- 风险承受能力：平衡型
- 投资期限：中期
- 财务目标：退休规划、子女教育金

请根据客户情况提供个性化建议。"""

agent = Assistant(
    llm=llm_cfg,
    system_message=system_prompt,
    function_list=['query_shanghai_index']
)

3. 错误处理

添加异常处理提升稳定性：

try:
    for response in agent.run(messages):
        response_messages = response
except Exception as e:
    print(f"执行错误: {str(e)}")
    # 降级处理

总结

Qwen-Agent 的优势

特性	说明
开箱即用	几行代码即可启动智能体
工具生态	简单的工具注册机制
GUI 支持	内置 Gradio 集成
流式输出	实时响应用户
模型支持	深度集成通义千问系列

适用场景

对话式 AI 应用
智能客服系统
工具调用型智能体
多轮对话系统
快速原型开发

学习资源

官方文档：https://github.com/QwenLM/Qwen-Agent
DashScope API：https://dashscope.console.aliyun.com/

快速开始 Checklist

安装 qwen-agent 和相关依赖
获取 DashScope API Key
创建第一个 Assistant
定义自定义工具
启动 Web 界面
实现多轮对话
添加错误处理

现在就开始你的 Qwen-Agent 之旅吧！🚀

此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。原文来自 — 版权归原作者所有。

推荐订阅源

博客园 - work hard work smart