멀티 모델 에이전트 개발을 훨씬 덜 고통스럽게 만드는 사실이 하나 있습니다. 2026년에는 사실상 모든 Python 에이전트 프레임워크가 기본적으로 하위 LLM을 커스텀 OpenAI 호환 base_url로 지정하는 기능을 지원할 것입니다. 새로운 패키지도, 포크(fork)도, 프레임워크 변경도 필요 없습니다. 하나의 URL과 하나의 키만 설정하면, 프레임워크는 당신이 선택한 어떤 백엔드와도 통신합니다.

이는 단일 OpenAI 호환 게이트웨이 (OpenAI-compatible gateway) — Claude, GPT, Gemini, DeepSeek, Kimi 등을 하나의 키로 전면에 내세우고, 폴백(fallback) 기능과 단일 청구 시스템을 갖춘 — 가 이 모든 프레임워크의 자연스러운 백엔드가 될 수 있음을 의미합니다. 오케스트레이션(orchestration)은 프레임워크가 담당하고, 모델은 하나의 엔드포인트(endpoint)에서 가져옵니다.

이 포스트는 지도 역할을 할 것입니다. 각 프레임워크를 위한 정확한 한 줄 코드(one-liner)와 함께, 각 프레임워크가 가진 **단 하나의 솔직한 주의사항 (gotcha)**을 알려드립니다. 왜냐하면 그 주의사항들이 실제로 당신의 오후 시간을 앗아가는 주범이기 때문입니다.

공개 사항 (Disclosure): 저는 이러한 게이트웨이 중 하나인 daoxe에서 일하고 있습니다. 하지만 아래 내용은 daoxe에 특화된 것이 아닙니다. 모든 코드 스니펫은 어떠한 OpenAI 호환 엔드포인트에서도 작동합니다. base URL을 당신의 것으로 바꾸기만 하면 됩니다. 프레임워크는 그 뒤에 누가 있는지 상관하지 않습니다.

이것이 작동하는 이유

거의 모든 프레임워크는 OpenAI Chat Completions 형식을 기반으로 구축됩니다:

POST {base_url}/chat/completions
Authorization: Bearer <key>

이 호출을 OpenAI로 라우팅하는 유일한 두 가지 요소는 base URL과 **키 (key)**입니다. base URL을 호환 가능한 게이트웨이로 변경하면, 동일한 오케스트레이션 코드가 이제 다른 백엔드에서 실행됩니다. 프레임워크들은 이를 base_url, api_base, api_base_url 등 약간씩 다른 이름으로 노출하지만, 개념은 동일합니다.

코드 스니펫을 보기 전 두 가지 보편적인 규칙:

• 모델 ID (Model ids)는 계정 범위(account-scoped)입니다. 블로그 포스트에서 ID를 복사하지 마세요. curl {base_url}/models -H "Authorization: Bearer $KEY"를 사용하여 본인의 모델 목록을 확인하고 정확한 ID를 사용하세요.
• 키는 환경 변수 (env vars)에 넣으세요. 절대 하드코딩하지 마세요. 아래의 모든 스니펫은 환경 변수로부터 값을 읽어옵니다.

메커니즘별로 그룹화된 11개 프레임워크

A) base_url 파라미터가 직접 있는 프레임워크

LangChain (+ LangGraph) — 가장 큰 생태계이므로 여기서부터 시작하세요:

from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="MODEL_ID", base_url="https://daoxe.com/v1", api_key="...")  # 키는 환경 변수를 통해 전달
print(llm.invoke("ping").content)
...

주의 사항 (Gotcha): ChatOpenAI는 공식 OpenAI 스펙을 대상으로 합니다. 일부 프록시(proxy)가 추가하는 비표준 필드는 보존되지 않습니다. 표준 응답에는 문제가 없습니다.

AutoGen (Microsoft AgentChat):

from autogen_agentchat.agents import AssistantAgent
from autogen_core.models import ModelInfo
from autogen_ext.models.openai import OpenAIChatCompletionClient
...

주의 사항 (Gotcha): OpenAI가 아닌 모델 ID를 사용할 때는 base_url과 model_info (기능 플래그)가 모두 필요합니다. model_info를 생략하면 오류가 발생합니다. 플래그를 사용 중인 모델 ID의 기능과 일치하도록 설정하세요.

smolagents (Hugging Face):

from smolagents import CodeAgent, OpenAIModel
model = OpenAIModel(model_id="MODEL_ID", api_base="https://daoxe.com/v1", api_key="...")
print(CodeAgent(tools=[], model=model).run("ping"))

주의 사항 (Gotcha): 1.9 버전 이전에는 클래스 이름이 OpenAIServerModel이었습니다 (파라미터는 동일). base_url이 아닌 api_base를 사용합니다.

Haystack (deepset):

from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.utils import Secret
...

주의 사항 (Gotcha): 파라미터 이름이 api_base_url입니다 (단어 하나가 추가됨에 유의). 키는 Secret.from_env_var(...)를 통해 전달됩니다.

Agno (구 phidata):

from agno.agent import Agent
from agno.models.openai.like import OpenAILike
Agent(model=OpenAILike(id="MODEL_ID", base_url="https://daoxe.com/v1", api_key="...")).print_response("ping")

주의 사항 (Gotcha): 제3자 엔드포인트(third-party endpoint)를 사용할 때는 일반 OpenAIChat이 아닌 OpenAILike (agno.models.openai.like에서 가져옴)를 사용하세요.

B) 명시적인 프로바이더(provider) 객체가 있는 프레임워크

PydanticAI — 타입 안전(type-safe) 에이전트:

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider
...

Gotcha: 일반적인 OpenAIProvider를 구축하여 OpenAIChatModel에 전달하세요 — 이는 문서에서 모든 OpenAI 호환 프로바이더에 사용하는 패턴과 동일합니다.

LlamaIndex:

from llama_index.llms.openai_like import OpenAILike  # pip install llama-index-llms-openai-like

llm = OpenAILike(model="MODEL_ID", api_base="https://daoxe.com/v1", api_key="...",
...

Gotcha: **is_chat_model=True**를 설정하지 않으면 /chat/completions 대신 /completions 엔드포인트를 호출합니다. 또한 실제 context_window도 설정하세요.

C) LiteLLM을 통해 라우팅하는 프레임워크 ( openai/ 접두사 필요)

CrewAI:

from crewai import LLM, Agent, Crew, Task
llm = LLM(model="openai/MODEL_ID", base_url="https://daoxe.com/v1", api_key="...")
agent = Agent(role="Greeter", goal="Greet briefly.", backstory="Concise.", llm=llm)
...

Gotcha: 모델 ID에 openai/ 접두사를 유지하세요. 이 접두사가 없으면 CrewAI (LiteLLM 경유)가 익숙한 모델 이름의 네이티브 프로바이더 클라이언트를 일치시켜 base_url을 무시할 수 있으며,

왜 하나의 엔드포인트가 여러 키를 관리하는 것보다 나은가

멀티 에이전트 오케스트레이션 (Multi-agent orchestration)은 모델 확산 (model sprawl)으로 인해 가장 큰 고통을 받는 영역입니다. 강력한 모델을 사용하는 플래너 (planner), 저렴한 모델을 사용하는 워커 (worker), 그리고 세 번째 모델을 사용하는 크리틱 (critic) — 이는 세 개의 벤더, 세 개의 키, 세 개의 청구서, 그리고 세 가지의 실패 모드 (failure modes)를 의미합니다. 이 모든 것을 하나의 OpenAI 호환 엔드포인트 (OpenAI-compatible endpoint)로 지정한다는 것은 다음을 의미합니다:

• 모든 프레임워크와 모든 에이전트 역할에 대해 하나의 키, 하나의 청구서를 사용합니다.
• 모델 선택이 새로운 통합 (integration) 과정이 아닌 단순한 문자열 (string) 처리가 됩니다. MODEL_ID만 바꾸면 동일한 에이전트가 Claude, GPT 또는 Gemini에서 실행됩니다.
• 특정 프레임워크에 종속되지 않습니다. 동일한 키로 11개 프레임워크 모두에서 동일한 작업을 수행할 수 있습니다.

또한 표준 엔드포인트이기 때문에, 단순히 믿는 대신 **검증 (verify)**할 수 있습니다. 엔드포인트에 프로브 (probe)를 실행하여 공식 API와 비교해 볼 수 있습니다 (모델이 몰래 교체되는 것을 잡아내는 방법에 대해서는 별도의 글을 작성했습니다).

저는 이를 위해 daoxe 엔드포인트를 사용합니다: https://daoxe.com/v1에서 OpenAI 호환 기능을 제공하며, Claude 네이티브 도구를 위한 네이티브 Anthropic Messages도 지원하여 하나의 키로 여러 모델을 사용할 수 있습니다. 중국 본토에서는 사용할 수 없습니다. 하지만 이 글의 핵심은 위의 어떤 코드도 daoxe에 특화된 것이 아니라는 점입니다. 여러분이 신뢰하는 어떤 호환 엔드포인트로든 지정하여 사용하십시오.

요약 (TL;DR)

• 여기서 소개된 모든 프레임워크는 커스텀 OpenAI 호환 엔드포인트를 네이티브하게 지원하며, 단 한 줄의 코드로 설정 가능합니다.
• 파라미터 이름 (base_url vs api_base vs api_base_url)과 프레임워크별 주의 사항을 확인하세요.
• CrewAI/DSPy는 openai/ 접두사가 필요하며, AutoGen은 model_info가 필요하고, LlamaIndex는 is_chat_model=True가 필요합니다.
• 하나의 키, 하나의 청구서, 문자열로 결정하는 모델 선택 — 그리고 백엔드를 신뢰하는 대신 직접 검증할 수 있습니다.