模型

每个智能体最终都会调用 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 的默认模型。

为 Runner 设置默认模型

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

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

GPT-5.x 模型

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

自定义 GPT-5 默认设置

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') （默认）

身份验证

设置默认 OpenAI 密钥

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	提供商创建自己的 OpenAI 客户端时传入的组织和项目值。
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。默认情况下，这些功能会触发警告并被忽略。

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

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：在您自己的应用架构中显式控制生命周期，包括关闭时的清理。

尽管名称中包含 Session，withResponsesWebSocketSession(...) 只是传输生命周期辅助函数，与会话中介绍的记忆 Session 接口无关。

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

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

如果自行实例化 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 工具搜索指南。

托管多智能体（实验性）

实验性 Beta

托管多智能体使用 Beta 版 Responses API 项模式，并且只能通过实验性 @openai/agents-openai/experimental/hosted-multi-agent 导出使用。API 和 SDK 接口可能会发生变化。

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

npm install @openai/agents-openai openai

托管多智能体允许 GPT-5.6 模型通过 Responses API 创建和协调由子智能体构成的树。这与 SDK 交接和 agents-as-tools 不同：应用不会为托管子智能体创建本地 Agent 对象，也不会调度其工作。托管根智能体负责委派工作，服务负责协调子智能体，/root 则汇总最终答案。有关 Beta 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 使其具有幂等性，以防中断后的继续执行重复产生副作用。

输出与流式传输行为

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

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

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

当前限制

实验性 SDK 模型仅支持 Responses WebSocket 传输。Beta 版 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	惩罚重复词元。
presencePenalty	number	鼓励生成新词元。
toolChoice	'auto' | 'required' | 'none' | string	请参阅强制使用工具。在 OpenAI Responses 中，toolChoice: 'computer' 会在可用时强制使用正式版内置计算机工具。
parallelToolCalls	boolean	在支持的情况下允许并行函数调用。
truncation	'auto' | 'disabled'	词元截断策略。
maxTokens	number	响应中的最大词元数。
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。

配置 GPT-5.6 请求控制

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，请参阅 AI SDK 集成。该适配器允许您将 AI SDK 模型直接接入 Agents 运行时。如果应用已统一使用 AI SDK 提供商，或希望使用更广泛的提供商生态系统，此方式非常有用。该页面还介绍了 Agents SDK 的 providerData 如何映射到 AI SDK 的 providerMetadata，以及 AI SDK UI 路由可用的流式辅助函数。

---

追踪凭证

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

设置追踪导出 API 密钥

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

setTracingExportApiKey('sk-...');

这会使用该凭证将追踪发送到 OpenAI 控制面板。有关自定义导出器（例如自定义数据接收端点或重试调优）的信息，请参阅追踪。

---

后续步骤

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