1. 为什么我用 smolagents 跑通了第一个 AgentHuggingFace smolagents 是一个用 Python 写轻量级 Agent 的库核心逻辑大约 1000 行代码能让你用几行代码就跑起一个会自己写代码、自己调工具的智能体。它适合谁适合刚接触大模型、想搞明白 Agent 到底怎么运转的 Python 开发者也适合已经用过 LangChain 但被一堆抽象层绕晕、想找个更透明框架的人。我最初接触 Agent 框架时最大的困惑是模型输出一段 JSON框架解析成工具调用再拼回上下文中间隔了太多层出了问题根本不知道是哪一步断了。smolagents 的思路不一样它让模型直接生成 Python 代码片段作为动作工具调用就是函数调用执行结果直接回填。这意味着你读一遍日志就能看懂 Agent 在干什么调试成本低很多。它的几个关键特性值得先记住CodeAgent 把动作写成可执行代码而不是 JSON 指令官方对比数据显示步骤数减少约 30%模型无关支持 Transformers 本地模型、Ollama、LiteLLM 接入的 OpenAI/Anthropic 等也支持 OpenAI 兼容服务器工具无关可以用 LangChain 工具、MCP 工具甚至把 Hub Space 当工具用模态上支持文本、视觉、视频、音频输入。这篇文章我会带你从零跑通一个能实际完成任务的 Agent包括环境安装、模型接入配置、最小可运行代码、一次完整的运行验证以及我踩过的几个典型报错。全程用可复制的命令和配置你跟着做就能看到结果。2. 环境准备与 TaoToken 模型接入前置配置2.1 安装 smolagents 与依赖Python 版本建议 3.10 以上我实测 3.11 最稳。先建虚拟环境避免和系统包冲突python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install smolagents如果你要用 DuckDuckGo 搜索工具还需要额外装pip install duckduckgo-search安装完成后验证一下版本python -c import smolagents; print(smolagents.__version__)能打印出版本号就说明基础环境没问题。这里有个小坑smolagents 更新比较快不同版本 API 有细微差异建议锁定一个稳定版本比如pip install smolagents1.9.0避免跟着最新文档跑却报参数不存在的错。2.2 为什么需要 TaoToken 这类模型接入层smolagents 本身不绑定任何模型提供方它通过不同的 Model 类来对接。你可以用 HfApiModel 走 HuggingFace 推理网关也可以用 LiteLLMModel 走 LiteLLM 支持的 100 多个模型还可以用 OpenAIServerModel 对接任何 OpenAI 兼容的服务器。问题在于很多国内开发者在直连某些模型提供方时会遇到网络不稳定、鉴权方式不统一、多个模型要维护多套 Key 的情况。TaoToken 在这里扮演的是一个统一的模型接入层它提供 OpenAI 兼容的 API 接口你只需要一个 Base URL 和一个 API Key就能在 smolagents 里通过 OpenAIServerModel 接入多种模型不用为每个提供方单独写适配代码。它的官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数配置时直接用这个。2.3 获取 API Key 与模型 ID进入控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建后复制 Key形如sk-xxxx不要泄露到公开仓库。模型 ID 可以在模型对话页面查看地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。选一个适合 Agent 任务的模型建议用指令跟随能力强的比如 Qwen 系列或 DeepSeek 系列。记下模型 ID后面配置要用。如果你打算长期跑编码类 Agent可以了解 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 它针对高频编码场景做了额度优化。2.4 用环境变量管理密钥不要把 Key 硬编码在代码里。用环境变量export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api这样代码里用os.environ读取换环境不用改代码。3. 可复制的 smolagents 最小 Agent 配置3.1 用 OpenAIServerModel 接入 TaoTokensmolagents 的 OpenAIServerModel 专门用来对接 OpenAI 兼容服务器配置如下。新建文件first_agent.pyimport os from smolagents import CodeAgent, DuckDuckGoSearchTool, OpenAIServerModel model OpenAIServerModel( model_idQwen/Qwen2.5-Coder-32B-Instruct, # 替换为你在 TaoToken 看到的模型 ID api_baseos.environ[TAOTOKEN_BASE_URL], api_keyos.environ[TAOTOKEN_API_KEY], ) agent CodeAgent( tools[DuckDuckGoSearchTool()], modelmodel, max_steps6, ) result agent.run(计算一只猎豹以全速跑完巴黎艺术桥需要多少秒先搜索猎豹全速和艺术桥长度的数据。) print(result)这里三个关键参数必须对齐Base URL 填https://taotoken.net/apiAPI Key 填你创建的那串Model ID 填模型对话页面里显示的完整 ID。三者缺一不可少一个就会在请求时被拒。3.2 用 settings 片段固化配置如果你不想每次写代码都读环境变量可以建一个config.toml放在项目根目录[model] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model_id Qwen/Qwen2.5-Coder-32B-Instruct [agent] max_steps 6 verbosity 2然后在代码里读取import os import tomllib from smolagents import CodeAgent, DuckDuckGoSearchTool, OpenAIServerModel with open(config.toml, rb) as f: cfg tomllib.load(f) model OpenAIServerModel( model_idcfg[model][model_id], api_basecfg[model][base_url], api_keyos.environ[cfg[model][api_key_env]], ) agent CodeAgent( tools[DuckDuckGoSearchTool()], modelmodel, max_stepscfg[agent][max_steps], verbosity_levelcfg[agent][verbosity], )这样配置和代码分离换模型只改 toml 文件。3.3 如果你用 LiteLLMModelLiteLLM 方式适合需要切换多家提供方的场景import os from smolagents import CodeAgent, LiteLLMModel model LiteLLMModel( model_idopenai/Qwen/Qwen2.5-Coder-32B-Instruct, api_baseos.environ[TAOTOKEN_BASE_URL], api_keyos.environ[TAOTOKEN_API_KEY], temperature0.2, )注意 LiteLLM 的 model_id 前缀规则OpenAI 兼容接口一般加openai/前缀。如果报模型找不到先确认前缀和模型 ID 拼写。3.4 工具配置与沙箱选项CodeAgent 默认在本地 Python 解释器执行生成的代码这有任意代码执行风险。smolagents 提供两个安全选项一是用更安全的 Python 解释器二是接入 E2B 沙箱。生产环境建议用 E2Bfrom smolagents import CodeAgent, DuckDuckGoSearchTool, OpenAIServerModel agent CodeAgent( tools[DuckDuckGoSearchTool()], modelmodel, executor_typee2b, # 需要额外配置 E2B API Key max_steps6, )本地开发阶段用默认解释器即可但不要让它执行你不信任的输入。4. 运行验证一次完整的 Agent 执行过程4.1 执行命令与预期输出保存好first_agent.py后运行python first_agent.py你会看到类似这样的日志verbosity_level2 时Step 1: 模型生成代码 web_search(cheetah top speed km/h) web_search(Pont des Arts length meters) Step 2: 执行搜索结果回填 Step 3: 模型生成计算代码 cheetah_speed_kmh 120 bridge_length_m 155 speed_ms cheetah_speed_kmh * 1000 / 3600 time_s bridge_length_m / speed_ms print(time_s) Final answer: 约 4.65 秒关键观察点模型第一步没有直接回答而是生成了两次搜索调用的代码第二步拿到搜索结果后第三步生成了计算代码并执行。这就是 CodeAgent 和传统 JSON 工具调用的区别——动作是代码工具调用是函数调用结果直接 print 出来回填上下文。4.2 验证请求是否真正走通如果 Agent 返回了合理结果说明 Base URL、API Key、Model ID 三件套配置正确。你可以进一步验证请求确实发到了 TaoTokenimport os from openai import OpenAI client OpenAI( base_urlos.environ[TAOTOKEN_BASE_URL], api_keyos.environ[TAOTOKEN_API_KEY], ) resp client.chat.completions.create( modelQwen/Qwen2.5-Coder-32B-Instruct, messages[{role: user, content: 回复 OK}], ) print(resp.choices[0].message.content)能打印出 OK 就说明接入层通了。这一步单独验证很有必要因为 smolagents 的报错有时会被 Agent 循环掩盖直接调 API 能快速定位是接入问题还是 Agent 逻辑问题。4.3 观察 Agent 的步骤数与效率smolagents 官方提到 CodeAgent 比传统工具调用型 Agent 步骤减少约 30%。你可以通过日志里的 Step 计数验证。我实测一个需要搜索加计算的简单任务CodeAgent 用了 3 步如果用 JSON 工具调用通常要 4 到 5 步。步骤少意味着 LLM 调用次数少成本和延迟都低。如果你想让 Agent 输出更详细的中间过程把verbosity_level调到 3会打印每次生成的完整代码和工具返回。4.4 把 Agent 分享到 Hub可选smolagents 支持把 Agent 推到 HuggingFace Hubagent.push_to_hub(your-username/my_first_agent)之后可以用agent.from_hub(your-username/my_first_agent)加载。注意这需要 HuggingFace 登录凭证和 TaoToken 的 Key 是两套体系不要混淆。5. 常见报错排查401、local proxy failed、reading choices5.1 401 Unauthorized这是最常见的接入错误报错长这样openai.AuthenticationError: Error code: 401 - {error: {message: Invalid API key}}原因通常是三个API Key 复制时带了空格或换行环境变量没生效代码读到了空字符串Key 已过期或被删除。排查步骤先echo $TAOTOKEN_API_KEY确认环境变量有值且无多余字符再用 4.2 的直接调用脚本验证 Key 本身有效如果直接调用也 401去控制台重新创建一个 Key。5.2 local proxy failed 或连接超时报错类似openai.APIConnectionError: Connection error.或者日志里出现local proxy failed。这通常是 Base URL 写错或网络层问题。先确认api_base是https://taotoken.net/api不要多加/v1或漏掉协议头。然后确认本机没有设置会干扰请求的全局代理环境变量echo $HTTP_PROXY echo $HTTPS_PROXY如果有值且指向不可用的地址临时清掉再试unset HTTP_PROXY HTTPS_PROXY5.3 reading choices 报错报错长这样KeyError: choices或者IndexError: list index out of range出现在解析响应时。这通常说明返回的 JSON 结构里没有 choices 字段可能是模型 ID 写错导致服务端返回了错误信息也可能是请求被中间层拦截返回了 HTML。排查打印原始响应看看返回了什么import os from openai import OpenAI client OpenAI( base_urlos.environ[TAOTOKEN_BASE_URL], api_keyos.environ[TAOTOKEN_API_KEY], ) try: resp client.chat.completions.create( model你的模型ID, messages[{role: user, content: hi}], ) print(resp) except Exception as e: print(原始错误:, e)如果返回的是 HTML 或非 JSON说明请求没到正确的 API 端点检查 Base URL 是否多了路径。5.4 OAuth 或鉴权方式不匹配如果你看到OAuth相关报错通常是因为用了需要 OAuth 流程的模型提供方配置但 smolagents 的 OpenAIServerModel 走的是 API Key 鉴权。解决方式是确认你用的模型 ID 在 TaoToken 里是 API Key 鉴权模式而不是需要额外 OAuth 授权的类型。换一个支持 API Key 的模型 ID 即可。5.5 模型 ID 不存在报错openai.NotFoundError: Error code: 404 - {error: {message: model not found}}去模型对话页面核对模型 ID 的完整拼写注意大小写和斜杠。有些模型 ID 带组织前缀比如Qwen/Qwen2.5-Coder-32B-Instruct少写前缀就会 404。6. 继续深入从跑通到用好跑通第一个 Agent 之后你可以往几个方向深入。一是加更多工具smolagents 支持把 Python 函数直接包装成工具from smolagents import tool tool def add_numbers(a: int, b: int) - int: 把两个整数相加。 return a b然后在 CodeAgent 的 tools 列表里加上add_numbers模型就能在生成的代码里调用它。二是试试多模态输入smolagents 支持视觉和音频你可以传图片让 Agent 分析。三是用 CLI 工具快速跑任务不用写脚本smolagent 帮我查一下今天北京天气并给出穿衣建议 \ --model-type OpenAIServerModel \ --model-id Qwen/Qwen2.5-Coder-32B-Instruct \ --tools web_searchCLI 方式适合快速验证想法但注意它读取的环境变量名可能和脚本里不同需要确认。如果你要长期跑编码类 Agent建议了解 Coding Plan 的额度方案地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言的完整示例。API Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。最后说一个我踩过的坑smolagents 的 CodeAgent 在生成代码时会 import 一些库如果你的环境里没装执行会失败。日志里会显示ModuleNotFoundError按提示 pip install 即可。另外max_steps 不要设太小复杂任务 6 步可能不够设 10 到 15 比较稳妥但也要防止无限循环配合 verbosity 观察每步在干什么。