---
title: "OpenAI Agents SDK 接入自定义 OpenAI 兼容供应商 | BroadRouter"
description: "通过 AsyncOpenAI 和 OpenAIChatCompletionsModel，让 Python 版 OpenAI Agents SDK 调用 BroadNet Inference，并关闭需要 OpenAI 密钥的 tracing。"
url: https://broadrouter.com/zh/guides/openai-agents-sdk-custom-provider/
lang: zh-Hans
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

本页由英文原文借助 AI 翻译。[阅读英文原文](https://broadrouter.com/guides/openai-agents-sdk-custom-provider/)（2026-11-16 更新）。

# 在 BroadNet Inference 上运行 OpenAI Agents SDK

更新于 2026-11-16

创建一个 AsyncOpenAI 客户端，base\_url 设为 https://inference.broadnet.ai/v1，填入你的 BroadNet 密钥；再用 OpenAIChatCompletionsModel 包装它，模型 ID 例如 broadnet/glm-5.3，然后把这个模型传给 Agent。除非你另有一个用于 tracing 的 OpenAI 密钥，否则请调用 set\_tracing\_disabled(True)。

OpenAI Agents SDK 是一个 Python 框架，用来构建带工具、handoff 和 guardrail 的 agent。它的文档说明了如何接入非 OpenAI 的供应商。对于 BroadNet Inference 这样的 OpenAI 兼容 API，你要把自己的 `AsyncOpenAI` 客户端交给 SDK，并使用 Chat Completions 模型类。SDK 默认走 Responses API，而很多供应商并不提供这个 API。

## 配置步骤

1.  **安装 SDK。** 需要 Python 3.10 或更高版本。

```bash
pip install openai-agents
export BROADNET_API_KEY='your-broadnet-key'
```

2.  **创建客户端、模型和 agent。**

```python
import asyncio
import os

from agents import (
    Agent,
    AsyncOpenAI,
    OpenAIChatCompletionsModel,
    Runner,
    function_tool,
    set_tracing_disabled,
)

set_tracing_disabled(disabled=True)  # tracing needs a platform.openai.com key

client = AsyncOpenAI(
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
)

model = OpenAIChatCompletionsModel(model="broadnet/glm-5.3", openai_client=client)

@function_tool
def get_order_status(order_id: str) -> str:
    """Look up an order."""
    return f"Order {order_id}: shipped"

agent = Agent(
    name="Support agent",
    instructions="Answer briefly. Use tools when you need order data.",
    model=model,
    tools=[get_order_status],
)

async def main():
    result = await Runner.run(agent, "Where is order 4471?")
    print(result.final_output)

asyncio.run(main())
```

3.  **运行。** agent 应该会调用 `get_order_status`，并根据它的返回结果作答。

## 接入供应商的三种方式

SDK 文档列出了以下内置选项：

-   **按 agent：** 像上面那样，把 `OpenAIChatCompletionsModel` 作为 `Agent.model` 传入。不同 agent 使用不同供应商时用这种方式。
-   **全局默认：** `set_default_openai_client(client)` 把你的客户端设为默认客户端，并搭配 `set_default_openai_api("chat_completions")` 使用。
-   **按运行：** 在 `RunConfig(model_provider=...)` 中传入自定义的 `ModelProvider`。

全局默认的写法如下：

```python
import os
from agents import (
    Agent,
    AsyncOpenAI,
    set_default_openai_api,
    set_default_openai_client,
    set_tracing_disabled,
)

client = AsyncOpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
set_default_openai_client(client, use_for_tracing=False)
set_default_openai_api("chat_completions")
set_tracing_disabled(True)

agent = Agent(name="Assistant", instructions="Be brief.", model="broadnet/glm-5.3")
```

如果只用环境变量，就设置 `OPENAI_BASE_URL=https://inference.broadnet.ai/v1`，把 `OPENAI_API_KEY` 设为你的 BroadNet 密钥，然后同样调用 `set_default_openai_api` 和 `set_tracing_disabled`。

SDK 文档指出，走 Chat Completions 时，它会静默丢弃只有 Responses 才有的字段，例如 `previous_response_id`、`conversation_id` 和 `prompt`。如果希望这时直接报错，请在 `OpenAIProvider` 上设置 `strict_feature_validation=True`。对话状态请在你自己的代码里维护，例如把上一次结果的输入列表传给下一次运行。网页搜索、文件搜索这类由 OpenAI 托管的工具在其他供应商上并不存在。agent 需要调用的任何功能都请用 `function_tool` 实现。

## Tracing

tracing 默认开启，会把 trace 发送给 OpenAI。SDK 文档说，如果没有来自 platform.openai.com 的 API 密钥，就应该用 `set_tracing_disabled()` 关闭它，或者配置其他 tracing processor。如果你有 OpenAI 密钥，可以保持 tracing 开启，并通过 `set_tracing_export_api_key(...)` 传入这个密钥。SDK 只用它上传 trace。你的 BroadNet 密钥不能用于这个用途。

## 选哪个模型

| Agent 类型 | 模型 | 说明 |
| --- | --- | --- |
| 使用工具的 agent | [GLM 5.3](https://broadrouter.com/zh/models/glm-5.3/) | 列出了工具和结构化输出；1M 上下文 |
| 图片输入加工具 | [Qwen3.8 27B](https://broadrouter.com/zh/models/qwen3.8-27b/) | 262K 上下文；经过阿拉伯语测试 |
| 固定价格的长时间运行 agent | [DeepSeek V4.1 Flash](https://broadrouter.com/zh/models/deepseek-v4.1-flash/) | 不限量套餐；BroadNet 未列出工具 |

SDK 文档提醒，有些供应商不支持 JSON schema 结构化输出。如果你在 agent 上设置了 `output_type`，请使用 GLM 5.3 或 Qwen3.8 27B。价格对比见[价格页面](https://broadrouter.com/zh/pricing/)。

## 故障排查

-   **401。** BroadNet 密钥错误、已过期，或者按量付费额度已用完。日志里的 tracing 错误是另一回事：它们说明 tracing 仍然开着，但没有 OpenAI 密钥。
-   **404 或 “not found”。** 你很可能还在走 Responses API。请使用 `OpenAIChatCompletionsModel` 或 `set_default_openai_api("chat_completions")`。如果已经设置了，再检查模型 ID 是否与 BroadNet 的完全一致。付费模型需要先充值；$5 额度可用于 Gemma 4 VL 26B 和两个 Transcribe 模型。
-   **`final_output` 为空。** 思考内容计入 `max_tokens`。如果你设置了 `ModelSettings(max_tokens=...)`，请调高它。[为什么回答会是空的](https://broadrouter.com/zh/guides/reasoning-tokens-empty-response/)。
-   **429。** 按量付费密钥每分钟允许 30 个请求，同时最多 4 个。每一轮工具调用都是一个新请求。见[错误码与重试](https://broadrouter.com/zh/guides/errors-and-retries/)。
-   **在套餐上并行运行 agent。** 一个[不限量套餐会话](https://broadrouter.com/zh/guides/unlimited-llm-api-sessions/)一次只处理一个请求。用 `asyncio.gather` 同时启动的 agent 每个都需要一个会话，否则会排队。见[用固定价格并行运行编程 agent](https://broadrouter.com/zh/blog/run-parallel-coding-agents-flat-rate/)。

## 本指南涉及的术语

[AI 智能体（AI agent）](https://broadrouter.com/zh/glossary/agent/)

AI 智能体是由语言模型自主决定步骤、朝目标推进的系统：它决定调用哪些工具、读取结果，然后重复，直到给出最终回答或触及上限。在固定位置调用模型的固定脚本，通常称为工作流（workflow）。

[按量付费（pay-as-you-go）](https://broadrouter.com/zh/glossary/pay-as-you-go/)

按量付费是一种计价模式：你只为实际用量付费，按 token、请求次数或音频分钟等单位计量，没有订阅费，也没有最低消费承诺。大多数大模型 API 都这样计费，从预付余额中扣减或定期开具账单。

[大模型包月套餐（flat-rate LLM plan）](https://broadrouter.com/zh/glossary/flat-rate-llm-plan/)

大模型包月套餐（固定价格套餐）是按一个周期（如一个月）收取固定费用、提供大模型 API 使用权的计价方式，不按 token 计费。这类套餐通常会限制别的东西，如并发、速度、模型或使用时间窗口，所以限制条件和价格同样重要。

[结构化输出（structured output）](https://broadrouter.com/zh/glossary/structured-output/)

结构化输出是大模型 API 的一项功能，它把模型的回复约束为开发者指定的格式（通常是 JSON Schema），让代码能可靠地解析。它比 JSON mode 更严格：JSON mode 只保证输出是合法 JSON，不保证特定结构。

[Chat Completions API（对话补全接口）](https://broadrouter.com/zh/glossary/chat-completions-api/)

Chat Completions API 是 OpenAI 的 HTTP 端点 POST /v1/chat/completions，它接收模型名称和一组带角色标记的消息，返回模型的下一条消息。它的请求与响应结构已成为 OpenAI 兼容服务商和各类 SDK 通用的格式。

[并发（concurrency）](https://broadrouter.com/zh/glossary/concurrency/)

并发（concurrency）是客户端在同一时刻正在进行中的请求数。大模型 API 往往按密钥或套餐单独限制并发，与每分钟请求数分开计算，因为每个未完成的请求在响应结束前都会占用 GPU 资源。

[速率限制（rate limit）](https://broadrouter.com/zh/glossary/rate-limit/)

速率限制是 API 对客户端在一个时间窗口内的使用量设定的上限，例如每分钟请求数或每分钟 token 数。超出限制的请求会被拒绝，通常返回 HTTP 429 Too Many Requests，直到用量回落到限制以下。

[JSON Schema](https://broadrouter.com/zh/glossary/json-schema/)

JSON Schema 是一套用 JSON 编写的词汇，用于描述和校验 JSON 数据的结构：类型、必填字段、允许的取值和嵌套。当前版本是 2020-12。大模型 API 用它来定义工具参数，以及结构化输出必须遵循的确切结构。

## 常见问题

### 用自定义 base URL 时，Agents SDK 为什么报 404？

SDK 默认使用 Responses API，而 BroadNet 提供的是对话补全。请使用 OpenAIChatCompletionsModel；如果你通过环境变量配置客户端，就调用 set\_default\_openai\_api("chat\_completions")。

### Agents SDK 为什么一直报 tracing 相关的错误？

tracing 会把数据上传到 OpenAI，需要一个来自 platform.openai.com 的密钥。SDK 文档建议没有这个密钥时调用 set\_tracing\_disabled()，或者换用其他 tracing processor。

### 只用环境变量能配置 Agents SDK 吗？

可以。把 OPENAI\_BASE\_URL 设为 https://inference.broadnet.ai/v1，OPENAI\_API\_KEY 设为你的 BroadNet 密钥，然后调用 set\_default\_openai\_api("chat\_completions") 和 set\_tracing\_disabled(True)。OPENAI\_DEFAULT\_MODEL 用来给没有指定模型的 agent 设置模型。

### 多 agent 运行需要几个套餐会话？

同时运行的每个请求各需要一个。handoff 是一个 agent 接一个 agent 依次运行，所以一个会话就够了。用 asyncio.gather 并行运行的 agent 则每个都需要一个会话。

## 相关指南

-   [用 OpenAI Python SDK 调用 BroadNet Inference](https://broadrouter.com/zh/guides/openai-python-sdk/)
-   [面向智能体的不限量 LLM API 套餐如何运作](https://broadrouter.com/zh/guides/unlimited-llm-api-sessions/)
-   [推理模型为什么返回空回答](https://broadrouter.com/zh/guides/reasoning-tokens-empty-response/)
-   [用 LiteLLM 路由到 BroadNet Inference（SDK 与代理）](https://broadrouter.com/zh/guides/litellm-proxy-custom-provider/)
-   [所有可与 BroadNet Inference 配合使用的工具（英文）](https://broadrouter.com/integrations/)：SDK、编程智能体、聊天界面和自动化工具，并附每个工具的具体设置

用你的真实业务负载试一试。新账户可获得 US$5 初始额度，用于 Gemma和转写。DeepSeek、GLM和Qwen3.8 需要先充值。

[开始使用](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-guides-openai-agents-sdk-custom-provider&utm_content=page-cta) ·

**来源**

-   [OpenAI Agents SDK 文档：Models（非 OpenAI 供应商）（核对于 2026-11-14）](https://openai.github.io/openai-agents-python/models/)
-   [PyPI 上的 openai-agents 包（0.24，Python 3.10+，核对于 2026-11-14）](https://pypi.org/project/openai-agents/)
-   [BroadNet Inference API 参考文档（英文）](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=zh-guides-openai-agents-sdk-custom-provider&utm_content=sources)
