BroadRouter

BroadNet Inference에서 OpenAI Agents SDK 실행하기

업데이트

base_url은 https://inference.broadnet.ai/v1, api_key는 BroadNet 키로 AsyncOpenAI 클라이언트를 만들고, broadnet/glm-5.3 같은 모델 ID와 함께 OpenAIChatCompletionsModel로 감싼 뒤 그 모델을 Agent에 넘기세요. 트레이싱용 OpenAI 키가 따로 없다면 set_tracing_disabled(True)를 호출하세요.

OpenAI Agents SDK는 도구, 핸드오프, 가드레일을 갖춘 에이전트를 만드는 Python 프레임워크입니다. SDK 문서에는 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. 클라이언트, 모델, 에이전트를 만드세요.
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. 실행하세요. 에이전트가 get_order_status를 호출하고 그 결과를 바탕으로 답해야 합니다.

제공자를 연결하는 세 가지 방법

SDK 문서에는 다음과 같은 기본 제공 방식이 나옵니다.

  • 에이전트별: 위 예제처럼 OpenAIChatCompletionsModel을 Agent.model로 넘깁니다. 에이전트마다 다른 제공자를 쓸 때 적합합니다.
  • 전역 기본값: 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로 라우팅할 때 SDK는 previous_response_id, conversation_id, prompt처럼 Responses 전용 필드를 아무 알림 없이 버립니다. 대신 오류가 나게 하려면 OpenAIProvider에 strict_feature_validation=True를 설정하세요. 대화 상태는 직접 코드에서 관리하세요. 예를 들어 이전 결과의 입력 목록을 다음 실행에 넘기면 됩니다. 웹 검색, 파일 검색 같은 OpenAI 호스팅 도구는 다른 제공자에는 없습니다. 에이전트가 호출해야 하는 기능은 모두 function_tool로 만드세요.

트레이싱

트레이싱은 기본으로 켜져 있으며 트레이스를 OpenAI로 보냅니다. SDK 문서는 platform.openai.com에서 발급한 API 키가 없으면 set_tracing_disabled()로 트레이싱을 끄거나 다른 트레이싱 프로세서를 설정하라고 안내합니다. OpenAI 키가 있다면 트레이싱을 켠 채로 set_tracing_export_api_key(...)로 그 키를 넘길 수 있습니다. SDK는 이 키를 트레이스 업로드에만 씁니다. BroadNet 키로는 이 용도에 쓸 수 없습니다.

어떤 모델을 고를까

에이전트 유형 모델 비고
도구를 쓰는 에이전트 GLM 5.3 도구와 구조화된 출력 표기, 1M 컨텍스트
이미지 입력과 도구 Qwen3.8 27B 262K 컨텍스트, 아랍어로 테스트됨
정액 요금으로 오래 실행하는 에이전트 DeepSeek V4.1 Flash 무제한 플랜, BroadNet이 도구 지원을 표기하지 않음

SDK 문서는 일부 제공자가 JSON 스키마 기반 구조화된 출력을 지원하지 않는다고 경고합니다. 에이전트에 output_type을 설정한다면 GLM 5.3이나 Qwen3.8 27B를 쓰세요. 가격은 가격 페이지에서 비교할 수 있습니다.

문제 해결

  • 401. BroadNet 키가 틀렸거나, 만료되었거나, 종량제 사용 가능 금액이 소진되었습니다. 로그에 보이는 트레이싱 오류는 별개의 문제로, OpenAI 키 없이 트레이싱이 아직 켜져 있다는 뜻입니다.
  • 404 또는 “not found”. Responses API를 쓰고 있을 가능성이 큽니다. OpenAIChatCompletionsModel을 쓰거나 set_default_openai_api("chat_completions")를 호출하세요. 이미 설정했다면 모델 ID가 BroadNet의 ID와 정확히 같은지 확인하세요. 유료 모델은 충전이 필요하며, 초기 크레딧($5 상당)은 Gemma 4 VL 26B와 Transcribe 모델 두 개에 쓸 수 있습니다.
  • 비어 있는 final_output. 추론도 max_tokens에 포함됩니다. ModelSettings(max_tokens=...)를 설정했다면 값을 늘리세요. 답변이 비어서 오는 이유를 참고하세요.
  • 429. 종량제 키는 분당 30 요청, 동시 처리 4 건까지 허용합니다. 도구 호출이 한 번 오갈 때마다 새 요청이 됩니다. 오류와 재시도를 참고하세요.
  • 플랜에서 에이전트를 병렬로 실행할 때. 무제한 플랜 세션은 한 번에 요청 하나를 처리합니다. asyncio.gather로 함께 실행한 에이전트는 각자 세션이 있어야 하며, 그렇지 않으면 대기열에 쌓입니다. 정액 요금으로 에이전트 병렬 실행하기를 참고하세요.

자주 묻는 질문

Agents SDK에서 커스텀 base URL을 쓰면 왜 404 오류가 나나요?

SDK는 기본적으로 Responses API를 쓰지만 BroadNet은 chat completions를 제공합니다. OpenAIChatCompletionsModel을 쓰거나, 환경 변수로 클라이언트를 설정했다면 set_default_openai_api("chat_completions")를 호출하세요.

Agents SDK가 트레이싱 관련 오류를 내는 이유는 무엇인가요?

트레이싱은 OpenAI로 업로드되며 platform.openai.com에서 발급한 키가 필요합니다. SDK 문서는 그런 키가 없으면 set_tracing_disabled()로 끄거나 다른 트레이싱 프로세서를 쓰라고 권합니다.

환경 변수만으로 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의 모델이 쓰입니다.

멀티 에이전트 실행에는 플랜 세션이 몇 개 필요한가요?

동시에 실행되는 요청마다 하나씩 필요합니다. 핸드오프는 에이전트를 하나씩 차례로 실행하므로 세션 하나면 충분합니다. asyncio.gather로 병렬 실행하는 에이전트는 각각 세션이 하나씩 필요합니다.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기