モデル
Agents SDK には、OpenAI モデルに対する標準サポートが 2 種類用意されています。
- 推奨:
OpenAIResponsesModel
。新しい Responses API を使用して OpenAI API を呼び出します。 OpenAIChatCompletionsModel
。 Chat Completions API を使用して OpenAI API を呼び出します。
OpenAI モデル
Agent
を初期化するときにモデルを指定しない場合は、デフォルトのモデルが使用されます。現在のデフォルトは gpt-4.1
で、エージェント ワークフローにおける予測可能性と低レイテンシのバランスに優れています。
gpt-5
など他のモデルに切り替える場合は、次のセクションの手順に従ってください。
既定の OpenAI モデル
カスタムモデルを設定していないすべての エージェント で特定のモデルを常に使用したい場合は、エージェントを実行する前に OPENAI_DEFAULT_MODEL
環境変数を設定してください。
GPT-5 モデル
この方法で GPT-5 の推論モデル(gpt-5
、gpt-5-mini
、または gpt-5-nano
)を使用する場合、SDK は既定で妥当な ModelSettings
を適用します。具体的には、reasoning.effort
と verbosity
の両方を "low"
に設定します。これらの設定を自分で構築したい場合は、agents.models.get_default_model_settings("gpt-5")
を呼び出してください。
より低レイテンシや特定の要件がある場合は、別のモデルと設定を選択できます。デフォルトモデルの推論負荷を調整するには、独自の ModelSettings
を渡します。
from openai.types.shared import Reasoning
from agents import Agent, ModelSettings
my_agent = Agent(
name="My Agent",
instructions="You're a helpful agent.",
model_settings=ModelSettings(reasoning=Reasoning(effort="minimal"), verbosity="low")
# If OPENAI_DEFAULT_MODEL=gpt-5 is set, passing only model_settings works.
# It's also fine to pass a GPT-5 model name explicitly:
# model="gpt-5",
)
特にレイテンシを下げたい場合は、gpt-5-mini
または gpt-5-nano
モデルに reasoning.effort="minimal"
を指定することで、デフォルト設定よりも高速に応答が返ることが多いです。ただし、Responses API の一部の内蔵ツール(たとえば ファイル検索 や画像生成)は "minimal"
の推論負荷をサポートしていないため、本 Agents SDK では "low"
をデフォルトにしています。
非 GPT-5 モデル
カスタムの model_settings
を指定せずに GPT-5 以外のモデル名を渡した場合、SDK はあらゆるモデルで互換性のある汎用的な ModelSettings
にフォールバックします。
非 OpenAI モデル
LiteLLM 連携 を通じて、ほとんどの非 OpenAI モデルを使用できます。まず、litellm の依存関係グループをインストールします。
次に、litellm/
プレフィックスを付けて サポートされているモデル を使用します。
claude_agent = Agent(model="litellm/anthropic/claude-3-5-sonnet-20240620", ...)
gemini_agent = Agent(model="litellm/gemini/gemini-2.5-flash-preview-04-17", ...)
非 OpenAI モデルを使う他の方法
他の LLM プロバイダを統合する方法はさらに 3 つあります(code examples はこちら)。
set_default_openai_client
は、LLM クライアントとしてAsyncOpenAI
のインスタンスをグローバルに使用したい場合に便利です。これは、LLM プロバイダが OpenAI 互換の API エンドポイントを持ち、base_url
とapi_key
を設定できるケース向けです。設定可能なサンプルは examples/model_providers/custom_example_global.py を参照してください。ModelProvider
はRunner.run
レベルです。これにより、「この実行のすべての エージェント にカスタムのモデルプロバイダを使う」と指定できます。設定可能なサンプルは examples/model_providers/custom_example_provider.py を参照してください。Agent.model
では、特定の Agent インスタンスでモデルを指定できます。これにより、エージェント ごとに異なるプロバイダを組み合わせて使えます。設定可能なサンプルは examples/model_providers/custom_example_agent.py を参照してください。利用可能なほとんどのモデルを簡単に使う方法としては、LiteLLM 連携 を利用するのが簡単です。
platform.openai.com
の API キーがない場合は、set_tracing_disabled()
で トレーシング を無効化するか、別の トレーシング プロセッサー を設定することをおすすめします。
Note
これらの code examples では、Responses API をサポートしていない LLM プロバイダが多いため、Chat Completions API/モデルを使用しています。使用している LLM プロバイダが Responses をサポートしている場合は、Responses の使用を推奨します。
モデルの組み合わせ
単一のワークフロー内で、エージェント ごとに異なるモデルを使いたい場合があります。例えば、トリアージには小型で高速なモデルを使い、複雑なタスクには大型で高性能なモデルを使う、といった使い分けです。Agent
を設定する際、次のいずれかの方法で特定のモデルを選べます。
- モデル名を渡す。
- 任意のモデル名と、その名前を Model インスタンスにマッピングできる
ModelProvider
を渡す。 Model
実装を直接渡す。
Note
SDK は OpenAIResponsesModel
と OpenAIChatCompletionsModel
の両方の形状をサポートしますが、両者はサポートする機能やツールが異なるため、各ワークフローでは単一のモデル形状の使用を推奨します。ワークフローでモデル形状を混在させる必要がある場合は、使用するすべての機能が両方で利用可能であることを確認してください。
from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel
import asyncio
spanish_agent = Agent(
name="Spanish agent",
instructions="You only speak Spanish.",
model="gpt-5-mini", # (1)!
)
english_agent = Agent(
name="English agent",
instructions="You only speak English",
model=OpenAIChatCompletionsModel( # (2)!
model="gpt-5-nano",
openai_client=AsyncOpenAI()
),
)
triage_agent = Agent(
name="Triage agent",
instructions="Handoff to the appropriate agent based on the language of the request.",
handoffs=[spanish_agent, english_agent],
model="gpt-5",
)
async def main():
result = await Runner.run(triage_agent, input="Hola, ¿cómo estás?")
print(result.final_output)
- OpenAI のモデル名を直接設定します。
Model
実装を提供します。
エージェント に使用するモデルをさらに構成したい場合は、ModelSettings
を渡せます。これは、temperature などのオプションのモデル構成パラメーターを提供します。
from agents import Agent, ModelSettings
english_agent = Agent(
name="English agent",
instructions="You only speak English",
model="gpt-4.1",
model_settings=ModelSettings(temperature=0.1),
)
また、OpenAI の Responses API を使用する場合、他にもいくつかの任意パラメーター(例: user
、service_tier
など)があります。トップレベルで指定できない場合は、extra_args
を使って渡せます。
from agents import Agent, ModelSettings
english_agent = Agent(
name="English agent",
instructions="You only speak English",
model="gpt-4.1",
model_settings=ModelSettings(
temperature=0.1,
extra_args={"service_tier": "flex", "user": "user_12345"},
),
)
他社 LLM プロバイダ使用時のよくある問題
トレーシング クライアントのエラー 401
トレーシング に関連するエラーが出る場合、トレースは OpenAI の サーバー にアップロードされ、OpenAI の API キーを持っていないことが原因です。次の 3 つの方法で解決できます。
- トレーシング を完全に無効化する:
set_tracing_disabled(True)
。 - トレーシング 用の OpenAI キーを設定する:
set_tracing_export_api_key(...)
。この API キーはトレースのアップロードにのみ使用され、platform.openai.com のキーである必要があります。 - 非 OpenAI のトレース プロセッサーを使用する。トレーシング ドキュメント を参照してください。
Responses API のサポート
SDK はデフォルトで Responses API を使用しますが、他の多くの LLM プロバイダはまだサポートしていません。その結果、404 などの問題が発生する場合があります。解決方法は次の 2 つです。
set_default_openai_api("chat_completions")
を呼び出す。これは環境変数でOPENAI_API_KEY
とOPENAI_BASE_URL
を設定している場合に機能します。OpenAIChatCompletionsModel
を使用する。code examples はこちら。
Structured outputs のサポート
一部のモデルプロバイダは structured outputs をサポートしていません。その結果、次のようなエラーになることがあります。
BadRequestError: Error code: 400 - {'error': {'message': "'response_format.type' : value is not one of the allowed values ['text','json_object']", 'type': 'invalid_request_error'}}
これは一部のモデルプロバイダ側の制約で、JSON 出力はサポートしていても、出力に使用する json_schema
を指定できない場合があります。現在この点については改善に取り組んでいますが、JSON スキーマ出力をサポートするプロバイダに依存することをおすすめします。そうでない場合、不正な JSON によりアプリが頻繁に壊れてしまう可能性があります。
プロバイダをまたいだモデルの混在
モデルプロバイダ間の機能差に注意しないと、エラーが発生する可能性があります。例えば、OpenAI は structured outputs、マルチモーダル入力、ホスト型の ファイル検索 と Web 検索 をサポートしていますが、他の多くのプロバイダはこれらの機能をサポートしていません。以下の制約に注意してください。
- サポートされていない
tools
を理解しないプロバイダに送信しない - テキストのみのモデルを呼び出す前に、マルチモーダル入力を除外する
- structured JSON 出力をサポートしていないプロバイダは、不正な JSON を生成することがある点に注意する