通过 OpenAIModel 和一个 api_base 把 smolagents 接到 Router One

安装 openai 扩展并设置凭证

使用 Python 3.10 或更新版本。安装带 openai 扩展的 smolagents：OpenAIModel 调用的是 OpenAI Python 包，缺少时会抛出 ModuleNotFoundError，消息为 Please install 'openai' extra to use OpenAIModel。toolkit 扩展装的是默认工具箱（DuckDuckGoSearchTool 用的 ddgs、VisitWebpageTool 用的 markdownify），之后设置 add_base_tools=True 时会用到；下面示例用的 WebSearchTool 只依赖核心包自带的 requests。两个扩展写在同一个方括号里，就是安装页文档给出的写法。下面是 macOS/Linux 的 shell 示例，运行前替换两个占位符：一把 Router One Key，以及当前目录中某个聊天模型的精确 ID。ROUTER_ONE_* 是本示例自己定义并显式读取的变量名；Key 直接作为 api_key 传给模型类，所以不需要设置 OPENAI_API_KEY。运行 Python 文件时沿用同一环境。

python -m pip install "smolagents[openai,toolkit]"
export ROUTER_ONE_API_KEY="sk-your-router-one-key"
export ROUTER_ONE_MODEL_ID="<exact-model-id-from-/models>"

把 smolagents 配置到 Router One base URL

保存为 agent.py，再运行 python agent.py。OpenAIModel 的 model_id 原样填目录里的模型 ID，若 ID 自带 provider 前缀也要保留；api_base 填带 /v1 的 base URL，它会作为 base_url 交给 OpenAI 客户端，客户端自行拼接 /chat/completions，所以一次运行里的每次模型调用都是一个 POST /v1/chat/completions；api_key 从 ROUTER_ONE_API_KEY 读取。第一个 CodeAgent 设 tools=[] 和 max_steps=4：模型写出 Python 代码，smolagents 解析代码块并在本地 Python 执行器里运行，代码调用 final_answer 或用完第四步时运行结束。return_full_result=True 让 run() 返回 RunResult 而不是只返回答案：output 是最终答案，state 是 success 或 max_steps_error，token_usage 是 API 为每个动作步和规划步报告的输入、输出 token 之和。第二个 Agent 加上 WebSearchTool()，它默认用 DuckDuckGo 引擎、不需要任何 Key：搜索是从你的进程发往 lite.duckduckgo.com 的 HTTP 请求，不会出现在 Logs 里，而这次运行的模型调用照样到达网关。两个 Agent 只差这一点，只在带工具时失败，就能定位到工具自身的网络访问。

import os

from smolagents import CodeAgent, OpenAIModel, WebSearchTool

model = OpenAIModel(
    model_id=os.environ["ROUTER_ONE_MODEL_ID"],
    api_base="https://api.router.one/v1",
    api_key=os.environ["ROUTER_ONE_API_KEY"],
)

# 1. No tools: every model call in this run is one POST /v1/chat/completions
agent = CodeAgent(tools=[], model=model, max_steps=4)
result = agent.run(
    "Compute the 30th Fibonacci number in Python and return it with final_answer.",
    return_full_result=True,
)
print(result.output, result.state, result.token_usage)

# 2. Same model, one built-in tool: the search leaves your process; the model calls still reach the gateway
agent = CodeAgent(tools=[WebSearchTool()], model=model, max_steps=4)
print(agent.run("Find the URL of the smolagents documentation and return it with final_answer."))

smolagents 的哪个设置发出哪种请求

连接信息由 OpenAIModel 携带，每一步向模型要什么则由 Agent 类决定。下表按本指南涉及的设置，给出该填的值、它产生的请求，以及使用前要确认的能力。

给一个 Agent 定预算，并逐次核对请求

一次 agent.run() 是多次模型请求：每个动作步是一次请求；设置了 planning_interval 时，第 1 步以及之后每隔这么多步会加一个规划步；到达 max_steps 时还会再发一次请求，根据运行记忆写出最终答案。每一步都会把整个运行记忆重新作为 messages 发送，所以输入 token 会逐步增长：max_steps 限制的是步数，不是花费。两层重试也会增加请求：OpenAIModel 内部的 OpenAI 客户端默认对连接错误和 408、409、429、5xx 响应重试 2 次，可用 client_kwargs={'max_retries': 0} 调整；模型类自身对消息里含 429 或 rate limit 的错误最多尝试 3 次，基础等待 60 秒，retry=False 可关闭，所以持续的 429 在一步里最多能产生九次尝试。每一次真正到达网关的尝试在 Dashboard → Logs 里都是独立请求，有各自的 request_id、Trace 和费用。给每个 Agent 单独一把设了 maxSpend 的 Key：失控的循环会在你设的上限处收到 HTTP 402，两层重试都不会重试 402，钱包和其他 Key 不受影响。模型类上的 requests_per_minute 是客户端侧限速，与 Key 的 rateLimit 无关。RunResult.token_usage 和 agent.monitor.get_total_token_counts() 是库对 API 报告用量的统计，每次 run() 都会重置（reset=False 除外）；费用以 Logs 记录为准。按 Key、时间、模型和 token 数对账，报障时保留 request_id。Router One 只记录模型调用元数据，不运行 Agent 的代码、工具或沙箱。

smolagents 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 smolagents 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个工具单独建 API Key，并设置 maxSpend 消费上限。

smolagents 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

在 trace 里验证 smolagents 的调用

先在 smolagents 发出一次简单文本请求，再到 Dashboard → Logs 按时间、模型和 request_id 核对 trace：tokens、花费、延迟和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

常见问题