50 KiB
| search | ||
|---|---|---|
|
模型
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 提供商:
- [
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级别。这样您便可以指定“对此次运行中的所有智能体使用自定义模型提供商”。可配置的代码示例请参阅 examples/model_providers/custom_example_provider.py。 - [
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] 时,可以通过以下任一方式选择特定模型:
- 传入模型名称。
- 传入任意模型名称和一个可将该名称映射到 Model 实例的 [
ModelProvider][agents.models.interface.ModelProvider]。 - 直接提供 [
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())
- 直接设置OpenAI模型的名称。
- 提供 [
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 密钥。可通过以下三种方式解决:
- 完全禁用追踪:[
set_tracing_disabled(True)][agents.set_tracing_disabled]。 - 为追踪设置OpenAI密钥:[
set_tracing_export_api_key(...)][agents.set_tracing_export_api_key]。此 API 密钥仅用于上传追踪数据,并且必须来自 platform.openai.com。 - 使用非OpenAI追踪处理器。请参阅追踪文档。
Responses API 支持
SDK 默认使用 Responses API,但许多其他 LLM 提供商仍不支持它。因此,您可能会遇到 404 或类似问题。可通过以下两种方式解决:
- 调用 [
set_default_openai_api("chat_completions")][agents.set_default_openai_api]。如果您通过环境变量设置OPENAI_API_KEY和OPENAI_BASE_URL,则此方法有效。 - 使用 [
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 时请重新验证此补丁,并在上游警告不再出现时删除该环境变量。