模型

Agents SDK 內建支援兩種 OpenAI 模型：

推薦： [OpenAIResponsesModel][agents.models.openai_responses.OpenAIResponsesModel]，透過全新的 Responses API 呼叫 OpenAI API。
[OpenAIChatCompletionsModel][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]，使用 Chat Completions API 呼叫 OpenAI API。

OpenAI 模型

當你在初始化 Agent 時未指定模型，將會使用預設模型。目前的預設為 gpt-4.1，此模型在代理（Agent）工作流程的可預測性與低延遲之間提供了良好的平衡。

如果你想切換至其他模型，例如 gpt-5，請參考下一節的步驟。

預設 OpenAI 模型

若你希望所有未自訂模型的代理（Agent）都一致使用特定模型，請在執行代理（Agent）前設定 OPENAI_DEFAULT_MODEL 環境變數。

export OPENAI_DEFAULT_MODEL=gpt-5
python3 my_awesome_agent.py

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 模型

如果你傳入非 GPT-5 的模型名稱且未自訂 model_settings，SDK 會回退至通用的 ModelSettings，可相容於任何模型。

非 OpenAI 模型

你可以透過 LiteLLM integration 使用大多數其他非 OpenAI 的模型。首先，請安裝 litellm 相依套件組：

pip install "openai-agents[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) 提供者（範例請見這裡）：

[set_default_openai_client][agents.set_default_openai_client] 適用於你希望全域使用某個 AsyncOpenAI 實例作為 LLM 用戶端的情境。這適用於 LLM 提供者有 OpenAI 相容 API 端點，且你可以設定 base_url 與 api_key。可參考 examples/model_providers/custom_example_global.py 中的可設定範例。
[ModelProvider][agents.models.interface.ModelProvider] 屬於 Runner.run 層級。這讓你可以指定「本次執行所有代理 (Agents) 都使用自訂的模型提供者」。可參考 examples/model_providers/custom_example_provider.py 中的可設定範例。
[Agent.model][agents.agent.Agent.model] 允許你在特定 Agent 實例上指定模型。這讓你可以為不同代理 (Agents) 混合搭配不同的提供者。可參考 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) 使用不同的模型。例如，你可以為分流（triage）階段選擇較小且速度較快的模型，而在處理複雜任務時則使用更大型、功能更強的模型。當你設定一個 [Agent][agents.Agent] 時，可以透過以下方式選擇特定模型：

傳入模型名稱。
傳入任意模型名稱加上一個 [ModelProvider][agents.models.interface.ModelProvider]，該提供者可以將名稱對應到一個 Model 實例。
直接提供一個 [Model][agents.models.interface.Model] 的實作。

Note

While our SDK supports both the [OpenAIResponsesModel][agents.models.openai_responses.OpenAIResponsesModel] and the [OpenAIChatCompletionsModel][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] shapes, we recommend using a single model shape for each workflow because the two shapes support a different set of features and tools. If your workflow requires mixing and matching model shapes, make sure that all the features you're using are available on both.

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][agents.models.interface.Model] 實作。

當你想要進一步設定代理 (Agent) 所使用的模型時，可以傳入 [ModelSettings][agents.models.interface.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) 提供者時的常見問題

Tracing 用戶端錯誤 401

如果你遇到與 tracing 相關的錯誤，這通常是因為 traces 會上傳到 OpenAI 伺服器，而你沒有 OpenAI API 金鑰。你有三種解決方式：

完全停用 tracing：[set_tracing_disabled(True)][agents.set_tracing_disabled]。
設定一組用於 tracing 的 OpenAI API 金鑰：[set_tracing_export_api_key(...)][agents.set_tracing_export_api_key]。這組 API 金鑰僅用於上傳 traces，必須來自 platform.openai.com。
使用非 OpenAI 的 trace 處理器。請參閱 tracing docs。

Responses API 支援

SDK 預設會使用 Responses API，但大多數其他大型語言模型 (LLM) 提供者尚未支援該 API。因此你可能會看到 404 或類似的錯誤。你有兩種解決方式：

呼叫 [set_default_openai_api("chat_completions")][agents.set_default_openai_api]。如果你是透過環境變數設定 OPENAI_API_KEY 和 OPENAI_BASE_URL，這個方法有效。
使用 [OpenAIChatCompletionsModel][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。相關範例請參考 here。

結構化輸出支援

部分模型提供者尚未支援 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 支援結構化輸出、多模態輸入，以及託管檔案搜尋和網頁搜尋，但許多其他提供者並不支援這些功能。請注意以下限制：

不要將不受支援的 tools 傳送給無法識別的提供者
在呼叫僅支援文字的模型前，先過濾掉多模態輸入
請注意，不支援結構化 JSON 輸出的提供者有時會產生無效的 JSON。