openai-agents-python/docs/zh/models/index.md
2026-11-10 07:54:51 +00:00

50 KiB
Raw Permalink Blame History

search
exclude
true

模型

Agents SDK 原生支持两种形式的OpenAI模型:

  • 推荐:[OpenAIResponsesModel][agents.models.openai_responses.OpenAIResponsesModel],使用新的 Responses API 调用OpenAI API。
  • [OpenAIChatCompletionsModel][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel],使用 Chat Completions API 调用OpenAI API。

Decisions API

在智能体运行过程中,可使用 OpenAI Decisions API 进行分类。直接调用 AsyncOpenAI.decisions.create(),然后在现有的 Agents SDK 安全防护措施、审批回调或模型选择步骤中使用答案。Decisions 不实现 Agents SDK 的 Model 接口。

安装 openai>=3.26.0,<4 以使用原生 Decisions 客户端。仅满足 Agents SDK 的最低依赖版本并不能保证 Decisions 资源可用。请显式配置原生客户端,包括任何自定义凭据或基础 URL;set_default_openai_client() 等 Agents SDK 默认设置不会配置单独构造的 AsyncOpenAI 实例。

可运行的 Decisions 代码示例展示了三种工作流:

工作流 现有 SDK API 应用程序职责
检查初始请求 @input_guardrail(run_in_parallel=False) 选择谓词和阈值;在智能体启动前处理拒绝。
审查函数工具内容 @tool_input_guardrail 或可调用的 needs_approval 定义内容策略,并选择拒绝调用还是请求人工审批。
运行前选择模型 agent.clone(model=...) 将选择答案映射到允许的模型,并选择拒绝时的后备方案。

按名称读取答案

Decisions 请求可以包含谓词、选择和评分问题。原生响应包含一个 answers 列表。按问题名称为答案建立索引,然后在读取每个答案的类型特定字段之前,检查其 type:

from openai import AsyncOpenAI


async def is_support_request(client: AsyncOpenAI, text: str) -> bool:
    decision = await client.decisions.create(
        model="gpt-6-luna",
        input=text,
        questions=[
            {
                "type": "predicate",
                "name": "in_scope",
                "instructions": "Is this a request for help with a software product?",
            }
        ],
    )
    answers = {answer.name: answer for answer in decision.answers}
    answer = answers.get("in_scope")
    if answer is None or answer.type != "predicate":
        return False
    return answer.probability >= 0.8

上述阈值仅作示例。请使用应用程序中的已标注示例选择阈值。拒绝仅适用于一个问题;同一响应中的另一个问题仍可返回答案。请分别确定每个工作流如何处理拒绝、缺失答案或 API 错误。代码示例会传播 API 错误,而不是将不可用的分类器视为肯定答案。

集成边界

输入安全防护措施示例接受单个文本请求,并在检查完成前阻止智能体执行。工具示例会评估公告参数,并且仅模拟发布。其分类器实现的是编辑审查策略;它不负责确定用户授权。请在可信的应用程序代码中单独实施权限控制。

对于可调用的 needs_approval,当参数验证需要类型转换、默认值或应用程序定义的验证时,使用装饰器定义的函数工具需要手动审批。在这些情况下,SDK 不会调用条件审批回调。显式批准后,SDK 会恢复调用,而不会再次评估该回调。工具输入安全防护措施属于独立检查,可在调用之前立即再次运行。请参阅人工介入和工具安全防护措施。

运行前路由会选择起始智能体的模型。它不会自动为任务转移选择模型,也不会重新路由恢复后的运行。请自行提供预期的分类依据;这些纯文本方案不会检索服务器保存的历史记录,也不会将任意对话项和附件转换为 Decisions 输入。

直接调用 Decisions 不经过 Runner 的模型适配器。其用量信息可在原生响应中获取,并且不会自动包含在 RunResult.context_wrapper.usage 或 Agents SDK 生成跨度中。请像代码示例一样,使用 async with AsyncOpenAI() as client 管理原生客户端的生命周期。

模型配置选择

从符合您配置需求的最简单方案开始:

如果您希望…… 推荐方案 更多信息
仅使用OpenAI模型 使用默认OpenAI提供商和 Responses 模型路径 OpenAI模型
通过 WebSocket 传输使用 OpenAI Responses API 保留 Responses 模型路径并启用 WebSocket 传输 Responses WebSocket 传输
使用由OpenAI托管的子智能体 使用实验性托管多智能体模型 托管多智能体
使用一个非OpenAI提供商 从内置提供商集成点开始 非OpenAI模型
在不同智能体之间混用模型或提供商 按运行或按智能体选择提供商,并查看功能差异 在一个工作流中混用模型和跨提供商混用模型
调整高级 OpenAI Responses 请求设置 在 OpenAI Responses 路径上使用 ModelSettings 高级 OpenAI Responses 设置
使用第三方适配器进行非OpenAI或混合提供商路由 比较受支持的测试版适配器,并验证您计划发布的提供商路径 第三方适配器

OpenAI模型

对于大多数仅使用OpenAI的应用,推荐使用默认OpenAI提供商中的字符串模型名称,并继续使用 Responses 模型路径。

当 [Agent][agents.agent.Agent] 未指定模型时,Agents SDK 默认使用 gpt-5.6-luna,并采用 reasoning.effort="none" 和 verbosity="low",适用于成本敏感、高吞吐量的智能体工作流。需要前沿能力的应用程序可以显式设置 model="gpt-5.6-sol",并选择适合工作负载的 model_settings。

如果要切换到 gpt-5.6-sol 等其他模型,有两种方式可以配置智能体。

默认模型

首先,如果您希望所有未设置自定义模型的智能体始终使用特定模型,请在运行智能体之前设置 OPENAI_DEFAULT_MODEL 环境变量。

export OPENAI_DEFAULT_MODEL=gpt-5.6-sol
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.6-sol"),
)

GPT-5 模型

以这种方式使用任何 GPT-5 模型(例如 gpt-5.6-sol)时,SDK 会应用默认的 ModelSettings。其中设置了最适合大多数用例的值。如需调整默认模型的推理强度,请传入您自己的 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.6-sol is set, passing only model_settings works.
    # It's also fine to pass a GPT-5 model name explicitly:
    model="gpt-5.6-sol",
    model_settings=ModelSettings(reasoning=Reasoning(effort="high"), verbosity="low"),
)

如需降低延迟,建议将 GPT-5 模型与 reasoning.effort="none" 搭配使用。

GPT-5.6 还通过现有的 reasoning 设置支持推理模式、跨对话轮次保留的推理上下文,以及 "max" 强度级别。这些控制项可在 Responses API 路径上使用:

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

agent = Agent(
    name="Deep research agent",
    model="gpt-5.6-sol",
    model_settings=ModelSettings(
        reasoning=Reasoning(
            mode="pro",
            effort="max",
            context="all_turns",
        ),
    ),
)

reasoning.mode 和 reasoning.context 是仅限 Responses 的设置。Chat Completions 仅使用 reasoning.effort,支持的强度级别取决于模型和 API 接口。请使用 Responses API 设置 GPT-5.6 的 "max" 强度。Chat Completions 适配器会忽略模式和上下文并发出警告;在OpenAI提供商上设置 strict_feature_validation=True 可将该警告转为错误。

使用 context="all_turns" 时,请通过 previous_response_id、服务器端 Responses API 对话,或在下一个请求中包含之前的推理项来保留对话。对于无状态的 store=False 调用,请在响应中请求 reasoning.encrypted_content,然后在下一个请求中将这些推理项作为输入包含在内。

ComputerTool 模型选择

如果智能体包含 [ComputerTool][agents.tool.ComputerTool],则实际 Responses 请求上的有效模型决定 SDK 发送哪种计算机工具负载。当智能体未设置 model 时,将应用正常的 SDK 模型选择优先级。SDK 当前内置的默认模型 gpt-5.6-luna 支持正式发布的内置 computer 工具。如果 OPENAI_DEFAULT_MODEL 或 RunConfig.model 覆盖了该默认值,请选择支持计算机操作的模型。如果希望为计算机操作工作负载选择不同的能力和成本配置,请在智能体上设置 model;例如,model="gpt-5.6" 使用由OpenAI路由至 GPT-5.6 Sol 的别名。显式的 computer-use-preview 请求仍使用较旧的 computer_use_preview 负载。

由提示词管理的调用是主要例外。如果提示词模板指定了模型,而 SDK 从请求中省略了 model,SDK 会默认使用与预览版兼容的计算机负载,以免猜测提示词固定了哪个模型。要在此流程中继续使用正式发布路径,可以在请求中显式指定受支持的正式发布模型(例如 model="gpt-5.6"),或者使用 ModelSettings(tool_choice="computer") 或 ModelSettings(tool_choice="computer_use") 强制选择正式发布版本。

注册 [ComputerTool][agents.tool.ComputerTool] 后,tool_choice="computer"、"computer_use" 和 "computer_use_preview" 会被规范化为与有效请求模型匹配的内置选择器。如果未注册 ComputerTool,这些字符串会继续像普通函数名称一样工作。

与预览版兼容的请求必须预先序列化 environment 和显示尺寸,因此,使用 [ComputerProvider][agents.tool.ComputerProvider] 工厂的提示词管理流程应传入具体的 Computer 或 AsyncComputer 实例,或者在发送请求前强制使用正式发布选择器。有关完整迁移详情,请参阅工具。

非 GPT-5 模型

如果传入非 GPT-5 模型名称且没有自定义 model_settings,SDK 会恢复为与任何模型兼容的通用 ModelSettings。

仅限 Responses 的工具功能

以下工具功能仅受 OpenAI Responses 模型支持:

  • [ToolSearchTool][agents.tool.ToolSearchTool]
  • [tool_namespace()][agents.tool.tool_namespace]
  • @function_tool(defer_loading=True) 及其他延迟加载的 Responses 工具接口
  • [ProgrammaticToolCallingTool][agents.tool.ProgrammaticToolCallingTool]、allowed_callers 和 tool_choice="programmatic_tool_calling"

Chat Completions 模型和非 Responses 后端会拒绝这些功能。使用延迟加载工具时,请将 ToolSearchTool() 添加到智能体,并让模型通过 auto 或 required 工具选项加载工具,而不要强制使用裸命名空间名称或仅限延迟加载的函数名称。有关配置详情和当前限制,请参阅托管工具检索和程序化工具调用。

Responses WebSocket 传输

默认情况下,OpenAI Responses API 请求使用 HTTP 传输。使用 OpenAI Responses 提供商路径时,可以选择启用 WebSocket 传输。

基本配置

from agents import set_default_openai_responses_transport

set_default_openai_responses_transport("websocket")

这会影响默认OpenAI提供商解析模型名称时产生的 OpenAI Responses 模型,包括 "gpt-5.6-sol" 等字符串模型名称。

SDK 将模型名称解析为模型实例时会选择传输方式。如果传入具体的 [Model][agents.models.interface.Model] 对象,其传输方式已固定:[OpenAIResponsesWSModel][agents.models.openai_responses.OpenAIResponsesWSModel] 使用 WebSocket,[OpenAIResponsesModel][agents.models.openai_responses.OpenAIResponsesModel] 使用 HTTP,而 [OpenAIChatCompletionsModel][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 继续使用 Chat Completions。如果传入 RunConfig(model_provider=...),则由该提供商控制传输选择,而不是使用全局默认设置。

提供商级或运行级配置

您也可以按提供商或按运行配置 WebSocket 传输:

from agents import Agent, OpenAIProvider, RunConfig, Runner

provider = OpenAIProvider(
    use_responses_websocket=True,
    # Optional; if omitted, OPENAI_WEBSOCKET_BASE_URL is used when set.
    websocket_base_url="wss://your-proxy.example/v1",
    # Optional low-level websocket keepalive settings.
    responses_websocket_options={"ping_interval": 20.0, "ping_timeout": 60.0},
)

agent = Agent(name="Assistant")
result = await Runner.run(
    agent,
    "Hello",
    run_config=RunConfig(model_provider=provider),
)

通过 SDK 的OpenAI集成进行路由的提供商还接受可选的智能体注册配置。这是一个高级选项,适用于OpenAI配置需要提供商级注册元数据(例如框架 ID)的情况。

from agents import (
    Agent,
    OpenAIAgentRegistrationConfig,
    OpenAIProvider,
    RunConfig,
    Runner,
)

provider = OpenAIProvider(
    use_responses_websocket=True,
    agent_registration=OpenAIAgentRegistrationConfig(harness_id="your-harness-id"),
)

agent = Agent(name="Assistant")
result = await Runner.run(
    agent,
    "Hello",
    run_config=RunConfig(model_provider=provider),
)

使用 MultiProvider 的高级路由

如果需要基于前缀的模型路由,例如在一次运行中混用 openai/... 和 any-llm/... 模型名称,请使用 [MultiProvider][agents.MultiProvider],并在其中设置 openai_use_responses_websocket=True。

MultiProvider 保留了两个历史默认行为:

  • openai/... 被视为OpenAI提供商的别名,因此 openai/gpt-4.1 会作为模型 gpt-4.1 进行路由。
  • 未知前缀会引发 UserError,而不会直接透传。

当您将OpenAI提供商指向要求使用字面命名空间模型 ID 的 OpenAI 兼容端点时,请显式启用透传行为。在启用 WebSocket 的配置中,还应在 MultiProvider 上保留 openai_use_responses_websocket=True:

from agents import Agent, MultiProvider, RunConfig, Runner

provider = MultiProvider(
    openai_base_url="https://openrouter.ai/api/v1",
    openai_api_key="...",
    openai_use_responses_websocket=True,
    openai_prefix_mode="model_id",
    unknown_prefix_mode="model_id",
)

agent = Agent(
    name="Assistant",
    instructions="Be concise.",
    model="openai/gpt-4.1",
)

result = await Runner.run(
    agent,
    "Hello",
    run_config=RunConfig(model_provider=provider),
)

当后端需要字面量 openai/... 字符串时,请使用 openai_prefix_mode="model_id"。当后端需要其他命名空间模型 ID(例如 openrouter/openai/gpt-4.1-mini)时,请使用 unknown_prefix_mode="model_id"。这些选项也适用于 WebSocket 传输之外的 MultiProvider;此示例保持 WebSocket 启用,因为它属于本节介绍的传输配置。相同选项也可用于 [responses_websocket_session()][agents.responses_websocket_session]。

如果通过 MultiProvider 路由时需要相同的提供商级注册元数据,请传入 openai_agent_registration=OpenAIAgentRegistrationConfig(...),它会被转发给底层OpenAI提供商。

如果使用自定义 OpenAI 兼容端点或代理,WebSocket 传输还需要兼容的 WebSocket /responses 端点。在这些配置中,您可能需要显式设置 websocket_base_url。

注意事项

  • 这是通过 WebSocket 传输的 Responses API,而不是 Realtime API。它不适用于 Chat Completions。仅当非OpenAI提供商支持 Responses WebSocket /responses 端点时,才适用于这些提供商。
  • 如果环境中尚未安装 websockets 软件包,请进行安装。
  • 启用 WebSocket 传输后,可以直接使用 [Runner.run_streamed()][agents.run.Runner.run_streamed]。对于希望跨轮次以及嵌套的智能体即工具调用复用同一 WebSocket 连接的多轮工作流,建议使用 [responses_websocket_session()][agents.responses_websocket_session] 辅助工具。请参阅运行智能体指南和 examples/basic/stream_ws.py。
  • 对于耗时较长的推理轮次或延迟波动较大的网络,可使用 responses_websocket_options 自定义 WebSocket 保活行为。增大 ping_timeout 以容忍延迟的 pong 帧,或将 ping_timeout=None 设置为禁用心跳超时,同时继续启用 ping。当可靠性比 WebSocket 延迟更重要时,建议使用 HTTP/SSE 传输。
  • 默认情况下,SDK 会禁用传入消息的大小限制(max_size=None)。对于代理后方的长期运行智能体进程或内存受限容器,请设置 responses_websocket_options={"max_size": 8 * 1024 * 1024} 以限制每条消息的内存用量。
  • Responses API WebSocket 服务在每个连接上一次处理一个响应,并将每个连接限制为 60 分钟。达到该限制后,请打开新连接;需要并行运行时,请使用多个连接。
  • 该服务仅在连接本地内存中保留最近一次响应。失败的 4xx 或 5xx 轮次会从该内存中逐出 previous_response_id 引用的响应。重新连接后,如果已存储的响应仍可用,则仍可继续处理;但 store=False 和 ZDR 流程没有持久化后备方案。请使用 previous_response_id=None 启动新链并发送完整输入上下文,或根据本地管理的会话状态重建该上下文。

托管多智能体(实验性)

OpenAI Responses API 的托管多智能体测试版允许 GPT-5.6 根模型创建并协调服务器托管的子智能体。Agents SDK 可以继续使用常规的 Runner:托管编排保留在服务端,而开发者定义的函数工具在您的应用程序中执行。

此集成为实验性功能,使用 Responses WebSocket 传输,以便通过 response.inject 将本地函数输出返回给活动的托管智能体。它要求使用 openai[realtime] 2.45.0 或更高版本的构建,并且该构建需公开 client.beta.responses.connect。接口和测试版项目架构可能会在正式发布前发生变化。

模型配置

从实验性模块导入模型,并将其分配给 SDK Agent:

from agents import Agent
from agents.extensions.experimental.hosted_multi_agent import OpenAIHostedMultiAgentModel

agent = Agent(
    name="Research coordinator",
    instructions="Delegate independent research tasks, then synthesize the findings.",
    model=OpenAIHostedMultiAgentModel(model="gpt-5.6-sol", config={"max_concurrent_subagents": 3}),
)

构造 OpenAIHostedMultiAgentModel 会启用 multi_agent.enabled 并发送 OpenAI-Beta: responses_multi_agent=v1 WebSocket 标头。除非提供 openai_client,否则模型会使用默认OpenAI客户端。如果省略 max_concurrent_subagents,则使用服务默认值。

本地函数工具

所有托管智能体共享为请求配置的模型和工具。Responses API 决定由哪个托管智能体调用函数。常规 SDK Runner 会在本地执行函数,并将具有相同调用 ID 的 function_call_output 注入活动的 WebSocket 响应,从而让服务恢复原始托管调用方。函数执行仍会经过 Runner 的常规安全防护措施、钩子和失败转换。不支持 SDK 工具审批中断:任何 needs_approval 设置不为 False 的函数工具都会在请求发送前被拒绝。

当工具需要感知调用方的日志记录或授权时,请使用 get_hosted_agent_metadata():

from typing import Any

from agents.decorators import tool
from agents.extensions.experimental.hosted_multi_agent import get_hosted_agent_metadata
from agents.tool_context import ToolContext


@tool
def lookup_document(ctx: ToolContext[Any], section: str) -> str:
    metadata = get_hosted_agent_metadata(ctx)
    caller = metadata.agent_name if metadata else "unknown"
    print(f"tool caller: {caller}; call ID: {ctx.tool_call_id}")
    return f"Contents for {section}"

托管智能体名称是观测元数据,而不是本地路由机制。请使用 SDK 提供的调用 ID 路由输出。对于具有副作用的工具,请将该调用 ID 用作幂等键,并在工具执行前或执行期间于应用程序代码中实施任何必需的授权;不要将 needs_approval 与此模型一起使用。工具参数和输出会跨越 Responses API 边界。

输出和流式传输行为

只有归属于 /root 且阶段为 final_answer 的消息才会成为常规最终消息。实验性适配器会从高级 RunResult 中过滤掉子智能体消息和托管编排记录;SDK 绝不会将这些记录作为本地函数执行。

原始流式传输会继续公开测试版 Responses 事件,包括托管输出项和 response.inject.created 确认。函数调用就绪时,适配器会将一个活动的提供商响应划分为 SDK 可见的逻辑模型轮次,然后在 Runner 生成输出后恢复同一提供商响应。使用 get_hosted_agent_metadata() 和原始托管项或 ToolContext,可以识别项目或工具调用归属于哪个托管智能体。

与 SDK 编排的关系

托管多智能体不同于 SDK 任务转移和 Agents-as-tools:

  • 托管多智能体会在OpenAI服务上创建子智能体。您的应用程序不负责创建或调度这些子智能体。
  • SDK 任务转移会更改当前活动的本地 SDK Agent。使用此实验性模型时会拒绝任务转移,因为每个托管智能体都会收到相同的任务转移工具,从而导致所有权冲突。
  • Agents-as-tools 仍然可用,但使用它们会同时创建嵌套的客户端编排和服务器端编排。请审慎评估额外的延迟、成本和工具暴露。

当前限制

实验性模型会拒绝 reasoning.summary、max_tool_calls,以及调用方提供的 multi_agent 或 betas 覆盖值。测试版不支持 Responses /compact 端点,但可以使用显式的 context_management.compact_threshold,因为服务会自动独立压缩每个托管智能体的上下文。

一个 OpenAIHostedMultiAgentModel 实例同一时间最多拥有一个活动的托管响应。如果运行在等待本地函数输出时被放弃,请调用 await model.close() 释放其 WebSocket。目前不支持在不同进程或事件循环中恢复正在进行的托管响应。

有关底层 Responses API 测试版行为,请参阅 OpenAI 多智能体指南。有关非流式和流式 SDK 用法,请参阅 examples/agent_patterns/hosted_multi_agent_beta.py。

非OpenAI模型

如果需要非OpenAI提供商,请从 SDK 的内置提供商集成点开始。对于许多配置,无需添加第三方适配器即可满足需求。每种模式的代码示例都位于 examples/model_providers。

非OpenAI提供商集成方式

方法 适用场景 作用范围
[set_default_openai_client][agents.set_default_openai_client] 一个 OpenAI 兼容端点应作为大多数或所有智能体的默认端点 全局默认
[ModelProvider][agents.models.interface.ModelProvider] 一个自定义提供商应应用于单次运行 按运行
[Agent.model][agents.agent.Agent.model] 不同智能体需要不同的提供商或具体模型对象 按智能体
第三方适配器 由于内置路径无法提供所需支持,您需要适配器提供的提供商覆盖范围或路由 请参阅第三方适配器

您可以通过这些内置路径集成其他 LLM 提供商:

  1. [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。
  2. [ModelProvider][agents.models.interface.ModelProvider] 位于 Runner.run 级别。这样您便可以指定“对此次运行中的所有智能体使用自定义模型提供商”。可配置的代码示例请参阅 examples/model_providers/custom_example_provider.py。
  3. [Agent.model][agents.agent.Agent.model] 允许您在特定 Agent 实例上指定模型。这样便可为不同智能体混合搭配不同提供商。可配置的代码示例请参阅 examples/model_providers/custom_example_agent.py。

如果您没有 platform.openai.com 的 API 密钥,建议通过 set_tracing_disabled() 禁用追踪,或设置其他追踪处理器。

from agents import Agent, AsyncOpenAI, OpenAIChatCompletionsModel, set_tracing_disabled

set_tracing_disabled(disabled=True)

client = AsyncOpenAI(api_key="Api_Key", base_url="Base URL of Provider")
model = OpenAIChatCompletionsModel(model="Model_Name", openai_client=client)

agent = Agent(name="Helping Agent", instructions="You are a Helping Agent", model=model)

!!! note

在这些代码示例中,我们使用 Chat Completions API/模型,因为许多 LLM 提供商仍不支持 Responses API。如果您的 LLM 提供商支持 Responses API,建议使用 Responses。

单个工作流中的模型混用

在单个工作流中,您可能希望为每个智能体使用不同的模型。例如,可以使用更小、更快的模型进行分流,同时使用更大、能力更强的模型处理复杂任务。配置 [Agent][agents.Agent] 时,可以通过以下任一方式选择特定模型:

  1. 传入模型名称。
  2. 传入任意模型名称和一个可将该名称映射到 Model 实例的 [ModelProvider][agents.models.interface.ModelProvider]。
  3. 直接提供 [Model][agents.models.interface.Model] 实现。

!!! note

虽然 SDK 同时支持 [`OpenAIResponsesModel`][agents.models.openai_responses.OpenAIResponsesModel] 和 [`OpenAIChatCompletionsModel`][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 形式,但建议每个工作流仅使用一种模型形式,因为这两种形式支持的功能和工具集不同。如果工作流需要混用模型形式,请确保使用的所有功能在两者上都可用。
import asyncio

from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel

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.6-sol",
)


async def main():
    result = await Runner.run(triage_agent, input="Hola, ¿cómo estás?")
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())
  1. 直接设置OpenAI模型的名称。
  2. 提供 [Model][agents.models.interface.Model] 实现。

如果希望进一步配置智能体使用的模型,可以传入 [ModelSettings][agents.model_settings.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 设置

当您使用 OpenAI Responses 路径并需要更多控制时,请从 ModelSettings 开始。

常用高级 ModelSettings 选项

使用 OpenAI Responses API 时,一些请求字段已经有直接对应的 ModelSettings 字段,因此无需通过 extra_args 设置它们。

  • parallel_tool_calls:允许或禁止在同一轮次中进行多个工具调用。
  • truncation:设置 "auto",让 Responses API 在上下文即将溢出时丢弃最早的对话项,而不是使请求失败。
  • store:控制生成的响应是否存储在服务器端,以供后续检索。这对于依赖响应 ID 的后续工作流以及当 store=False 时可能需要回退到本地输入的会话压缩流程很重要。
  • context_management:配置服务器端上下文处理,例如使用 compact_threshold 进行 Responses 压缩。
  • prompt_cache_retention:为早期模型系列配置延长保留时间,例如 使用 "24h"。
  • prompt_cache_options:选择隐式或显式提示词缓存,并为 GPT-5.6 配置 "30m" 缓存 TTL。
  • response_include:请求更丰富的响应负载,例如 web_search_call.action.sources、file_search_call.results 或 reasoning.encrypted_content。
  • top_logprobs:请求输出文本中高概率 token 的 logprobs。SDK 还会自动添加 message.output_text.logprobs。
  • retry:选择启用由 Runner 管理的模型调用重试设置。请参阅 Runner 管理的重试。
from agents import Agent, ModelSettings

research_agent = Agent(
    name="Research agent",
    model="gpt-5.6-sol",
    model_settings=ModelSettings(
        parallel_tool_calls=False,
        truncation="auto",
        store=True,
        context_management=[{"type": "compaction", "compact_threshold": 200000}],
        prompt_cache_options={"mode": "explicit", "ttl": "30m"},
        response_include=["web_search_call.action.sources"],
        top_logprobs=5,
    ),
)

使用显式提示词缓存时,请在可复用前缀结束的内容部分添加断点。同一 ModelSettings.prompt_cache_options 字段会透传至 Responses 和 Chat Completions 请求,并且 Chat Completions 转换器会保留文本、图像、音频和文件内容部分上的断点。

from agents import Runner

result = await Runner.run(
    research_agent,
    [
        {
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "Reusable background material...",
                    "prompt_cache_breakpoint": {"mode": "explicit"},
                },
                {
                    "type": "input_text",
                    "text": "Analyze the latest question.",
                },
            ],
        }
    ],
)

prompt_cache_retention 仍可供使用旧版 保留控制的早期模型系列使用。请勿将直接的 ModelSettings 字段与 extra_args 中的相同键结合使用。

设置 store=False 后,Responses API 不会保留该响应以供后续服务器端检索。这适用于无状态或零数据保留风格的流程,但也意味着原本会复用响应 ID 的功能需要改为依赖本地管理的状态。例如,当最后一个响应未被存储时,[OpenAIResponsesCompactionSession][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] 会将默认的 "auto" 压缩路径切换为基于输入的压缩。请参阅会话指南。

服务器端压缩不同于 [OpenAIResponsesCompactionSession][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession]。context_management=[{"type": "compaction", "compact_threshold": ...}] 会随每个 Responses API 请求发送,当渲染后的上下文超过阈值时,API 可以将压缩项作为响应的一部分发出。OpenAIResponsesCompactionSession 会在轮次之间调用独立的 responses.compact 端点,并重写本地会话历史记录。

extra_args 的传递

当需要 SDK 尚未直接在顶层公开的提供商特定字段或较新请求字段时,请使用 extra_args。

使用OpenAI模型时,extra_args 可以将可选参数传递给 Responses API 和 Chat Completions API,例如 user 和 service_tier。对于受支持的模型,请设置 extra_args={"service_tier": "fast"} 以使用快速模式;"priority" 仍与之等效。请勿同时通过直接的 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,
        extra_args={"service_tier": "flex", "user": "user_12345"},
    ),
)

模型调用超时

将 [ModelSettings.timeout][agents.model_settings.ModelSettings.timeout] 设置为正数秒值,以限制每次模型调用尝试的时长。超时适用于流式和非流式调用,并涵盖整个尝试过程,包括传输等待。它不限制完整的智能体运行、函数工具执行或重试退避。

from agents import Agent, ModelSettings

agent = Agent(
    name="Assistant",
    model_settings=ModelSettings(timeout=30.0),
)

如果某次尝试超过限制,SDK 会取消该尝试,并等待其清理完成后再引发 [ModelTimeoutError][agents.exceptions.ModelTimeoutError]。启用 Runner 管理的重试后,SDK 会将超时失败传递给重试策略,并将 context.normalized.is_timeout 设置为 True;例如,retry_policies.network_error() 会匹配此分类。每次获准的重试都会获得新的单次尝试超时。SDK 在重试之前仍会应用常规的重放安全规则。

Runner 管理的重试

重试仅在运行时生效,且需要主动启用。除非设置 ModelSettings(retry=...) 且重试策略决定重试,否则 SDK 不会重试一般模型请求。

在 Responses WebSocket 传输中,retry_policies.provider_suggested() 会将响应前过载帧和无代码的 server_error 帧识别为重试建议。这本身不会启用重试:您仍需设置 ModelRetrySettings,并且常规重放安全检查仍然适用。如果已经收到任何响应事件,SDK 就不会重放请求。

from agents import Agent, ModelRetrySettings, ModelSettings, retry_policies

agent = Agent(
    name="Assistant",
    model="gpt-5.6-sol",
    model_settings=ModelSettings(
        retry=ModelRetrySettings(
            max_retries=4,
            backoff={
                "initial_delay": 0.5,
                "max_delay": 5.0,
                "multiplier": 2.0,
                "jitter": True,
            },
            policy=retry_policies.any(
                retry_policies.provider_suggested(),
                retry_policies.retry_after(),
                retry_policies.network_error(),
                retry_policies.http_status([408, 409, 429, 500, 502, 503, 504]),
            ),
        )
    ),
)

ModelRetrySettings 包含三个字段:

字段 类型 说明
max_retries `int None`
backoff `ModelRetryBackoffSettings dict
policy `RetryPolicy None`

重试策略会接收一个 [RetryPolicyContext][agents.retry.RetryPolicyContext],其中包含:

  • attempt 和 max_retries,以便您根据尝试次数做出决策。
  • stream,以便您在流式和非流式行为之间进行分支。
  • error,用于原始检查。
  • normalized 信息,例如 status_code、retry_after、error_code、is_network_error、is_timeout 和 is_abort。
  • 当底层模型适配器可以提供重试指导时的 provider_advice。
  • response_started、replay_safety 和 stateful_request,作为策略运行前捕获的稳定重放安全信息。replay_safety 为 "safe"、"unsafe" 或 "unknown";当请求使用 previous_response_id 或 conversation_id 时,stateful_request 为 true。

策略可以返回以下任一类型:

  • True / False,用于简单的重试决策。
  • 当您希望覆盖延迟、附加诊断原因或显式批准范围严格受限的不安全重放时,返回 [RetryDecision][agents.retry.RetryDecision]。

SDK 在 retry_policies 上导出了现成的辅助工具:

辅助工具 行为
retry_policies.never() 始终选择不重试。
retry_policies.provider_suggested() 在有提供商重试建议时遵循该建议。
retry_policies.network_error() 匹配临时传输和超时失败。
retry_policies.http_status([...]) 匹配选定的 HTTP 状态码。
retry_policies.retry_after() 仅在存在 retry-after 提示时重试,并使用该延迟。此辅助工具将 retry-after 值视为显式策略延迟,因此 backoff.max_delay 不会限制该值。
retry_policies.any(...) 当任一嵌套策略选择重试时进行重试。
retry_policies.all(...) 仅当所有嵌套策略都选择重试时才进行重试。

组合策略时,provider_suggested() 是最安全的首选基础组件,因为当提供商可以区分否决和重放安全批准时,它会保留这些信息。

安全边界

以下某些失败绝不会重试:

  • 中止错误。
  • 已经开始输出,导致重放不安全的流式运行。
  • 存在单独的本地副作用重放否决的请求,包括程序化工具调用请求,除非提供商已独立将重放标记为安全。

默认情况下,提供商标记为不安全的失败也会被阻止。对于不存在单独本地副作用否决的非流式请求,应用程序可以通过返回 RetryDecision(retry=True, approve_unsafe_replay=True) 接受提供商侧的重放风险。批准之前,请检查 context.response_started、context.replay_safety 和 context.stateful_request,并且仅在可以接受重复提供商侧工作时才批准。普通的 RetryDecision(retry=True) 绝不会绕过重放保护,而 approve_unsafe_replay=True 无法授权流式重试或本地副作用。

使用 previous_response_id 或 conversation_id 的有状态后续请求会在重放安全性未知时以拒绝方式失败。对于这些请求,network_error() 或 http_status([500]) 等非提供商谓词本身并不足够。请包含来自提供商的重放安全批准(通常通过 retry_policies.provider_suggested()),或按上述方式显式批准提供商标记为不安全的非流式失败。

Runner 与智能体的合并行为

Runner 级和智能体级 ModelSettings 之间会深度合并 retry:

  • 智能体可以仅覆盖 retry.max_retries,同时继续继承 Runner 的 policy。
  • 智能体可以仅覆盖 retry.backoff 的一部分,同时保留 Runner 中同级的退避字段。
  • policy 仅在运行时有效,因此序列化后的 ModelSettings 会保留 max_retries 和 backoff,但省略回调本身。

更多完整代码示例请参阅 examples/basic/retry.py 和由适配器支持的重试示例。

非OpenAI提供商故障排除

追踪客户端错误 401

如果遇到与追踪相关的错误,这是因为追踪数据会上传到OpenAI服务器,而您没有 OpenAI API 密钥。可通过以下三种方式解决:

  1. 完全禁用追踪:[set_tracing_disabled(True)][agents.set_tracing_disabled]。
  2. 为追踪设置OpenAI密钥:[set_tracing_export_api_key(...)][agents.set_tracing_export_api_key]。此 API 密钥仅用于上传追踪数据,并且必须来自 platform.openai.com。
  3. 使用非OpenAI追踪处理器。请参阅追踪文档。

Responses API 支持

SDK 默认使用 Responses API,但许多其他 LLM 提供商仍不支持它。因此,您可能会遇到 404 或类似问题。可通过以下两种方式解决:

  1. 调用 [set_default_openai_api("chat_completions")][agents.set_default_openai_api]。如果您通过环境变量设置 OPENAI_API_KEY 和 OPENAI_BASE_URL,则此方法有效。
  2. 使用 [OpenAIChatCompletionsModel][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel]。此处提供了代码示例。

Chat Completions 兼容性选项

通过 Chat Completions 路由时,SDK 会静默丢弃 Chat Completions 无法发送的仅限 Responses 字段,以保持兼容性,例如 previous_response_id、conversation_id、Responses API 的 prompt 字段,或并非纯文本的工具输出。如果希望在开发过程中让这些不匹配快速失败,请在OpenAI提供商上启用严格功能验证:

from agents import Agent, OpenAIProvider, RunConfig, Runner

provider = OpenAIProvider(
    use_responses=False,
    strict_feature_validation=True,
)

agent = Agent(name="Assistant")
result = await Runner.run(
    agent,
    "Hello",
    run_config=RunConfig(model_provider=provider),
)

如果使用 [MultiProvider][agents.MultiProvider],请改为传入 openai_strict_feature_validation=True。

OpenAI Chat Completions API 可以返回音频输出,但 [OpenAIChatCompletionsModel][agents.models.openai_chatcompletions.OpenAIChatCompletionsModel] 当前不会将音频输出转换为 Agents SDK 运行项。如果非流式消息或流式增量包含音频输出,适配器会引发 AgentsException("Audio is not currently supported"),而不是返回部分或空结果。对于由 SDK 管理的音频工作流,请使用 Realtime 智能体或语音智能体。

如果流式或非流式 Chat Completions 响应以 finish_reason="length" 结束,且此前未生成助手文本、工具调用或拒绝,适配器会引发 [ModelBehaviorError][agents.exceptions.ModelBehaviorError]。SDK 将此空结果视为 token 或推理预算耗尽,而不是内容策略拒绝,因此模型拒绝处理程序不会为此运行。

一些 OpenAI 兼容的 Chat Completions 提供商会分块传输工具调用增量,但这些分块的可靠性不足以供 SDK 进行增量处理。在这种情况下,请启用流式工具调用缓冲,使 SDK 仅在提供商流结束后发出工具调用:

from agents import OpenAIProvider

provider = OpenAIProvider(
    use_responses=False,
    buffer_streamed_tool_calls=True,
)

对于 [MultiProvider][agents.MultiProvider],请使用 openai_buffer_streamed_tool_calls=True。

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、多模态输入以及托管式文件检索和网络检索,但许多其他提供商不支持这些功能。请注意以下限制:

  • 不要向无法理解不受支持 tools 的提供商发送这些内容
  • 在调用纯文本模型之前过滤掉多模态输入
  • 请注意,不支持结构化 JSON 输出的提供商偶尔会生成无效 JSON。

第三方适配器

仅当 SDK 的内置提供商集成点无法满足需求时,才应使用第三方适配器。如果您仅通过此 SDK 使用OpenAI模型,请优先使用内置的 [OpenAIResponsesModel][agents.models.openai_responses.OpenAIResponsesModel] 路径,而不是 Any-LLM 或 LiteLLM。第三方适配器适用于需要将OpenAI模型与非OpenAI提供商组合使用,或者需要只有适配器才能提供的提供商覆盖范围或路由的情况。适配器会在 SDK 与上游模型提供商之间增加一层兼容性,因此功能支持和请求语义可能因提供商而异。SDK 当前以尽力而为的测试版集成方式包含 Any-LLM 和 LiteLLM。

Any-LLM

Any-LLM 支持以尽力而为的测试版形式提供,适用于需要由 Any-LLM 管理提供商覆盖范围或路由的情况。

根据上游提供商路径,Any-LLM 可能会使用 Responses API、Chat Completions 兼容 API 或提供商特定的兼容层。

如果需要 Any-LLM,请安装 openai-agents[any-llm],然后从 examples/model_providers/any_llm_auto.py 或 examples/model_providers/any_llm_provider.py 开始。您可以将 any-llm/... 模型名称与 [MultiProvider][agents.MultiProvider] 配合使用、直接实例化 AnyLLMModel,或在运行作用域使用 AnyLLMProvider。如果需要显式固定模型接口,请在构造 AnyLLMModel 时传入 api="responses" 或 api="chat_completions"。

在 Any-LLM Chat Completions 路径上,[ModelSettings.extra_body][agents.model_settings.ModelSettings.extra_body] 仍然是嵌套的 extra_body 参数。Agents SDK 不会将该映射合并到 Any-LLM 的顶层调用参数中,因此请将提供商特定的请求正文字段保留在 extra_body 映射内。

Any-LLM 仍是第三方适配层,因此提供商依赖项和能力缺口由上游 Any-LLM 定义,而不是由 SDK 定义。当上游提供商返回用量指标时,这些指标会自动传播,但流式 Chat Completions 后端可能需要 ModelSettings(include_usage=True) 才会发出用量数据块。如果您依赖 structured outputs、工具调用、用量报告或 Responses 特定行为,请验证计划部署的具体提供商后端。

LiteLLM

LiteLLM 支持以尽力而为的测试版形式提供,适用于需要 LiteLLM 特定提供商覆盖范围或路由的情况。

如果需要 LiteLLM,请安装 openai-agents[litellm],然后从 examples/model_providers/litellm_auto.py 或 examples/model_providers/litellm_provider.py 开始。您可以使用 litellm/... 模型名称,也可以直接实例化 [LitellmModel][agents.extensions.models.litellm_model.LitellmModel]。

通过 LiteLLM 适配器访问的某些提供商默认不会填充 SDK 用量指标。如果需要用量报告,请传入 ModelSettings(include_usage=True);如果您依赖 structured outputs、工具调用、用量报告或适配器特定路由行为,请验证计划部署的具体提供商后端。

如果 LiteLLM 针对响应对象发出 Pydantic 序列化程序警告,可以在导入 LiteLLM 适配器之前选择启用 SDK 的兼容性补丁:

export OPENAI_AGENTS_ENABLE_LITELLM_SERIALIZER_PATCH=true

该补丁默认禁用,并且仅对 1 或 true 值启用。它通过封装私有 LiteLLM 日志辅助工具来抑制特定类型的 LiteLLM 响应序列化警告,因此应将其视为针对性的临时解决方案,而不是通用序列化设置。由于它依赖私有 LiteLLM API,升级 LiteLLM 时请重新验证此补丁,并在上游警告不再出现时删除该环境变量。