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

> https://router.one/zh/integrations/openai-agents-sdk 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 最后更新：2026-09-11

OpenAI Agents SDK（openai-agents 包）用 Python 运行 Agent，自带处理工具调用、handoff、guardrail 和 session 的循环。把它的模型调用指向 Router One 之后，这个循环仍在你的进程里跑，网关负责每一次模型请求，并记录带成本和延迟的 Trace。SDK 默认走 Responses API；本指南在显式的 AsyncOpenAI client 上构造 OpenAIChatCompletionsModel，让目录里任何聊天模型 ID 都能用，再说明什么时候更适合保留 Responses 默认、为什么 tracing 必须关掉或单独给一把 OpenAI Key，以及怎样给一次会发出多个模型请求的运行设预算。

## 安装 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 文件时需沿用同一环境。

`terminal`

```bash
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 就是纯文本回复。

`agents_sdk_router_one.py`

```python
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 的方式对照下表，再到模型详情页核对端点：

| SDK 设置 | 端点或运行位置 | 需要核对 |
| --- | --- | --- |
| OpenAIChatCompletionsModel(model=…, openai_client=client)，即上面的示例 | POST /v1/chat/completions | /models 里任一聊天模型 ID；该 ID 的工具调用与流式输出 |
| Agent(model="<id>") 走默认 provider，或只调用 set_default_openai_client(client) | POST /v1/responses（SDK 默认，OpenAIResponsesModel） | 该 ID 的详情页列出 /v1/responses；其他系列会返回 400 must be called via |
| set_default_openai_api("chat_completions") 配合 set_default_openai_client(client) 或 OPENAI_BASE_URL | 所有字符串模型名都走 POST /v1/chat/completions | 关闭 tracing 或设置 set_tracing_export_api_key，并给 set_default_openai_client 传 use_for_tracing=False，否则这把 Key 会被用来上传 trace |
| 托管工具：WebSearchTool、FileSearchTool、CodeInterpreterTool、HostedMCPTool、ImageGenerationTool；ComputerTool 作为本地 harness | 仅 Responses 路径；SDK 文档把它们列为使用 OpenAIResponsesModel 时的内置工具 | 该 ID 的 Responses 支持及工具类型，用一次真实请求验证；FileSearchTool 依赖 OpenAI Vector Stores，网关没有文件存储 API |
| previous_response_id、conversation_id | 仅 Responses；在 Chat Completions 上会被静默丢弃，除非设置 OpenAIProvider(use_responses=False, strict_feature_validation=True) | 依赖服务端对话状态之前，先确认该 ID 的详情页列出 /v1/responses |

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

一次运行就是一个循环：每个 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；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

## 常见问题

### 为什么要构造 OpenAIChatCompletionsModel，而不是直接给 Agent 传模型名？

字符串模型名由 SDK 默认的 OpenAI provider 解析，而 SDK 文档写明它默认使用 Responses API，且许多其他 provider 尚不支持这条路径。在 Router One 上，/v1/responses 原生服务于当前上架的 GPT 系列和 DeepSeek ID；把 Claude、Gemini 或 Grok 的 ID 发到那里，会在调用任何模型之前收到 HTTP 400 invalid_request_error，消息为 model '<id>' must be called via …。显式构造的 OpenAIChatCompletionsModel 始终走 /v1/chat/completions，它服务目录里的所有聊天模型，所以同一份文件对你导出的任何 ID 都适用。若你的 Agent 只用详情页列出 /v1/responses 的 ID，并且需要这条路径的功能（比如托管工具），可以保留 Responses 默认；SDK 也建议一个工作流只用一种模型形态，因为两种形态支持的功能和工具并不相同。

### tracing 报 401，或者我不想把提示词上传到任何地方，该怎么设置？

SDK 的 tracing 默认开启，按文档的说法，它用与模型请求相同的 OpenAI API Key 把 trace 上传到 OpenAI 服务器；排障章节里的 Tracing client error 401 说的正是没有 platform.openai.com Key 的情况，Router One 的 Key 不能顶替这个用途。关闭方式有三种：像示例那样调用 set_tracing_disabled(True)，在环境里设置 OPENAI_AGENTS_DISABLE_TRACING=1，或按单次运行传 RunConfig(tracing_disabled=True)。如果仍想用 OpenAI 的 Traces 面板，用 set_tracing_export_api_key(...) 单独给导出器一把 OpenAI Key，并在全局注册 Router One client 时给 set_default_openai_client 传 use_for_tracing=False；注意此时 generation span 默认包含请求输入和响应输出，除非把 trace_include_sensitive_data 设为 False。每次请求的模型、tokens、费用和延迟记录在 Router One 的 Trace 里（Dashboard → Logs），与这个设置无关。

### TypeScript 版 SDK（@openai/agents）也要做同样的改动吗？

要，而且开关的名字一致。TypeScript SDK 的 OpenAI provider 同样默认走 Responses API：setOpenAIAPI('chat_completions') 让字符串模型名改走 Chat Completions；setDefaultOpenAIClient(new OpenAI({ baseURL: 'https://api.router.one/v1', apiKey: ... })) 提供 Router One client（或把 baseURL 和 apiKey 传给 OpenAIProvider）；setTracingDisabled(true) 或 OPENAI_AGENTS_DISABLE_TRACING=1 停止 trace 导出——导出默认也用同一把 OpenAI Key，setTracingExportApiKey(...) 可以单独指定。要核对的事情相同：模型详情页上的端点，以及 Dashboard → Logs 里的一次普通请求。

### OpenAI Agents SDK 能通过网关用哪些模型？

选用当前目录中同时支持 OpenAI Agents SDK 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准；不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型，只证明模型发现成功，仍需验证实际调用。

### 能列出模型，但调用报 400 或 404，怎么办？

先记录实际请求路径和错误消息，再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配；404 可能是请求路径或资源不存在，不能直接判定模型下线。若错误提示 must be called via，按它指明的端点调整客户端 provider，或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。

### 中国大陆能直连吗？

能。网关在大陆可直连、无需 VPN，配置与全球环境完全一致。

### 报 401/402/403/429 怎么排查？

先到 Dashboard → Logs 核对请求及错误消息。401 查 Key 是否传入和有效；402 查钱包余额与 maxSpend；403 查 Key 权限和访问限制；429 查请求频率、token 限额及上游限流，按错误来源处理。保留 request_id，再按错误码速查页逐项排查。

## 相关页面

- 全部接入指南：https://router.one/zh/integrations
- OpenAI Agents SDK 的 API 错误排查：https://router.one/zh/llm-api-error-codes
- API 兼容性：端点与功能对照：https://router.one/zh/facts/api-compatibility.md
- Responses API 配置与限制：https://router.one/zh/codex-responses-api
- Claude Agent SDK 接入：https://router.one/zh/integrations/claude-agent-sdk
- Haystack 接入：https://router.one/zh/integrations/haystack
- OpenAI Python SDK 接入：https://router.one/zh/integrations/openai-sdk
- 工具调用的 API 要求：https://router.one/zh/llm-tool-calling
- 按 Key 追踪模型调用成本：https://router.one/zh/llm-cost-tracking
- OpenAI Agents SDK 官方文档：模型与非 OpenAI provider：https://openai.github.io/openai-agents-python/models/
- OpenAI Agents SDK 官方文档：配置与 tracing 开关：https://openai.github.io/openai-agents-python/config/
- OpenAI Agents SDK 官方文档：工具：https://openai.github.io/openai-agents-python/tools/
- 网关层负责什么：https://router.one/zh/llm-api-gateway
- OpenAI 兼容 API：https://router.one/zh/openai-compatible-api
- API 文档：https://router.one/zh/docs
- 本页规范地址：https://router.one/zh/integrations/openai-agents-sdk
- 模型与每模型 token 价格：https://router.one/zh/models （markdown：https://router.one/zh/models.md ）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md