模型

每个智能体最终都会调用 LLM。SDK 通过两个轻量级接口对模型进行抽象：

Model——负责向特定 API 发出一次请求。
ModelProvider——将人类可读的模型名称（例如 'gpt-5.6-sol'）解析为 Model 实例。

在日常工作中，您通常只需与模型名称交互，偶尔还会使用 ModelSettings。

import { Agent } from '@openai/agents';

const agent = new Agent({
  name: 'Creative writer',
  model: 'gpt-5.6-sol',
});

模型选择

默认模型

初始化 Agent 时，如果未指定模型，将使用默认模型。目前默认模型是 gpt-5.6-luna，并配置 reasoning.effort: "none" 和 text.verbosity: "low"，适用于高效、高吞吐量的智能体工作负载。

如果您想切换到 gpt-5.6-sol 等其他模型，可以通过两种方式配置智能体。

第一种方式是，如果您希望所有未设置自定义模型的智能体始终使用某个特定模型，请在运行智能体前设置 OPENAI_DEFAULT_MODEL 环境变量。

export OPENAI_DEFAULT_MODEL=gpt-5.6-sol
node my-awesome-agent.js

第二种方式是为 Runner 实例设置默认模型。如果没有为智能体设置模型，则会使用此 Runner 的默认模型。

import { Runner } from '@openai/agents';

const runner = new Runner({ model: 'gpt-4.1-mini' });

GPT-5.x 模型

以这种方式使用 gpt-5.6-sol 等任意 GPT-5.x 模型时，SDK 会应用默认的 modelSettings，这些设置最适合大多数用例。要调整默认模型的推理强度，请传入您自己的 modelSettings：

import { Agent } from '@openai/agents';

const myAgent = new Agent({
  name: 'My Agent',
  instructions: "You're a helpful agent.",
  // If OPENAI_DEFAULT_MODEL=gpt-5.6-sol is set, passing only modelSettings works.
  // It's also fine to pass a GPT-5.x model name explicitly:
  model: 'gpt-5.6-sol',
  modelSettings: {
    reasoning: { effort: 'high' },
    text: { verbosity: 'low' },
  },
});

如果延迟和成本很重要，请先使用默认的 gpt-5.6-luna 配置，或在其他 GPT-5.x 模型上使用 reasoning.effort: "none"；仅当任务需要更审慎的推理时，再提高推理强度。

非 GPT-5 模型

如果传入非 GPT-5 模型名称且未提供自定义 modelSettings，SDK 将恢复使用兼容任何模型的通用 modelSettings。

OpenAI 提供商配置

OpenAI 提供商

默认 ModelProvider 使用 OpenAI API 解析名称。它支持两个不同的端点：

API	用途	调用 `setOpenAIAPI()`
Chat Completions	标准聊天与函数调用	`setOpenAIAPI('chat_completions')`
Responses	全新的流式传输优先生成式 API（工具调用、灵活输出）	`setOpenAIAPI('responses')` （默认）

身份验证

import { setDefaultOpenAIKey } from '@openai/agents';

setDefaultOpenAIKey(process.env.OPENAI_API_KEY!); // sk-...

如果需要自定义网络设置，也可以通过 setDefaultOpenAIClient(client) 接入您自己的 OpenAI 客户端。直接提供的客户端必须使用 openai 7.2 或更高版本。

提供商选项参考

直接实例化 OpenAIProvider 时，以下选项控制客户端构造、端点选择和功能验证：

选项	用途
`apiKey`	提供商创建自己的 OpenAI 客户端时使用的 API 密钥。默认为 SDK 范围内的 OpenAI 密钥。
`baseURL`	OpenAI 兼容端点的 HTTP 基础 URL。不能与 `openAIClient` 同时使用。
`websocketBaseURL`	Responses WebSocket 传输机制的 WebSocket 基础 URL。不能与 `openAIClient` 同时使用。
`openAIClient`	来自 `openai` 7.2 或更高版本的预配置客户端。不能与 `apiKey`、`baseURL`、`websocketBaseURL`、`organization` 或 `project` 同时使用。
`organization` / `project`	提供商创建自己的 OpenAI 客户端时传入的组织和项目值。不能与 `openAIClient` 同时使用。
`useResponses`	为此提供商解析的字符串模型名称选择 Responses API（`true`）或 Chat Completions API（`false`）。默认为进程范围内的 `setOpenAIAPI(...)` 设置。
`useResponsesWebSocket`	对此提供商解析的 Responses 模型使用 WebSocket 传输机制。默认为进程范围内的 `setOpenAIResponsesTransport(...)` 设置。
`cacheResponsesWebSocketModels`	复用基于 WebSocket 的 Responses 模型包装器，以便复用连接。默认为 `true`；关闭时调用 `provider.close()` 以关闭缓存的包装器。
`responsesWebSocketOptions`	使用 `pingIntervalMs` 和 `pingTimeoutMs` 配置客户端保活。
`strictFeatureValidation`	对于 Chat Completions 模型，遇到 `previousResponseId`、`conversationId`、`prompt` 和助手消息阶段等仅限 Responses 的功能时抛出 `UserError`。默认情况下会警告并忽略这些功能。

如果存在 apiKey、baseURL、organization 或 project，该 OpenAIProvider 会使用提供商特定的值构造自己的 OpenAI 客户端，而不会复用通过 setDefaultOpenAIClient(...) 配置的客户端。如果这些选项和 openAIClient 均不存在，提供商可以复用 SDK 范围内的默认客户端。websocketBaseURL 会更改 Responses WebSocket 的目标，但其本身不会替换 HTTP 客户端。

当 Responses 助手消息包含值为 commentary 或 final_answer 的 phase 时，SDK 会将其保留为历史记录项的顶层字段。通过 OpenAIConversationsSession 重放会话以及序列化 RunState 时，该阶段都会保留。Chat Completions 没有对应字段，因此默认情况下会发出警告并丢弃该阶段；设置 strictFeatureValidation: true 可改为拒绝该转换。

Responses 终止状态

Responses 流式传输协议使用带类型的终止事件。SDK 将包含响应载荷的 response.completed 事件视为成功的模型结果。在流式传输和非流式传输运行中，以下情况均会抛出 ModelBehaviorError：failed 或 incomplete 响应，response.failed、response.incomplete 或 response.error 事件，error 事件，或者缺少必需响应载荷的 response.completed 事件。

SDK 将失败的终止状态视为可能已开始的响应，因而无法安全重放。对于非流式传输运行，默认重试建议不会自动重复请求；在运行器能够重试之前，自定义重试策略必须明确批准不安全重放。对于流式传输运行，即使自定义重试策略批准不安全重放，运行器在发出原始终止事件后也不会重试。如果失败响应报告了用量，运行器仍会将该用量纳入追踪和运行计量。即使 result.completed 被拒绝，流式传输结果仍会在 result.state.usage 中保留该用量。

失败响应不会成为成功的 ModelResponse，不会追加到 rawResponses 或会话历史记录，也不会执行该响应中的输出项。在 result.completed 被拒绝前，流式传输使用方仍可通过原始模型事件流检查原始终止事件。不要将部分终止输出视为可重放的历史记录或最终输出。

Chat Completions 截断

对于 Chat Completions，finish_reason: 'length' 表示提供商因达到 token 或上下文限制而停止生成。当选项包含有用的文本、拒绝、音频、推理或函数调用时，SDK 会保留该部分助手载荷。当被截断的选项不包含上述任何载荷时，SDK 会在流式传输和非流式传输运行中抛出 ModelBehaviorError，而不会将空选项视为成功响应。

SDK 将这种空截断视为可能已开始的响应，因而无法安全重放。在 result.completed 被拒绝前，流式传输使用方可能已经收到原始数据块。如果失败的尝试报告了用量，运行器仍会将该用量纳入追踪和运行计量。

Chat Completions 音频

支持音频的 Chat Completions 模型通过 modelSettings.providerData 接收端点特定的 modalities 和 audio 请求字段。请使用支持音频的模型，并遵循官方音频与语音指南中支持的请求值。

非流式调用和流式调用都会保留纯音频的助手输出。规范化后的 ModelResponse.output 包含一个 audio 内容部分。当该消息成为运行项时，RunMessageOutputItem.rawItem 包含相同部分。其 audio 字段包含 base64 数据，而 providerData 则保留 id、transcript、format 和 expires_at 等提供商元数据。如果同一选项还包含文本或拒绝，规范化后的助手消息会保留该文本或拒绝。对于非流式调用，完整的提供商响应（包括音频）仍可通过 result.rawResponses[].providerData 获取。对于流式调用，请在源 Chat Completions 数据块到达时，通过原始模型流事件使用它们；重建后的音频会保留用于追踪，但不会保留在 result.rawResponses 中。空音频片段会被忽略。格式错误或不可克隆的音频增量，或者结束时没有音频数据的流，都会以 ModelBehaviorError 失败。toTextStream() 仅发出助手文本。如果应用需要低延迟双向音频，请改用 Realtime API。

Responses WebSocket 传输机制

将 OpenAI 提供商与 Responses API 搭配使用时，可以通过 WebSocket 传输机制发送请求，而不是使用默认的 HTTP 传输机制。

可以通过 setOpenAIResponsesTransport('websocket') 全局启用，也可以通过 new OpenAIProvider({ useResponses: true, useResponsesWebSocket: true }) 为单个提供商启用。

仅使用 WebSocket 传输机制时，不需要 withResponsesWebSocketSession(...) 或自定义 OpenAIProvider。如果可以接受每次运行或请求都重新连接，那么启用 setOpenAIResponsesTransport('websocket') 后，现有的 run() / Runner.run() 用法仍会继续工作。

传输机制的选择遵循模型解析方式：

setOpenAIResponsesTransport('websocket') 仅影响之后通过 OpenAI 提供商解析、且使用 Responses API 的字符串模型名称。
如果向 Agent 或 Runner 传入具体的 Model 实例，则会按原样使用该实例。OpenAIResponsesWSModel 继续使用 WebSocket，OpenAIResponsesModel 继续使用 HTTP，OpenAIChatCompletionsModel 继续使用 Chat Completions。
如果提供自己的 modelProvider，该提供商将控制模型解析。请在那里启用 WebSocket，而不要依赖全局设置器。
如果通过代理、网关或其他 OpenAI 兼容端点进行路由，目标必须支持 WebSocket /responses 端点。您可能还需要显式设置 websocketBaseURL。

仅当您希望优化连接复用，并更明确地管理 WebSocket 提供商生命周期时，才使用 withResponsesWebSocketSession(...) 或自定义 OpenAIProvider / Runner：

withResponsesWebSocketSession(...)：便捷的作用域生命周期，回调完成后会自动清理。
自定义 OpenAIProvider / Runner：在您自己的应用架构中显式控制生命周期，包括关闭时的清理。

尽管名称如此，withResponsesWebSocketSession(...) 是传输机制生命周期辅助函数，与会话中描述的记忆 Session 接口无关。

如果使用 WebSocket 代理或网关，请在 OpenAIProvider 上配置 websocketBaseURL，或设置 OPENAI_WEBSOCKET_BASE_URL。

在 responsesWebSocketOptions 中，pingIntervalMs 用于设置客户端 ping 之间的间隔；省略该值或将其设为 null 可禁用 ping。pingTimeoutMs 用于设置等待 pong 的时长，超过该时长后将终止或关闭套接字；省略该值或将其设为 null 可在保持 ping 启用的同时禁用心跳超时。保活需要使用公开 ping 和 pong 支持的 WebSocket 实现。

如果自行实例化 OpenAIProvider，请记住，基于 WebSocket 的 Responses 模型包装器默认会被缓存以复用连接。关闭时调用 await provider.close()，以释放这些缓存连接。withResponsesWebSocketSession(...) 的主要用途就是为您管理该生命周期：它会创建启用 WebSocket 的提供商和运行器，将它们传给您的回调，并在之后始终关闭提供商。使用 providerOptions 配置临时提供商，使用 runnerConfig 配置回调作用域内的运行器默认值。

有关使用 Responses WebSocket 传输机制的完整流式传输与人工干预代码示例，请参阅 examples/basic/stream-ws.ts。

仅限 Responses 的延迟工具加载

toolSearchTool()、toolNamespace()，以及设置了 deferLoading: true 的函数工具或托管 MCP 工具，都需要使用 OpenAI Responses API。Chat Completions 提供商会拒绝带命名空间或延迟加载的函数工具，而 AI SDK 适配器不支持延迟的 Responses 工具加载流程。如果需要工具搜索，请直接使用 Responses 模型。

仅 GPT-5.6 Sol 和更新的模型版本支持工具搜索，并且这些模型必须在 Responses API 中支持该功能。

当运行包含延迟工具时，请将 toolSearchTool() 添加到同一个智能体，并让 modelSettings.toolChoice 保持为 'auto'。SDK 不允许按名称强制使用内置 tool_search 工具或延迟函数工具，因为模型需要决定何时加载这些定义。有关完整设置，请参阅工具和官方 OpenAI 工具搜索指南。

托管式多智能体（实验性）

请将提供商软件包和 OpenAI 客户端安装为直接依赖项，因为代码示例会直接导入这两个软件包：

npm install @openai/agents-openai openai

托管式多智能体允许 GPT-5.6 模型通过 Responses API 创建并协调子智能体树。这与 SDK 交接和 agents-as-tools 不同：应用不会为托管子智能体创建本地 Agent 对象，也不会调度它们的工作。托管的根智能体负责委派工作，服务负责协调子智能体，而 /root 则综合生成最终答案。有关测试版 API 的行为和支持的模型，请参阅官方多智能体指南。

实验性模型配置

显式构造 OpenAIHostedMultiAgentModel 并将其传给 SDK Agent。构造该模型本身即表示选择启用，无需单独的启用标志。

实验性模型使用持久化的 Responses WebSocket。本地函数输出通过 response.inject 注入当前活动的托管响应，因此请在整个运行期间使用同一个模型实例，并在不再需要时将其关闭。

import OpenAI from 'openai';
import { Agent, run, tool } from '@openai/agents';
import {
  OpenAIHostedMultiAgentModel,
  getHostedAgentMetadata,
} from '@openai/agents-openai/experimental/hosted-multi-agent';
import { z } from 'zod';

const lookupProject = tool({
  name: 'lookup_project',
  description: 'Return details about a project.',
  parameters: z.object({ project: z.string() }),
  execute: async ({ project }, _context, details) => {
    const caller = getHostedAgentMetadata(details);
    console.log(`Tool called by ${caller?.agentName ?? 'unknown'}`);
    return { project, status: 'on track' };
  },
});

const model = new OpenAIHostedMultiAgentModel(new OpenAI(), 'gpt-5.6-sol', {
  maxConcurrentSubagents: 3,
});

try {
  const agent = new Agent({
    name: 'Hosted coordinator',
    model,
    tools: [lookupProject],
    instructions:
      'Delegate project research to hosted subagents, wait for them, and synthesize the result.',
  });

  const result = await run(agent, 'Compare projects alpha and beta.');
  console.log(result.finalOutput);
} finally {
  await model.close();
}

有关流式传输可观测性（包括托管协作记录和子智能体消息），请参阅完整代码示例。

省略 maxConcurrentSubagents 可保留服务默认值，目前为三个。提供的值必须是正整数。

工具执行与归属

每个托管智能体都使用请求中的模型，并看到相同的本地工具定义。当任意托管智能体发出常规 function_call 时，现有 Agents SDK 运行器会执行应用工具。Responses API 的调用 ID 是路由令牌：SDK 会将匹配的 function_call_output 注入当前活动的托管响应，并路由给发出请求的调用方。

getHostedAgentMetadata(details) 从工具回调的第三个参数中读取托管智能体名称。此元数据对日志记录和应用授权很有用，但不会控制路由。不要按智能体名称分派函数结果；请保留并使用调用 ID。

工具参数通过 WebSocket 从服务传入，工具输出则注入回当前活动的托管响应。请在应用中实施敏感数据策略、工具授权和审批检查。如果工具具有副作用，请按调用 ID 使其具备幂等性，以免中断后的继续执行重复产生该副作用。

输出与流式传输行为

只有 phase 为 final_answer 的 /root 消息才会成为普通助手输出，并计入 finalOutput。函数调用仍是普通的 SDK 工具调用，以便运行器执行；推理和托管工具调用等稳定的 Responses 项会保留现有的 SDK 表示形式。子智能体消息、根智能体评注和托管协作记录会保留在当前活动的 WebSocket 响应中，不会添加到 SDK 历史记录。

原始流式事件仍可通过 raw_model_stream_event 获取，其中包括托管记录和子智能体消息。高级项流式传输会保留稳定的 Responses 项，同时过滤仅限测试版的协作记录；高级文本流式传输则只包含根智能体的最终答案。这能在保留完整托管事件流以供观测的同时，使 RunState 和会话历史记录保持提供商中立。

请持续使用流式运行，直至收到其终止事件。如果流使用方提前停止，SDK 会关闭 WebSocket 并放弃当前活动的托管响应；之后的运行会开始新的托管响应，而不会恢复被放弃的响应。

当前限制

实验性 SDK 模型仅支持 Responses WebSocket 传输机制。测试版 Responses API 也支持通过 HTTP 使用托管式多智能体，但 OpenAIHostedMultiAgentModel 会保持一个 WebSocket 连接，以便 SDK 运行器在继续执行前，将每个本地函数输出注入当前活动的响应。

进行中托管响应的继续执行状态由 OpenAIHostedMultiAgentModel 实例保存。模型可以在注入待处理函数输出前重新连接已关闭的 WebSocket，但审批和中断的工具仍必须使用同一个模型实例，以及相同的 WebSocket 传输标头和查询来恢复。重新创建模型会丢失继续执行状态。一个模型实例同一时间也只支持一次活动运行。

只有当 SDK 确定请求帧尚未发送时，传输失败才能安全重放。一旦服务器可能已经收到该帧，SDK 就会将错误标记为无法安全重放，并且不会自动重复托管轮次。有关通用重试策略，请参阅模型重试。

不要将此模型与 SDK 交接、reasoning.summary 或 max_tool_calls 组合使用；这些组合会在发送请求前失败。仍支持使用 modelSettings.contextManagement 配置的服务器端压缩阈值，而显式调用 Responses 压缩端点不属于此模型的生命周期。您仍可将 SDK 交接和 agents-as-tools 与稳定的 OpenAIResponsesModel 搭配使用。

模型行为与提示

ModelSettings

ModelSettings 与 OpenAI 参数对应，但不依赖特定提供商。

字段	类型	说明
`temperature`	`number`	创造性与确定性之间的权衡。
`topP`	`number`	核采样。
`frequencyPenalty`	`number`	惩罚重复 token。
`presencePenalty`	`number`	鼓励生成新 token。
`toolChoice`	`'auto' \| 'required' \| 'none' \| string`	请参阅强制使用工具。在 OpenAI Responses 中，`toolChoice: 'computer'` 会在可用时强制使用正式发布的内置计算机工具。
`parallelToolCalls`	`boolean`	在支持的情况下允许并行函数调用。
`truncation`	`'auto' \| 'disabled'`	token 截断策略。
`maxTokens`	`number`	响应中的最大 token 数。
`timeoutMs`	`number`	每次模型请求尝试的协作式超时，单位为毫秒。必须是有限值、大于 `0` 且不超过 `2147483647`。
`store`	`boolean`	持久化响应，以供检索/RAG 工作流使用。
`promptCacheRetention`	`'in-memory' \| '24h' \| null`	在支持的情况下控制旧版最大提示缓存保留策略。此设置独立于 `promptCacheOptions.ttl`。
`promptCacheOptions`	`{ mode?: 'implicit' \| 'explicit'; ttl?: '30m' }`	控制 GPT-5.6 及更高版本模型的隐式或显式提示缓存断点。
`contextManagement`	`ModelSettingsContextManagement`	控制提供商上下文管理，例如服务器端压缩。
`reasoning.effort`	`'none' \| 'minimal' \| 'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'`	支持的 gpt-5.x 模型的推理强度。GPT-5.6 支持 `max`。
`reasoning.mode`	`'standard' \| 'pro' \| string`	选择推理执行模式。此设置需要 Responses API。
`reasoning.context`	`'auto' \| 'current_turn' \| 'all_turns' \| null`	控制后续轮次中哪些推理项会重新呈现给模型。此设置需要 Responses API。
`reasoning.summary`	`'auto' \| 'concise' \| 'detailed'`	控制模型返回的推理摘要详细程度。
`text.verbosity`	`'low' \| 'medium' \| 'high'`	gpt-5.x 等模型的文本详细程度。
`providerData`	`Record<string, any>`	转发给底层模型的提供商特定透传选项。
`preserveRawUsage`	`boolean`	在 SDK 对每个已完成模型响应的提供商用量进行规范化前，保留一份独立且兼容 JSON 的快照。默认禁用。
`retry`	`ModelRetrySettings`	仅运行时使用的选择启用重试配置。请参阅模型重试。

可在任一层级附加设置：

import { Runner, Agent } from '@openai/agents';

const agent = new Agent({
  name: 'Creative writer',
  // ...
  modelSettings: { temperature: 0.7, toolChoice: 'auto' },
});

// or globally
new Runner({ modelSettings: { temperature: 0.3 } });

Runner 层级的设置会覆盖智能体层级的冲突设置。reasoning、text、promptCacheOptions 和 retry 中的嵌套字段会在运行器设置和智能体设置之间合并，除非您使用 undefined 显式清除继承的值。

当 timeoutMs 到期时，SDK 会中止当前模型请求尝试。如果重试处理既未开始另一次尝试，也未报告其他故障，SDK 将抛出 ModelTimeoutError。运行层级的中止信号仍会取消整个运行。如果启用了模型重试，重试策略会像评估其他失败尝试一样评估超时；仅当该策略选择重试，并且请求可安全重放或应用显式批准不安全重放时，SDK 才会重试。

当您需要提供商特定的用量字段，或需要区分省略字段与规范化后的零值时，请设置 preserveRawUsage: true。OpenAI Responses、OpenAI Chat Completions 和基于 AI SDK 的模型均支持在流式传输和非流式传输运行中使用此设置。保留操作会尽力而为：如果提供商未返回用量，或返回的值无法安全复制为普通的 JSON 兼容数据，rawUsage 将保持为 undefined。有关如何访问保留的载荷，请参阅原始响应。

GPT-5.6 推理与提示缓存控制

GPT-5.6 增加了请求层级的推理模式和显式提示缓存断点。reasoning.mode 和 reasoning.context 是仅限 Responses 的设置。OpenAIChatCompletionsModel 会发出一次警告并忽略它们；如果启用了严格功能验证，则会在请求前抛出 UserError。受支持的 Chat Completions 模型仍可使用 reasoning.effort。

Responses 和 Chat Completions 模型路径都会转发 promptCacheOptions。默认的 implicit 模式允许 OpenAI 在任何显式断点之外选择一个自动断点。设置 mode: 'explicit' 后，将仅使用带有 promptCacheBreakpoint: { mode: 'explicit' } 标记的内容部分。目前支持的最短缓存生命周期为 30m。

import { Agent, run } from '@openai/agents';

const agent = new Agent({
  name: 'Research assistant',
  model: 'gpt-5.6',
  modelSettings: {
    reasoning: {
      mode: 'pro',
      effort: 'max',
      context: 'all_turns',
    },
    promptCacheOptions: {
      mode: 'explicit',
      ttl: '30m',
    },
  },
});

await run(agent, [
  {
    role: 'user',
    content: [
      {
        type: 'input_text',
        text: 'Treat this research brief as a reusable prompt prefix.',
        promptCacheBreakpoint: { mode: 'explicit' },
      },
      {
        type: 'input_text',
        text: 'Summarize the brief and identify its main risks.',
      },
    ],
  },
]);

GPT-5.6 及更高版本的模型支持显式断点。支持的内容部分类型和断点限制会因 API 而异；有关最新详情，请参阅官方提示缓存断点指南。

模型重试

重试仅在运行时可用，并且需要选择启用。除非您配置 modelSettings.retry，且策略返回重试决定，否则 SDK 不会重试模型请求。

import { Agent, Runner, retryPolicies } from '@openai/agents';

const sharedRetry = {
  maxRetries: 4,
  backoff: {
    initialDelayMs: 500,
    maxDelayMs: 5_000,
    multiplier: 2,
    jitter: true,
  },
  policy: retryPolicies.any(
    retryPolicies.providerSuggested(),
    retryPolicies.retryAfter(),
    retryPolicies.networkError(),
    retryPolicies.httpStatus([408, 409, 429, 500, 502, 503, 504]),
  ),
};

const runner = new Runner({
  modelSettings: {
    retry: sharedRetry,
  },
});

const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are a concise assistant.',
  modelSettings: {
    retry: {
      maxRetries: 2,
      backoff: {
        maxDelayMs: 2_000,
      },
    },
  },
});

await runner.run(agent, 'Summarize exponential backoff in plain English.');

ModelRetrySettings 包含三个字段：

字段	类型	说明
`maxRetries`	`number`	初始请求之后允许的重试次数。
`backoff`	`{ initialDelayMs?, maxDelayMs?, multiplier?, jitter? }`	当策略重试但未返回 `delayMs` 时使用的默认延迟策略。`backoff.maxDelayMs` 仅限制计算出的退避延迟；它不会限制策略返回的显式 `delayMs` 值或 retry-after 提示。
`policy`	`RetryPolicy`	决定是否重试的回调。此函数仅在运行时使用，不会序列化到持久化的运行状态中。

重试策略接收包含以下内容的 RetryPolicyContext：

attempt 和 maxRetries，便于根据尝试次数做出决定。
stream，便于区分流式传输和非流式传输行为。
error，用于检查原始错误。
normalized，包含 statusCode、retryAfterMs、errorCode、isNetworkError 和 isAbort 等规范化事实。
providerAdvice，底层模型或提供商可通过它提供重试指导。
replaySafety、responseStarted 和 statefulRequest，便于应用策略检查运行器稳定的重放分类，而无需重新解读提供商特定的错误。

策略可以返回以下任一种值：

true / false，用于简单的重试决定。
{ retry, delayMs?, reason?, approveUnsafeReplay? }，用于覆盖延迟、附加供日志记录使用的诊断原因，或显式授权提供商标记为不安全的非流式重放。

SDK 在 retryPolicies 上导出了现成的辅助函数：

辅助函数	行为
`retryPolicies.never()`	始终选择不重试。
`retryPolicies.providerSuggested()`	在可用时遵循提供商的重试建议。
`retryPolicies.networkError()`	匹配暂时性的传输或连接故障。
`retryPolicies.httpStatus([..])`	匹配选定的 HTTP 状态码。
`retryPolicies.retryAfter()`	仅当存在 retry-after 提示时重试，并将该提示用作不受 `backoff.maxDelayMs` 限制的显式延迟。
`retryPolicies.any(...)`	任意嵌套策略选择重试时即重试。
`retryPolicies.all(...)`	仅当所有嵌套策略都选择重试时才重试。

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

安全边界

某些失败永远不会自动重试：

中止错误。
已经发出任何可见事件或原始模型事件后的流式传输运行。
将重放标记为不安全的提供商建议。

使用 previousResponseId 或 conversationId 的有状态后续请求也会得到更保守的处理。对于这些请求，networkError() 或 httpStatus([500]) 等非提供商谓词本身并不足够。重试策略必须包含提供商的安全重放批准，通常通过 retryPolicies.providerSuggested() 实现。

应用可以通过返回 { retry: true, approveUnsafeReplay: true }，覆盖提供商对非流式请求的不安全分类。这表示明确确认先前的请求可能已经被接受，重试可能导致响应或其他提供商端工作重复。仅当应用能够容忍该结果时才使用此选项。它无法覆盖中止处理、已发出事件的流式请求或不安全的流式重放。使用 retryPolicies.any(...) 或 retryPolicies.all(...) 组合策略时，只有当返回的决定显式设置 approveUnsafeReplay: true 时，才会保留该批准。

运行器与智能体合并行为

运行器层级与智能体层级的 modelSettings 之间会深度合并 retry：

智能体可以仅覆盖 retry.maxRetries，同时仍继承运行器的 policy。
智能体可以仅覆盖 retry.backoff 的一部分，同时保留运行器中的其他同级退避字段。
如果需要移除继承的 policy 或 backoff，请将该字段显式设置为 undefined。

有关包含日志记录的更完整代码示例，请参阅 examples/basic/retry.ts 和 examples/ai-sdk/retry.ts。

提示

可以使用 prompt 参数配置智能体，该参数指示应使用服务器存储的提示配置来控制智能体的行为。目前，仅当使用 OpenAI Responses API 时才支持此选项。

prompt 可以是静态对象，也可以是运行时返回对象的函数。有关回调形式，请参阅动态提示。

字段	类型	说明
`promptId`	`string`	提示的唯一标识符。
`version`	`string`	您希望使用的提示版本。
`variables`	`object`	要替换到提示中的键值变量对。值可以是字符串，也可以是文本、图像或文件等内容输入类型。

import { parseArgs } from 'node:util';
import { Agent, run } from '@openai/agents';

/*
NOTE: This example will not work out of the box, because the default prompt ID will not
be available in your project.

To use it, please:
1. Go to https://platform.openai.com/chat/edit
2. Create a new prompt variable, `poem_style`.
3. Create a system prompt with the content:
   Write a poem in {{poem_style}}
4. Run the example with the `--prompt-id` flag.
*/

const DEFAULT_PROMPT_ID =
  'pmpt_6965a984c7ac8194a8f4e79b00f838840118c1e58beb3332';
const POEM_STYLES = ['limerick', 'haiku', 'ballad'];

function pickPoemStyle(): string {
  return POEM_STYLES[Math.floor(Math.random() * POEM_STYLES.length)];
}

async function runDynamic(promptId: string) {
  const poemStyle = pickPoemStyle();
  console.log(`[debug] Dynamic poem_style: ${poemStyle}`);

  const agent = new Agent({
    name: 'Assistant',
    prompt: {
      promptId,
      version: '1',
      variables: { poem_style: poemStyle },
    },
  });

  const result = await run(agent, 'Tell me about recursion in programming.');
  console.log(result.finalOutput);
}

async function runStatic(promptId: string) {
  const agent = new Agent({
    name: 'Assistant',
    prompt: {
      promptId,
      version: '1',
      variables: { poem_style: 'limerick' },
    },
  });

  const result = await run(agent, 'Tell me about recursion in programming.');
  console.log(result.finalOutput);
}

async function main() {
  const args = parseArgs({
    options: {
      dynamic: { type: 'boolean', default: false },
      'prompt-id': { type: 'string', default: DEFAULT_PROMPT_ID },
    },
  });

  const promptId = args.values['prompt-id'];
  if (!promptId) {
    console.error('Please provide a prompt ID via --prompt-id.');
    process.exit(1);
  }

  if (args.values.dynamic) {
    await runDynamic(promptId);
  } else {
    await runStatic(promptId);
  }
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

任何其他智能体配置（例如 tools 或 instructions）都会覆盖存储提示中可能配置的值。

当存储的提示已经定义模型时，除非您显式覆盖，否则 SDK 不会发送智能体的默认模型。这对 computerTool() 很重要：为了兼容性，由提示管理的运行默认保留旧版预览线协议格式。要在由提示管理的运行中选择使用正式发布的 Responses 计算机工具，请显式设置 modelSettings.toolChoice: 'computer'，或发送 gpt-5.6-sol 等显式模型。有关计算机操作的相关详情，请参阅工具。

高级提供商与可观测性

自定义模型提供商

实现自己的提供商非常简单：实现 ModelProvider 和 Model，然后将该提供商传给 Runner 构造函数：

import {
  ModelProvider,
  Model,
  ModelRequest,
  ModelResponse,
  ResponseStreamEvent,
} from '@openai/agents-core';

import { Agent, Runner } from '@openai/agents';

class EchoModel implements Model {
  name: string;
  constructor() {
    this.name = 'Echo';
  }
  async getResponse(request: ModelRequest): Promise<ModelResponse> {
    return {
      usage: {},
      output: [{ role: 'assistant', content: request.input as string }],
    } as any;
  }
  async *getStreamedResponse(
    _request: ModelRequest,
  ): AsyncIterable<ResponseStreamEvent> {
    yield {
      type: 'response.completed',
      response: { output: [], usage: {} },
    } as any;
  }
}

class EchoProvider implements ModelProvider {
  getModel(_modelName?: string): Promise<Model> | Model {
    return new EchoModel();
  }
}

const runner = new Runner({ modelProvider: new EchoProvider() });
console.log(runner.config.modelProvider.getModel());
const agent = new Agent({
  name: 'Test Agent',
  instructions: 'You are a helpful assistant.',
  model: new EchoModel(),
  modelSettings: { temperature: 0.7, toolChoice: 'auto' },
});
console.log(agent.model);

如果希望每次 run() 调用和每个新构造的 Runner 默认使用同一个提供商，请在应用启动时设置一次：

import { setDefaultModelProvider } from '@openai/agents';

setDefaultModelProvider({
  async getModel() {
    // Return any Model implementation here.
    throw new Error('Provide your own model implementation.');
  },
});

当您的应用统一使用非 OpenAI 提供商，并且不希望在各处传递自定义 Runner 时，此功能很有用。

AI SDK 集成

如果希望使用非 OpenAI 模型，而不想自行实现 ModelProvider，请参阅使用 Vercel AI SDK 中的任意模型。该适配器允许您直接将 AI SDK 模型接入 Agents 运行时；当应用已经统一使用 AI SDK 提供商，或希望访问更广泛的提供商生态系统时，这非常有用。该页面还说明了 Agents SDK providerData 如何映射到 AI SDK providerMetadata，以及 AI SDK UI 路由可用的流辅助函数。

追踪凭据

在受支持的服务器运行时中，追踪默认已经启用。仅当追踪导出需要使用与默认 OpenAI API 密钥不同的凭据时，才使用 setTracingExportApiKey()：

import { setTracingExportApiKey } from '@openai/agents';

setTracingExportApiKey('sk-...');

这会使用该凭据将追踪发送到 OpenAI 控制面板。有关自定义采集端点或重试调优等导出器自定义内容，请参阅追踪。

后续步骤

探索运行智能体。
使用工具为模型赋予强大能力。
根据需要添加护栏或追踪。