BroadRouter

在 BroadNet Inference 上运行 OpenAI Agents SDK

更新于

创建一个 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 或更高版本。
pip install openai-agents
export BROADNET_API_KEY='your-broadnet-key'
  1. 创建客户端、模型和 agent。
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())
  1. 运行。 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。

全局默认的写法如下:

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 列出了工具和结构化输出;1M 上下文
图片输入加工具 Qwen3.8 27B 262K 上下文;经过阿拉伯语测试
固定价格的长时间运行 agent DeepSeek V4.1 Flash 不限量套餐;BroadNet 未列出工具

SDK 文档提醒,有些供应商不支持 JSON schema 结构化输出。如果你在 agent 上设置了 output_type,请使用 GLM 5.3 或 Qwen3.8 27B。价格对比见价格页面。

故障排查

  • 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=...),请调高它。为什么回答会是空的。
  • 429。 按量付费密钥每分钟允许 30 个请求,同时最多 4 个。每一轮工具调用都是一个新请求。见错误码与重试。
  • 在套餐上并行运行 agent。 一个不限量套餐会话一次只处理一个请求。用 asyncio.gather 同时启动的 agent 每个都需要一个会话,否则会排队。见用固定价格并行运行编程 agent。

常见问题

用自定义 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 则每个都需要一个会话。

以 Markdown 格式阅读问 ChatGPT问 Claude问 Perplexity