1. Qwen-Agent 是什么开源 Agent 开发框架能做什么Qwen-Agent 是阿里通义团队开源的一套 Agent 开发框架核心定位是让开发者用尽量少的胶水代码把大模型的「指令遵循、工具调用、规划、记忆」这几件事串起来。你可以把它理解成一个中间层底层接任意兼容 OpenAI 协议的模型服务上层给你现成的 Agent 抽象、工具注册机制和 Gradio 界面。适合谁想快速验证 Agent 想法的人、需要给内部系统加一个能调工具的大脑的工程师、以及做 RAG 和代码解释器实验的同学。它和直接写 OpenAI SDK 的区别在于Qwen-Agent 把「多轮工具调用循环」这件事封装好了。你定义一个工具写清楚 description 和 parametersAgent 就会在对话里自己决定什么时候调用、传什么参数、拿到结果后怎么继续。框架自带code_interpreter、retrieval等工具也支持你注册自定义工具。文档处理上它通过 RAG 支持从 8K 到百万级 tokens 的长文档问答不是硬塞进上下文而是先检索再回答。我这次要演示的重点不是把 Qwen-Agent 讲成百科而是跑通一条最小链路本地装好框架把模型 endpoint 和鉴权切到 TaoToken 的统一 Key/API 通道然后让一个带自定义工具的 Assistant 真正跑起来并返回结果。这样你拿到的不只是概念而是一份能复制粘贴的配置。2. 环境准备与 TaoToken 统一 Key 前置配置先说环境。Qwen-Agent 对 Python 版本有要求GUI 部分需要 Python 3.10 及以上我建议直接用 3.10 或 3.11避免后面装 Gradio 5 时踩版本坑。用 conda 或 venv 都行我习惯 venvpython3.11 -m venv qwen-agent-env source qwen-agent-env/bin/activate pip install -U qwen-agent[rag,code_interpreter,python_executor,gui]如果你只想先跑最小依赖pip install -U qwen-agent也能装上但code_interpreter和 GUI 就用不了。装完可以用pip show qwen-agent确认版本。接下来是鉴权。Qwen-Agent 默认支持 DashScope 的model_server: dashscope也支持任何兼容 OpenAI 接口的服务只要给model_server一个 base_url。我们要做的就是把 base_url 指向 TaoToken 的 API 通道Key 用 TaoToken 控制台生成的统一 Key。先去控制台创建 Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentqwen_agent_consoleAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentqwen_agent_apikeys创建后把 Key 写进环境变量别硬编码进代码export TAOTOKEN_API_KEYsk-你的统一KeyTaoToken 的 API base_url 是https://taotoken.net/api注意这个地址后面不加 UTM 参数直接作为model_server的值。模型 ID 用你通道里可用的 Qwen 系列比如qwen-max或qwen-plus具体以控制台模型列表为准。这里三件套要记牢Base URL、Key、Model ID缺一个都连不上。提示环境变量方式比写死在代码里安全也方便你在 CI 或多环境之间切换。如果你用.env文件记得加进.gitignore。3. 可复制配置把 Qwen-Agent 的 endpoint 切到 TaoTokenQwen-Agent 的 LLM 配置就是一个字典关键字段是model、model_server、api_key。当model_server是一个 http 地址时框架会按 OpenAI 兼容协议发请求。下面这份配置可以直接复制把 Key 换成你自己的import os llm_cfg { # 模型 ID按 TaoToken 控制台可用列表填写 model: qwen-max, # 指向 TaoToken 的 OpenAI 兼容 API 通道 model_server: https://taotoken.net/api, # 统一 Key从环境变量读取 api_key: os.environ.get(TAOTOKEN_API_KEY), # 生成超参数 generate_cfg: { top_p: 0.8, temperature: 0.7 } }如果你更习惯用 TOML 管理配置可以单独放一个config.toml[llm] model qwen-max model_server https://taotoken.net/api api_key_env TAOTOKEN_API_KEY top_p 0.8 temperature 0.7然后在代码里读进来组装成上面的字典。注意model_server结尾不要多加/v1TaoToken 的通道地址就是https://taotoken.net/api框架内部会拼接具体路径。这一点和某些自建 vLLM 服务写http://localhost:8000/v1的习惯不同写错了会直接 404。再补一个自定义工具的完整片段方便你一次跑通。这个工具叫my_image_gen返回一个图片 URLimport json5 import urllib.parse from qwen_agent.tools.base import BaseTool, register_tool register_tool(my_image_gen) class MyImageGen(BaseTool): description AI 绘画服务输入文本描述返回图像 URL。 parameters [{ name: prompt, type: string, description: 期望的图像内容描述, required: True }] def call(self, params: str, **kwargs) - str: prompt json5.loads(params)[prompt] prompt urllib.parse.quote(prompt) return json5.dumps( {image_url: fhttps://image.pollinations.ai/prompt/{prompt}}, ensure_asciiFalse )工具注册好之后Agent 就能在对话里自主决定是否调用它。description写得越清楚模型判断越准这是很多人忽略的一点。4. 验证请求跑通一个最小可用 Agent 并看到成功结果配置齐了写一个最小可运行脚本。这里用Assistant这个高级抽象它自带工具调用和文件读取能力import pprint from qwen_agent.agents import Assistant llm_cfg { model: qwen-max, model_server: https://taotoken.net/api, api_key: os.environ.get(TAOTOKEN_API_KEY), generate_cfg: {top_p: 0.8} } system_instruction 你是一个乐于助人的AI助手。 收到用户请求后先绘制一幅图像得到 URL然后用中文回复用户。 tools [my_image_gen] bot Assistant( llmllm_cfg, system_messagesystem_instruction, function_listtools ) messages [] query input(用户请求: ) messages.append({role: user, content: query}) response [] for response in bot.run(messagesmessages): print(机器人回应:) pprint.pprint(response, indent2) messages.extend(response)运行后输入「画一只在草地上奔跑的柯基」你会看到流式输出里先出现一个function_call参数是{prompt: ...}接着工具返回image_url最后模型用中文总结。整个过程说明三件事都通了鉴权通过、模型响应正常、工具调用链路完整。如果你想用 GUI 快速看效果加两行from qwen_agent.gui import WebUI WebUI(bot).run()浏览器打开后就是一个聊天界面能直接看到工具调用过程。实测下来GUI 对调试 Agent 的工具选择逻辑特别直观比盯终端输出舒服。验证成功的标志很简单终端里出现带image_url的返回且没有抛异常。如果只看到模型文字回复但没触发工具多半是description写得太模糊或者 system_instruction 没引导它用工具。5. 本篇常见报错排查401、local proxy failed 与 choices 读取失败接入过程里最容易撞的几个错我按真实报错对照说。401 Unauthorized最常见。先确认TAOTOKEN_API_KEY环境变量在当前 shell 里真的存在echo $TAOTOKEN_API_KEY看一眼。如果 Key 是对的还 401检查是不是复制时带了空格或换行。还有一种情况是model_server写成了带/v1的地址路径不对导致鉴权头没被正确识别。local proxy failed / connection error这类报错通常是网络层没通或者 base_url 拼错。确认model_server就是https://taotoken.net/api不要自己加后缀。如果你在公司内网检查是否需要配置出网策略但不要使用任何非正规的网络工具走正常网络出口即可。reading choices 相关报错比如Cannot read properties of undefined (reading choices)这多半是返回体不是标准 OpenAI 格式或者请求根本没到模型服务。常见原因是model字段填了一个通道里不存在的模型 ID。去控制台核对模型列表把model改成实际可用的值。另一个原因是api_key传成了None框架发了个空鉴权请求返回体自然没有choices。OAuth / token 过期类报错如果你用的是某些需要 OAuth 的客户端配置注意 TaoToken 走的是 API Key 鉴权不是 OAuth 流程。把配置里的 OAuth 相关字段去掉只保留 Base URL、Key、Model ID 三件套。CC Switch、Cline MCP、Codex 的auth.json这类工具也是同样逻辑认准这三个字段就不会乱。工具没被调用不是报错但很常见。检查function_list里的工具名和register_tool注册的名字是否一致大小写敏感。再检查parameters的 JSON schema 是否合法字段类型写错会导致模型生成的参数解析失败。排障时建议先把generate_cfg里的temperature调低减少模型乱选工具的概率。定位到具体环节后再调回来。6. 从最小 Agent 到长期编码把 TaoToken 用顺的几条路径跑通最小 Agent 只是起点。接下来你大概率会往两个方向走一是把 Agent 接到更复杂的工具链上比如 RAG 检索、代码执行、多轮规划二是把模型通道固定下来让日常编码和 Agent 实验共用一套 Key省得来回切换。如果你主要做 Agent 实验和模型对比可以直接在模型对话里试不同 Qwen 版本的表现快速判断哪个模型更适合你的工具调用场景https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentqwen_agent_chat如果你要把 Agent 能力嵌进日常编码流程比如让 Claude Code 或类似工具走统一通道那 Coding Plan 更合适它按长期编码场景做了额度规划https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentqwen_agent_codingplan接入文档里有各客户端的完整配置示例遇到字段不确定时对着抄https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentqwen_agent_doc我自己的习惯是Agent 实验用qwen-max保证工具调用准确率批量跑数据时切到更便宜的模型Key 始终用同一个只改model字段。这样配置不用动切换成本几乎为零。Qwen-Agent 的llm_cfg是运行时字典你完全可以在代码里根据任务类型动态选模型这是它比写死配置灵活的地方。最后提醒一句code_interpreter和python_executor默认没有沙箱保护本地测试没问题别直接放到生产环境跑用户输入。要上生产自己加一层隔离。