用显式 Chat Completions 模型把 OpenAI Agents SDK 接到 Router One

安装 openai-agents 并设置凭证

使用 Python 3.10 或更新版本，在虚拟环境里安装 openai-agents 包；它依赖 openai 客户端库，示例中的 AsyncOpenAI 就从那里导入。下面是 macOS/Linux 的 shell 示例。运行前替换两个占位符，分别填入 Router One Key，以及当前目录中支持 Chat Completions 的精确模型 ID。ROUTER_ONE_* 是本示例定义并在代码中显式读取的环境变量；SDK 自己的 OPENAI_API_KEY 刻意不设置，因为 SDK 还会用这把 Key 上传 trace。运行 Python 文件时需沿用同一环境。

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

把 OpenAI Agents SDK 配置到 Router One base URL

保存为 agents_sdk_router_one.py，再运行 python agents_sdk_router_one.py。AsyncOpenAI 接收带 /v1 的 base URL 和你的 Key，请求不再依赖环境里的 OPENAI_API_KEY 或 OPENAI_BASE_URL。OpenAIChatCompletionsModel 包装这个 client，显式选择 /v1/chat/completions；目录中的模型 ID 原样传入，若 ID 自带 provider 前缀也应保留。set_tracing_disabled(True) 关闭 SDK 内置的 tracing——它默认开启，并用 OpenAI Key 把 trace 上传到 OpenAI 服务器。Runner.run_sync 在普通脚本里运行 Agent 循环；max_turns=3 把本次运行限制在三次模型调用以内，超出即抛出 MaxTurnsExceeded。result.final_output 就是纯文本回复。

import os

from openai import AsyncOpenAI
from agents import Agent, OpenAIChatCompletionsModel, Runner, set_tracing_disabled

# Tracing uploads to OpenAI's servers with an OpenAI key; there is none here.
set_tracing_disabled(True)

client = AsyncOpenAI(
    base_url="https://api.router.one/v1",
    api_key=os.environ["ROUTER_ONE_API_KEY"],
)
model = OpenAIChatCompletionsModel(
    model=os.environ["ROUTER_ONE_MODEL_ID"],
    openai_client=client,
)
agent = Agent(
    name="Assistant",
    instructions="Answer in one short sentence.",
    model=model,
)
result = Runner.run_sync(
    agent,
    "Reply with one short greeting.",
    max_turns=3,
)
print(result.final_output)

SDK 的哪个设置对应哪个端点

SDK 通过默认的 OpenAI provider 解析字符串模型名，走的是 Responses API。在 Router One 上，这条路径原生服务于当前上架的 GPT 系列和 DeepSeek ID，而 /v1/chat/completions 服务目录里的所有聊天模型；把 ID 发到不服务它的端点，会在调用任何模型之前收到 HTTP 400 invalid_request_error，消息为 model '<id>' must be called via …。按你配置 SDK 的方式对照下表，再到模型详情页核对端点：

控制运行预算，并逐次核对模型请求

一次运行就是一个循环：每个 turn 是一次模型调用，工具调用和 handoff 都会增加 turn。max_turns 是 SDK 的循环上限（不传时为 10，传 None 则不限制），超出即抛出 MaxTurnsExceeded；它不是计费上限，也不计入客户端重试。按 SDK 文档，除非你用 ModelSettings(retry=...) 主动开启，runner 不会重试模型请求；每一次到达网关的尝试都是独立请求，有各自的 Trace 和费用。为应用单独建立 Router One Key 并设置 maxSpend，然后在 Dashboard → Logs 按该 Key、时间、精确模型和 request_id 核对本次运行，用网关记录的费用核账；SDK 侧的用量或成本数字不一定采用你的 Router One 费率。Router One 只服务模型请求并记录 Trace。函数工具（@tool / function_tool）、handoff、guardrail、session 和 SDK 自己的 tracing，无论走哪条路径都运行在你的进程里：handoff 对模型来说是一次工具调用，session 把历史存在你这边；它们都不是网关功能。

OpenAI Agents SDK 该填哪个模型 ID？

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

OpenAI Agents SDK 用的是哪种 API 协议？

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

在 trace 里验证 OpenAI Agents SDK 的调用

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

常见问题