模型

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_DEFAULT_MODEL 环境变量。

export OPENAI_DEFAULT_MODEL=gpt-5.2
python3 my_awesome_agent.py

其次，你可以通过 RunConfig 为一次运行设置默认模型。如果你未为某个智能体设置模型，将使用该次运行的模型。

from agents import Agent, RunConfig, Runner

agent = Agent(
    name="Assistant",
    instructions="You're a helpful agent.",
)

result = await Runner.run(
    agent,
    "Hello",
    run_config=RunConfig(model="gpt-5.2"),
)

GPT-5.x 模型

当你以这种方式使用任意 GPT-5.x 模型（例如 gpt-5.2）时，SDK 会应用默认的 ModelSettings。它会设置对大多数用例效果最佳的选项。要调整默认模型的推理努力（reasoning effort），请传入你自己的 ModelSettings：

from openai.types.shared import Reasoning
from agents import Agent, ModelSettings

my_agent = Agent(
    name="My Agent",
    instructions="You're a helpful agent.",
    # If OPENAI_DEFAULT_MODEL=gpt-5.2 is set, passing only model_settings works.
    # It's also fine to pass a GPT-5.x model name explicitly:
    model="gpt-5.2",
    model_settings=ModelSettings(reasoning=Reasoning(effort="high"), verbosity="low")
)

为了更低延迟，建议在 gpt-5.2 上使用 reasoning.effort="none"。gpt-4.1 系列（包括 mini 与 nano 变体）也仍然是构建交互式智能体应用的稳健选择。

非 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 适用于你希望全局使用 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 key 的情况下，我们建议通过 set_tracing_disabled() 禁用追踪，或设置一个不同的追踪进程。

Note

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

模型混合与匹配

在单个工作流中，你可能希望为每个智能体使用不同模型。例如，你可以用更小、更快的模型做分流（triage），同时用更大、更强的模型处理复杂任务。在配置 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 key。你有三种解决方案：

完全禁用追踪：set_tracing_disabled(True)。
为追踪设置 OpenAI key：set_tracing_export_api_key(...)。该 API key 仅用于上传追踪，并且必须来自 platform.openai.com。
使用非 OpenAI 的追踪处理器。参见追踪文档。

Responses API 支持

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

调用 set_default_openai_api("chat_completions")。当你通过环境变量设置 OPENAI_API_KEY 与 OPENAI_BASE_URL 时，这种方式可用。
使用 OpenAIChatCompletionsModel。示例见此处。

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、多模态输入，以及由OpenAI托管的工具文件检索与网络检索，但许多其他提供商不支持这些功能。请注意以下限制：

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