モデル
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 の reasoning モデル(gpt-5、gpt-5-mini、gpt-5-nano)を使用する場合、SDK は既定で妥当な ModelSettings を適用します。具体的には、reasoning.effort と verbosity の両方を "low" に設定します。これらの設定を自分で構成したい場合は、agents.models.get_default_model_settings("gpt-5") を呼び出してください。
より低レイテンシや特定の要件のために、別のモデルや設定を選択できます。デフォルトモデルの reasoning 努力度を調整するには、独自の 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" の reasoning 努力度をサポートしていません。そのため、この 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
これらの例では Chat Completions API/モデルを使用しています。これは、多くの LLM プロバイダーがまだ Responses API をサポートしていないためです。LLM プロバイダーがサポートしている場合は、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 schema 出力をサポートするプロバイダーを利用することをおすすめします。そうでない場合、不正な JSON によりアプリが頻繁に壊れてしまいます。
プロバイダー間でのモデルの組み合わせ
モデルプロバイダー間の機能差に注意しないと、エラーが発生する可能性があります。例えば、OpenAI は structured outputs、マルチモーダル入力、ホスト型のファイル検索と Web 検索をサポートしますが、多くの他社プロバイダーはこれらの機能をサポートしていません。次の制限に注意してください。
- サポートされていない
toolsを理解しないプロバイダーに送らないでください - テキスト専用のモデルを呼び出す前に、マルチモーダル入力を除外してください
- structured JSON 出力をサポートしないプロバイダーは、無効な JSON を出力することがあります