---
title: "OpenAI Agents SDK 커스텀 OpenAI 호환 제공자 설정 | BroadRouter"
description: "AsyncOpenAI와 OpenAIChatCompletionsModel로 OpenAI Agents SDK(Python)를 BroadNet Inference에 연결하고, OpenAI 키가 필요한 트레이싱을 끄는 방법을 설명합니다."
url: https://broadrouter.com/ko/guides/openai-agents-sdk-custom-provider/
lang: ko
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

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 이상이 필요합니다.

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

2.  **클라이언트, 모델, 에이전트를 만드세요.**

```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.  **실행하세요.** 에이전트가 `get_order_status`를 호출하고 그 결과를 바탕으로 답해야 합니다.

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

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

-   **에이전트별:** 위 예제처럼 `OpenAIChatCompletionsModel`을 `Agent.model`로 넘깁니다. 에이전트마다 다른 제공자를 쓸 때 적합합니다.
-   **전역 기본값:** `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로 라우팅할 때 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](https://broadrouter.com/ko/models/glm-5.3/) | 도구와 구조화된 출력 표기, 1M 컨텍스트 |
| 이미지 입력과 도구 | [Qwen3.8 27B](https://broadrouter.com/ko/models/qwen3.8-27b/) | 262K 컨텍스트, 아랍어로 테스트됨 |
| 정액 요금으로 오래 실행하는 에이전트 | [DeepSeek V4.1 Flash](https://broadrouter.com/ko/models/deepseek-v4.1-flash/) | 무제한 플랜, BroadNet이 도구 지원을 표기하지 않음 |

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

## 문제 해결

-   **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=...)`를 설정했다면 값을 늘리세요. [답변이 비어서 오는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)를 참고하세요.
-   **429.** 종량제 키는 분당 30 요청, 동시 처리 4 건까지 허용합니다. 도구 호출이 한 번 오갈 때마다 새 요청이 됩니다. [오류와 재시도](https://broadrouter.com/ko/guides/errors-and-retries/)를 참고하세요.
-   **플랜에서 에이전트를 병렬로 실행할 때.** [무제한 플랜 세션](https://broadrouter.com/ko/guides/unlimited-llm-api-sessions/)은 한 번에 요청 하나를 처리합니다. `asyncio.gather`로 함께 실행한 에이전트는 각자 세션이 있어야 하며, 그렇지 않으면 대기열에 쌓입니다. [정액 요금으로 에이전트 병렬 실행하기](https://broadrouter.com/ko/blog/run-parallel-coding-agents-flat-rate/)를 참고하세요.

## 이 가이드의 용어

[종량제(Pay-as-you-go)](https://broadrouter.com/ko/glossary/pay-as-you-go/)

종량제(pay-as-you-go)는 구독이나 최소 약정 없이 토큰, 요청, 오디오 분 같은 단위로 사용량을 측정해 쓴 만큼만 내는 요금 방식입니다. 대부분의 LLM API가 선불 잔액에서 차감하거나 정기 청구서를 발행하는 식으로 이렇게 과금합니다.

[AI 에이전트(AI agent)](https://broadrouter.com/ko/glossary/agent/)

AI 에이전트는 언어 모델이 목표를 향해 스스로 단계를 정하는 시스템입니다. 어떤 도구를 호출할지 결정하고, 결과를 읽고, 최종 답변을 내거나 한도에 닿을 때까지 이를 반복합니다. 정해진 지점에서 모델을 호출하는 고정된 스크립트는 보통 워크플로라고 부릅니다.

[구조화된 출력(Structured output)](https://broadrouter.com/ko/glossary/structured-output/)

구조화된 출력(structured output)은 모델의 응답을 개발자가 지정한 형식, 주로 JSON Schema에 맞추도록 제한해 코드가 안정적으로 파싱할 수 있게 하는 LLM API 기능입니다. 유효한 JSON만 보장하고 특정 구조는 보장하지 않는 JSON 모드보다 더 엄격합니다.

[동시 처리(concurrency)](https://broadrouter.com/ko/glossary/concurrency/)

동시 처리(concurrency)는 클라이언트가 같은 시점에 진행 중인 요청 수입니다. LLM API는 분당 요청 수와 별도로 키나 플랜마다 이를 제한하는 경우가 많습니다. 열려 있는 요청은 응답이 끝날 때까지 GPU 용량을 차지하기 때문입니다.

[속도 제한(rate limit)](https://broadrouter.com/ko/glossary/rate-limit/)

속도 제한(rate limit)은 API가 일정 시간 동안 클라이언트가 사용할 수 있는 양에 두는 상한으로, 분당 요청 수나 분당 토큰 수 같은 기준이 있습니다. 한도를 넘은 요청은 사용량이 다시 한도 아래로 내려갈 때까지 거부되며, 보통 HTTP 429 Too Many Requests가 반환됩니다.

[Chat Completions API](https://broadrouter.com/ko/glossary/chat-completions-api/)

Chat Completions API는 OpenAI의 HTTP 엔드포인트인 POST /v1/chat/completions로, 모델 이름과 역할이 붙은 메시지 목록을 받아 모델의 다음 메시지를 반환합니다. 이 요청과 응답 구조는 OpenAI 호환 제공업체와 SDK가 재사용하는 공통 형식이 되었습니다.

[JSON Schema(JSON 스키마)](https://broadrouter.com/ko/glossary/json-schema/)

JSON Schema는 JSON으로 작성하는 어휘로, 타입, 필수 필드, 허용 값, 중첩 같은 JSON 데이터의 구조를 기술하고 검증합니다. 현재 버전은 2020-12입니다. LLM API는 이를 사용해 도구 파라미터와 구조화된 출력이 따라야 할 정확한 형태를 정의합니다.

[OpenAI 호환 API(OpenAI-compatible API)](https://broadrouter.com/ko/glossary/openai-compatible-api/)

OpenAI 호환 API는 POST /v1/chat/completions처럼 OpenAI API와 같은 요청 및 응답 형식을 받는 HTTP API입니다. 그래서 OpenAI SDK와 도구는 base URL, API 키, 모델 이름만 바꾸면 이 API를 그대로 사용할 수 있습니다.

## 자주 묻는 질문

### 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로 병렬 실행하는 에이전트는 각각 세션이 하나씩 필요합니다.

## 관련 가이드

-   [BroadNet Inference에서 OpenAI Python SDK 사용하기](https://broadrouter.com/ko/guides/openai-python-sdk/)
-   [에이전트용 무제한 LLM API 플랜은 어떻게 작동하나요?](https://broadrouter.com/ko/guides/unlimited-llm-api-sessions/)
-   [추론 모델이 빈 답변을 반환하는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)
-   [LiteLLM을 BroadNet Inference에 연결하기(SDK와 프록시)](https://broadrouter.com/ko/guides/litellm-proxy-custom-provider/)
-   [BroadNet Inference와 함께 쓸 수 있는 모든 도구 (영어)](https://broadrouter.com/integrations/): SDK, 코딩 에이전트, 채팅 UI, 자동화 도구와 각 도구의 정확한 설정

실제 워크로드로 테스트해 보세요. 신규 계정에는 US$5 상당의 초기 크레딧이 제공되며 Gemma 및 음성 전사에 사용할 수 있습니다. DeepSeek, GLM 및 Qwen3.8 모델은 충전이 필요합니다.

[시작하기](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-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=ko-guides-openai-agents-sdk-custom-provider&utm_content=sources)
