千问智能体SDK实测：本地部署+自定义工具接入指南

问题
输入“现在几点？”，AI返回真实时间；输入“查北京天气”，它调API、解析、再回答——不是幻觉，是千问 Agent 的实际能力。但官方只提供了 SDK，没给可直接跑通的步骤。很多人卡在安装失败、工具不触发、返回空结果上。

方案
用开源 qwen-agent（v0.4.0+），5 分钟在本地启动一个能调度函数、能联网、能执行动作的 AI 助手。不依赖阿里云账号，纯本地运行。LLM 可选 Ollama 上的 Qwen2-1.5B（CPU 可跑），也可走 Qwen API。工具支持两种方式：Python 函数或 HTTP 接口。

步骤

1. 安装 SDK 与基础依赖（Windows/Linux/macOS 通用）

   pip install qwen-agent
   # 验证安装
   qwen-agent --version  # 应输出 0.4.0 或更高

   qwen-agent 是轻量级 Agent 框架，核心就三块：Plan（任务拆解）、Act（工具调用）、Memory（上下文管理）。pip install 安装的是 PyPI 预编译包，跳过源码构建，基本不会报错。

2. 启动本地 LLM 服务（无需 GPU）

   # 方式一：Ollama 运行 Qwen2-1.5B（推荐新手）
   ollama run qwen2:1.5b  # 启动后保持终端开启
   # 方式二：Qwen API（需申请 Key）
   export QWEN_API_KEY="sk-xxx"

   Qwen2-1.5B 在 CPU 上约 3 token/s，足够跑通完整流程；API 模式响应更稳，适合验证逻辑。Agent 本身不负责推理，只做任务规划和工具分发。

3. 写一个自定义工具：获取当前北京时间
   新建文件 tools/time_tool.py：

   from qwen_agent.tools import register_tool
   
   
   
   
   👉 <a href="https://idsoo.com/go/binance.html" rel="nofollow noopener" target="_blank">Binance</a> · <a href="https://idsoo.com/go/okx.html" rel="nofollow noopener" target="_blank">OKX</a> · <a href="https://idsoo.com/go/gate.html" rel="nofollow noopener" target="_blank">Gate.io</a> · <a href="https://idsoo.com/go/htx.html" rel="nofollow noopener" target="_blank">HTX</a> · <a href="https://idsoo.com/go/bitget.html" rel="nofollow noopener" target="_blank">Bitget</a>
   
   @register_tool('get_time')
   def get_time() -> str:
    """返回当前北京时间字符串"""
    from datetime import datetime
    import pytz
    return datetime.now(pytz.timezone('Asia/Shanghai')).strftime('%Y-%m-%d %H:%M:%S')

   @register_tool 是 SDK 的注册协议。Agent 理解用户意图后，会根据语义 + 函数签名匹配到 get_time 并执行，不是靠关键词硬匹配。

4. 启动 Agent 服务并加载工具

   qwen-agent serve \
     --host 127.0.0.1 \
     --port 8080 \
     --tools ./tools/time_tool.py

   --tools 参数指定 Python 文件路径，Agent 启动时会自动扫描并注册其中所有 @register_tool 装饰的函数。此时它已具备执行能力，不只是聊天。

5. CLI 调用：让 AI 真正行动
   新开终端，发送请求：

   curl -X POST http://127.0.0.1:8080/chat \
     -H "Content-Type: application/json" \
     -d '{"query":"现在几点？"}'

   返回示例：
   {"response":"当前时间是2024-06-12 14:28:05","tool_calls":[{"name":"get_time","args":{}}]}
tool_calls 字段出现，说明 Agent 确实调用了你的函数，不是模型幻觉。

验证

• ✅ 输入“告诉我现在的时间”，返回动态生成的真实时间
• ✅ 在 time_tool.py 的函数里加 print("已执行！")，重启服务后 CLI 调用能看到终端输出
• ✅ 替换为官网的 weather_tool.py，输入“查北京天气”，返回实时气象数据

常见问题

• ❌ 报错 ModuleNotFoundError: No module named 'qwen_agent.tools'
  → SDK 版本低于 0.4.0。运行 pip install --upgrade qwen-agent
• ❌ CLI 返回空，或 tool_calls 为空
  → 检查 --tools 路径是否指向 .py 文件（不能是目录）；确认函数用了 @register_tool 装饰器
• ❌ 时间总是旧的或时区错误
  → datetime.now() 默认本地时区。必须显式指定 pytz.timezone('Asia/Shanghai')

下一步建议
你现在有一个能真正执行动作的 AI。接下来可以：
① 把 time_tool.py 改成邮件工具（用 smtplib 发日报）→ 《用Agent自动发日报：SMTP工具接入实战》
② 接入 Dify 工作流，把 Agent 封装成网页按钮 → 《Dify + Qwen-Agent：三步上线智能客服》
③ 用 vLLM 部署 Qwen2-7B，推理速度提升 10 倍 → 《本地大模型提速指南：vLLM部署Qwen2》

所有命令已在 Ubuntu 22.04 / Windows 11 WSL2 / macOS Sonoma 实测通过。SDK 仓库：https://github.com/QwenLM/Qwen-Agent（Star 数超 2.1k，持续更新）