OpenAI Agents SDK는 도구, 핸드오프, 가드레일을 갖춘 에이전트를 만드는 Python 프레임워크입니다. SDK 문서에는 OpenAI가 아닌 제공자를 연결하는 방법이 나옵니다. BroadNet Inference 같은 OpenAI 호환 API에는 직접 만든 AsyncOpenAI 클라이언트를 SDK에 넘기고 Chat Completions 모델 클래스를 씁니다. SDK의 기본값은 Responses API인데, 이 API를 제공하지 않는 제공자가 많습니다.
설정
- SDK를 설치하세요. Python 3.10 이상이 필요합니다.
pip install openai-agents
export BROADNET_API_KEY='your-broadnet-key'
- 클라이언트, 모델, 에이전트를 만드세요.
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())
- 실행하세요. 에이전트가
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로 함께 실행한 에이전트는 각자 세션이 있어야 하며, 그렇지 않으면 대기열에 쌓입니다. 정액 요금으로 에이전트 병렬 실행하기를 참고하세요.
