基于Qwen的Agent开发实战：完整代码+环境配置+运行步骤

本文将从零开始实现一个基于阿里云通义千问（Qwen）的智能Agent，包含环境配置、核心代码实现、运行步骤及功能扩展，确保你能快速复现并二次开发。

一、环境准备

1. 硬件要求

• 本地运行（轻量Agent）：无强制GPU要求，CPU即可
• 本地部署Qwen模型（进阶）：建议GPU≥8G显存（如RTX 3060/4090），内存≥16G

2. 软件环境

• Python版本：3.8~3.11（推荐3.9，兼容性最佳）
• 核心依赖库：
  • dashscope：阿里云通义千问官方SDK
  • langchain：Agent开发框架（可选，简化流程）
  • python-dotenv：环境变量管理
  • pydantic：数据校验（可选）

3. 环境配置步骤

步骤1：创建虚拟环境（推荐）

# 创建虚拟环境
conda create -n qwen-agent python=3.9
# 激活环境
conda activate qwen-agent  # Windows/Linux通用（conda）
# 或用venv（无conda）
python -m venv qwen-agent
# Windows激活
qwen-agent\Scripts\activate
# Linux/Mac激活
source qwen-agent/bin/activate

步骤2：安装依赖

# 基础依赖（必装）
pip install dashscope python-dotenv
# 进阶依赖（LangChain框架）
pip install langchain langchain-community
# 可选：本地部署模型需装
pip install transformers torch accelerate sentencepiece

步骤3：获取阿里云API Key

Agent调用Qwen云端模型需要API Key，获取流程：

1. 访问阿里云百炼控制台
2. 登录后进入「API-KEY管理」，创建并复制API Key
3. 新建.env文件，写入：

DASHSCOPE_API_KEY=你的API_KEY_HERE

二、核心代码实现

方案1：基础版Agent（纯SDK调用，无框架）

适合新手，核心实现「意图识别+工具调用+回答生成」的基础Agent能力。

完整代码（qwen_agent_basic.py）

import os
from dotenv import load_dotenv
import dashscope
from dashscope import Generation

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

# 定义Agent工具（示例：计算器工具）
class CalculatorTool:
    """简单计算器工具，支持加减乘除"""
    def run(self, expression: str) -> str:
        try:
            # 安全执行表达式（仅示例，生产环境需限制操作）
            result = eval(expression, {"__builtins__": None}, {})
            return f"计算结果：{expression} = {result}"
        except Exception as e:
            return f"计算失败：{str(e)}"

# 定义Qwen Agent核心类
class QwenAgent:
    def __init__(self):
        self.tools = {
            "calculator": CalculatorTool()  # 注册工具
        }
        # 系统提示词：定义Agent行为逻辑
        self.system_prompt = """
        你是一个智能Agent，名为QwenAgent。
        你的能力：
        1. 能理解用户问题，判断是否需要调用工具；
        2. 如果需要调用工具，格式必须为：【工具名|参数】，例如【calculator|100+200*3】；
        3. 如果不需要调用工具，直接用自然语言回答用户问题。
        """

    def _call_qwen_model(self, prompt: str) -> str:
        """调用Qwen云端模型（通义千问2.0）"""
        response = Generation.call(
            model="qwen-turbo",  # 轻量版，也可换qwen-plus/qwen-max
            messages=[
                {"role": "system", "content": self.system_prompt},
                {"role": "user", "content": prompt}
            ],
            temperature=0.1,  # 越低越稳定
            result_format="text"
        )
        if response.status_code == 200:
            return response.output.text
        else:
            return f"模型调用失败：{response.code} - {response.message}"

    def _parse_tool_call(self, model_response: str) -> tuple:
        """解析模型返回的工具调用指令"""
        if "【" in model_response and "】" in model_response:
            tool_part = model_response.split("【")[1].split("】")[0]
            if "|" in tool_part:
                tool_name, tool_args = tool_part.split("|", 1)
                return tool_name.strip(), tool_args.strip()
        return None, None

    def run(self, user_input: str) -> str:
        """Agent主运行逻辑：提问→模型判断→工具调用/直接回答"""
        # 1. 调用Qwen模型获取响应
        model_resp = self._call_qwen_model(user_input)
        print(f"模型原始响应：{model_resp}")

        # 2. 解析是否需要调用工具
        tool_name, tool_args = self._parse_tool_call(model_resp)
        if tool_name and tool_name in self.tools:
            # 3. 调用对应工具
            tool_result = self.tools[tool_name].run(tool_args)
            return f"Agent执行结果：\n{tool_result}"
        else:
            # 无需调用工具，直接返回模型回答
            return f"Agent回答：\n{model_resp}"

# 主函数
if __name__ == "__main__":
    # 初始化Agent
    agent = QwenAgent()
    print("===== Qwen Agent 启动 =====")
    print("输入问题（输入'exit'退出）：")
    while True:
        user_input = input("> ")
        if user_input.lower() == "exit":
            print("Agent已退出")
            break
        if not user_input.strip():
            print("请输入有效问题！")
            continue
        # 运行Agent并输出结果
        result = agent.run(user_input)
        print(result)
        print("-" * 50)

方案2：进阶版Agent（基于LangChain框架）

适合复杂场景，利用LangChain简化工具注册、对话记忆、多轮交互等逻辑。

完整代码（qwen_agent_langchain.py）

import os
from dotenv import load_dotenv
from langchain.llms.base import LLM
from langchain.agents import initialize_agent, AgentType
from langchain.tools import Tool
from langchain.memory import ConversationBufferMemory
from typing import Any, List, Mapping, Optional
import dashscope
from dashscope import Generation

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

# 自定义LangChain LLM封装（适配Qwen）
class QwenLLM(LLM):
    """适配LangChain的Qwen LLM封装类"""
    model_name: str = "qwen-turbo"  # 模型名称
    temperature: float = 0.1       # 温度系数

    @property
    def _llm_type(self) -> str:
        return "qwen"

    def _call(
        self,
        prompt: str,
        stop: Optional[List[str]] = None,
        run_manager: Any = None,
        **kwargs: Any,
    ) -> str:
        """核心调用方法"""
        response = Generation.call(
            model=self.model_name,
            messages=[{"role": "user", "content": prompt}],
            temperature=self.temperature,
            result_format="text"
        )
        if response.status_code == 200:
            return response.output.text
        else:
            raise ValueError(f"Qwen模型调用失败：{response.code} - {response.message}")

    @property
    def _identifying_params(self) -> Mapping[str, Any]:
        return {"model_name": self.model_name, "temperature": self.temperature}

# 定义工具函数
def calculator_tool(expression: str) -> str:
    """计算器工具函数"""
    try:
        result = eval(expression, {"__builtins__": None}, {})
        return f"计算结果：{expression} = {result}"
    except Exception as e:
        return f"计算错误：{str(e)}"

def weather_tool(city: str) -> str:
    """模拟天气查询工具"""
    mock_weather = {
        "北京": "晴，25℃",
        "上海": "多云，23℃",
        "广州": "雷阵雨，28℃"
    }
    return mock_weather.get(city, f"暂未查询到{city}的天气")

# 主函数
if __name__ == "__main__":
    # 1. 初始化Qwen LLM
    qwen_llm = QwenLLM(model_name="qwen-turbo", temperature=0.1)

    # 2. 定义工具列表
    tools = [
        Tool(
            name="Calculator",
            func=calculator_tool,
            description="用于数学计算，输入需要计算的表达式（如100+200*3）"
        ),
        Tool(
            name="Weather",
            func=weather_tool,
            description="用于查询城市天气，输入城市名称（如北京）"
        )
    ]

    # 3. 初始化对话记忆（支持多轮交互）
    memory = ConversationBufferMemory(memory_key="chat_history")

    # 4. 初始化Agent
    agent = initialize_agent(
        tools=tools,
        llm=qwen_llm,
        agent=AgentType.CONVERSATIONAL_REACT_DESCRIPTION,
        memory=memory,
        verbose=True  # 打印详细执行过程
    )

    # 5. 启动交互
    print("===== LangChain-Qwen Agent 启动 =====")
    print("输入问题（输入'exit'退出）：")
    while True:
        user_input = input("> ")
        if user_input.lower() == "exit":
            print("Agent已退出")
            break
        if not user_input.strip():
            print("请输入有效问题！")
            continue
        # 运行Agent
        try:
            result = agent.run(user_input)
            print(f"\nAgent最终回答：{result}")
        except Exception as e:
            print(f"执行出错：{str(e)}")
        print("-" * 80)

三、运行步骤

1. 基础版Agent运行

步骤1：确认环境配置

• 已激活qwen-agent虚拟环境
• .env文件中正确填写DASHSCOPE_API_KEY

步骤2：运行代码

python qwen_agent_basic.py

步骤3：测试交互

===== Qwen Agent 启动 =====
输入问题（输入'exit'退出）：
> 帮我计算100+200*5-80
模型原始响应：【calculator|100+200*5-80】
Agent执行结果：
计算结果：100+200*5-80 = 1020
--------------------------------------------------
> 介绍一下通义千问
模型原始响应：通义千问（Qwen）是阿里云研发的大语言模型，具备强大的自然语言理解、生成、逻辑推理等能力，可应用于智能问答、内容创作、代码生成等多个场景。
Agent回答：
通义千问（Qwen）是阿里云研发的大语言模型，具备强大的自然语言理解、生成、逻辑推理等能力，可应用于智能问答、内容创作、代码生成等多个场景。
--------------------------------------------------
> exit
Agent已退出

2. 进阶版Agent运行

步骤1：同上，确认环境和API Key

步骤2：运行代码

python qwen_agent_langchain.py

步骤3：测试交互

===== LangChain-Qwen Agent 启动 =====
输入问题（输入'exit'退出）：
> 北京今天天气怎么样？
> Entering new AgentExecutor chain...
> 我需要调用Weather工具来查询北京的天气。
> 调用工具：Weather，参数：北京
> 工具返回：晴，25℃
> 我现在可以回答用户的问题了。

> Finished chain.

Agent最终回答：北京今天的天气是晴，25℃
--------------------------------------------------------------------------------
> 帮我算一下(100-20)*3/4
> Entering new AgentExecutor chain...
> 我需要调用Calculator工具来计算这个表达式。
> 调用工具：Calculator，参数：(100-20)*3/4
> 工具返回：计算结果：(100-20)*3/4 = 60.0
> 我现在可以回答用户的问题了。

> Finished chain.

Agent最终回答：(100-20)*3/4的计算结果是60.0
--------------------------------------------------------------------------------
> exit
Agent已退出

四、常见问题解决

1. API Key错误

• 报错：InvalidApiKey/Unauthorized
• 解决：检查.env文件中API Key是否正确，确认阿里云账号有百炼服务权限。

2. 依赖安装失败

• 报错：pip install dashscope失败

• 解决：升级pip：pip install --upgrade pip，或换源安装：

  pip install dashscope -i https://mirrors.aliyun.com/pypi/simple/
  

3. 模型调用超时

• 报错：Timeout/ConnectionError
• 解决：检查网络，或增加超时参数（在Generation.call中添加timeout=30）。

4. 本地部署Qwen模型（可选）

若不想调用云端API，可本地部署Qwen开源模型（如Qwen-7B-Chat），核心修改：

from transformers import AutoModelForCausalLM, AutoTokenizer

# 加载本地模型
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen-7B-Chat", trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen-7B-Chat",
    device_map="auto",
    trust_remote_code=True
).eval()

# 调用本地模型
def _call_local_qwen(self, prompt):
    response, history = model.chat(tokenizer, prompt, history=None)
    return response

五、功能扩展建议

1. 增加更多工具：如文本翻译、文件读写、API调用（如查股票、查快递）；
2. 优化工具解析：使用JSON格式解析工具调用，替代简单字符串分割；
3. 多轮对话记忆：基础版可添加ConversationBufferMemory类保存对话历史；
4. 错误重试机制：模型调用失败时自动重试；
5. 权限控制：限制计算器工具的执行范围，避免安全风险。

通过以上代码和步骤，你可以快速搭建一个可运行的Qwen Agent，并根据业务需求扩展功能。核心逻辑是「用户输入→模型判断意图→工具调用/直接回答」，这也是大语言模型Agent的通用范式。