模型

Agents SDK 默认支持两种形式的 OpenAI 模型

推荐：OpenAIResponsesModel，它使用新的 Responses API 调用 OpenAI API。
OpenAIChatCompletionsModel，它使用 Chat Completions API 调用 OpenAI API。

OpenAI 模型

当您在初始化 Agent 时没有指定模型时，将使用默认模型。目前，默认模型是 gpt-4.1，以实现兼容性和低延迟。如果您有权限，我们建议将您的代理设置为 gpt-5.2，以获得更高的质量，同时保持明确的 model_settings。

如果您想切换到其他模型，如 gpt-5.2，请按照下一节中的步骤操作。

默认 OpenAI 模型

如果您希望始终为未设置自定义模型的代理使用特定模型，请在运行代理之前设置 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 集成使用大多数其他非 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 模型的其他方法

您可以通过 3 种其他方式集成其他 LLM 提供商（示例此处）

set_default_openai_client 在您希望全局使用 LLM 提供商的 AsyncOpenAI 实例作为 LLM 客户端的情况下很有用。这适用于 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() 禁用追踪，或设置不同的追踪处理器。

注意

在这些示例中，我们使用 Chat Completions API/模型，因为大多数 LLM 提供商尚未支持 Responses API。如果您的 LLM 提供商支持它，我们建议使用 Responses。

混合搭配模型

在单个工作流程中，您可能希望为每个代理使用不同的模型。例如，您可以使用较小、较快的模型进行分类，同时使用较大、功能更强大的模型来执行复杂任务。在配置 Agent 时，您可以选择特定的模型，方法是

传递模型名称。
传递任何模型名称 + 一个 ModelProvider，它可以将该名称映射到 Model 实例。
直接提供一个 Model 实现。

注意

虽然我们的 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，它提供可选的模型配置参数，例如温度。

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 密钥。您有三种选择来解决此问题

完全禁用追踪：set_tracing_disabled(True)。
设置用于追踪的 OpenAI 密钥：set_tracing_export_api_key(...)。此 API 密钥仅用于上传追踪，必须来自 platform.openai.com。
使用非 OpenAI 追踪处理器。请参阅追踪文档。

Responses API 支持

SDK 默认使用 Responses API，但大多数其他 LLM 提供商尚未支持它。您可能会看到 404 或类似问题。要解决，您有两个选择

调用 set_default_openai_api("chat_completions")。如果通过环境变量设置 OPENAI_API_KEY 和 OPENAI_BASE_URL，则此方法有效。
使用 OpenAIChatCompletionsModel。示例此处。

结构化输出支持

某些模型提供商不支持结构化输出。这有时会导致类似于以下内容的错误

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 支持结构化输出、多模态输入以及托管的文件搜索和网络搜索，但许多其他提供商不支持这些功能。请注意这些限制

不要将不受支持的 tools 发送到不理解它们的提供商
在调用仅支持文本的模型之前，过滤掉多模态输入
请注意，不支持结构化 JSON 输出的提供商偶尔会生成无效的 JSON。