创建Python虚拟环境

使用conda或venv创建一个新的Python环境（建议Python 3.10+），避免包冲突。

Gradio 5+需要Python 3.10或更高版本。

安装Qwen-Agent

在虚拟环境中，通过PyPI安装稳定版：`pip install qwen-agent`。或者克隆GitHub仓库，安装开发版。

新手建议直接从PyPI安装稳定版。

获取模型访问权限

决定使用DashScope API（阿里云服务）或本地部署开源模型。如果选择DashScope，需要申请API Key并设置环境变量`DASHSCOPE_API_KEY`。

对于新手，使用DashScope API是最快开始的方式，无需本地GPU。记得设置环境变量：`export DASHSCOPE_API_KEY='your-key'`（Linux/Mac）或 `set DASHSCOPE_API_KEY=your-key`（Windows）。

浏览项目结构

克隆或下载项目后，快速浏览`examples/`目录，了解官方提供的几个Demo（如Browser Assistant, Code Interpreter），对项目能做什么有个直观印象。

运行最简单的示例

在`examples/`目录下找一个最简单的示例脚本（例如`basic_demo.py`或类似），尝试运行它，确保环境和API Key配置正确。

首次运行可能会下载一些模型或工具依赖，耐心等待。

理解核心组件：LLM与Tool

阅读README中“Developing Your Own Agent”部分的示例代码。重点关注：1. 如何初始化一个LLM对象（如`QwenChat`）。2. 如何定义一个简单的自定义工具（继承`BaseTool`）。3. 如何将工具列表传给Agent。

不必完全理解所有细节，先关注代码的整体流程：定义工具 -> 创建Agent -> 调用Agent.run()。

动手实践：创建一个问答智能体

模仿示例，编写一个简单的脚本。创建一个使用DashScope Qwen模型的Agent，并为其添加一个内置工具（如`code_interpreter`或`web_search`，如果可用），然后向它提一个问题，观察其调用工具和回复的过程。

为智能体添加Web界面

使用框架提供的Gradio集成功能。参考README中的GUI示例代码，为你上一步创建的智能体快速启动一个Gradio Web Demo。

通常只需要几行代码：`agent.run_gradio()`或类似方法。在浏览器中打开本地链接进行交互。

探索函数调用（工具调用）

仔细阅读FAQ中关于函数调用的部分。尝试创建一个需要多步工具调用的复杂任务（例如：“查询今天的天气，然后根据天气推荐一首歌”），观察Agent的规划和执行过程。

理解“Parallel Function Calls”意味着Agent可以同时调用多个工具。

了解代码解释器工具

阅读FAQ中“How to Use the Code Interpreter Tool?”部分。如果本地安装了Docker，尝试在Agent中启用`code_interpreter`工具，让它执行一些简单的Python计算或绘图任务。

⚠️ 注意：首次使用会下载Docker镜像，耗时取决于网络。生产环境需谨慎使用。

学习使用MCP（Model Context Protocol）

阅读README和FAQ中关于MCP的部分。按照指引，尝试配置一个简单的MCP服务器工具（如从公开MCP服务器列表中选择一个），并将其集成到你的Agent中。

MCP可以极大地扩展Agent能使用的工具范围，是框架的重要特性。

阅读官方文档和博客

访问项目首页提供的文档（Documentation）链接和博客（Blog）链接。重点关注“长文档问答”（1M tokens）解决方案和最新的技术动态（如Qwen3.5 Agent Demo）。

博客和文档包含了更深入的技术原理和最佳实践。

研究高级Agent类

不再只使用高级的`Assistant`类，尝试查看`FnCallAgent`或`ReActChat`等内置Agent的实现，理解它们如何继承自基础的`Agent`类，并尝试模仿创建自己的简单Agent子类。