模型
每个智能体最终都会调用 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-solnode my-awesome-agent.js第二种方式,可以为 Runner 实例设置默认模型。如果没有为智能体设置模型,就会使用此 Runner 的默认模型。
import { Runner } from '@openai/agents';
const runner = new Runner({ model: 'gpt-4.1-mini' });GPT-5.x 模型
Section titled “GPT-5.x 模型”以这种方式使用任何 GPT-5.x 模型(例如 gpt-5.6-sol)时,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 模型
Section titled “非 GPT-5 模型”如果传入非 GPT-5 模型名称且未自定义 modelSettings,SDK 会回退到与任何模型兼容的通用 modelSettings。
OpenAI 提供方配置
Section titled “OpenAI 提供方配置”OpenAI 提供方
Section titled “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 或更高版本。
提供方选项参考
Section titled “提供方选项参考”直接实例化 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 模型,使用仅限 Responses 的功能(例如 previousResponseId、conversationId、prompt 和助手消息阶段)时抛出 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 终止状态
Section titled “Responses 终止状态”Responses 流式传输协议使用带类型的终止事件。SDK 将带有响应载荷的 response.completed 事件视为成功的模型结果。对于 failed 或 incomplete 响应,response.failed、response.incomplete 或 response.error 事件,error 事件,以及缺少必需响应载荷的 response.completed 事件,SDK 在流式和非流式运行中都会抛出 ModelBehaviorError。
SDK 将未成功的终止状态视为响应可能已经开始,因此重放并不安全。对于非流式运行,默认重试建议不会自动重复请求;自定义重试策略必须明确批准不安全的重放,运行器才能重试。对于流式运行,一旦发出原始终止事件,运行器就不会重试,即使自定义重试策略批准了不安全的重放也是如此。如果未成功的响应报告了用量,运行器仍会将该用量计入追踪和运行统计。即使 result.completed 被拒绝,流式执行结果也会在 result.state.usage 中保留用量。
未成功的响应不会成为成功的 ModelResponse,不会追加到 rawResponses 或会话历史记录中,也不会执行该响应中的输出项。在 result.completed 被拒绝之前,流式消费者仍可通过原始模型事件流查看原始终止事件。不要将终止时的部分输出视为可重放的历史记录或最终输出。
Chat Completions 截断
Section titled “Chat Completions 截断”对于 Chat Completions,finish_reason: 'length' 表示提供方因达到 token 或上下文限制而停止生成。当候选项包含有用的文本、拒绝内容、音频、推理或函数调用时,SDK 会保留该部分助手载荷。当被截断的候选项不包含上述任何载荷时,SDK 在流式和非流式运行中都会抛出 ModelBehaviorError,而不是将空候选项视为成功响应。
SDK 将这种空截断视为响应可能已经开始,因此重放并不安全。在 result.completed 被拒绝之前,流式消费者可能已经收到了原始数据块。如果失败的尝试报告了用量,运行器仍会将该用量计入追踪和运行统计。
Chat Completions 音频
Section titled “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 中。值为 null 的音频片段会被忽略。格式错误或无法克隆的音频增量,以及结束时没有音频数据的流,都会引发 ModelBehaviorError。toTextStream() 仅输出助手文本。如果应用需要低延迟的双向音频,请改用语音智能体概述中介绍的 Realtime API。
Responses WebSocket 传输
Section titled “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 传输的完整流式传输 + HITL 代码示例,请参阅 examples/basic/stream-ws.ts。
仅限 Responses 的延迟工具加载
Section titled “仅限 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 工具搜索指南。
托管多智能体(实验性)
Section titled “托管多智能体(实验性)”请将提供方包和 OpenAI 客户端安装为直接依赖,因为代码示例会直接导入这两个包:
npm install @openai/agents-openai openai托管多智能体允许 GPT-5.6 模型通过 Responses API 创建和协调树状的子智能体结构。这与 SDK 交接和 agents-as-tools 不同:应用不会为托管子智能体创建本地 Agent 对象,也不会调度其工作。托管根智能体负责委派工作,服务负责协调子智能体,/root 则综合生成最终答案。有关 Beta 版 API 的行为和支持的模型,请参阅官方多智能体指南。
实验性模型配置
Section titled “实验性模型配置”显式构建 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 可保留服务默认值,目前为 3。如果提供该值,则必须为正整数。
工具执行与归属
Section titled “工具执行与归属”每个托管智能体都使用请求中的模型,并且可以看到相同的本地工具定义。当任何托管智能体发出普通的 function_call 时,现有的 Agents SDK 运行器会执行应用工具。Responses API 的调用 ID 是路由标识:SDK 会将匹配的 function_call_output 注入正在进行的托管响应,交给发起请求的调用方。
getHostedAgentMetadata(details) 从工具回调的第三个参数中读取托管智能体名称。该元数据可用于日志记录和应用授权,但不控制路由。不要按智能体名称分发函数结果;请保留并使用调用 ID。
工具参数通过 WebSocket 从服务传入,工具输出则注入回正在进行的托管响应。请在应用中保留敏感数据策略、工具授权和审批检查。如果工具具有副作用,请基于调用 ID 确保其幂等性,以免中断后继续执行时重复产生副作用。
输出与流式传输行为
Section titled “输出与流式传输行为”只有阶段为 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 配合使用。
模型行为与提示词
Section titled “模型行为与提示词”ModelSettings
Section titled “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 globallynew 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 推理与提示词缓存控制
Section titled “GPT-5.6 推理与提示词缓存控制”GPT-5.6 新增了请求级推理模式和显式提示词缓存断点。reasoning.mode 和 reasoning.context 是仅限 Responses 的设置。OpenAIChatCompletionsModel 会发出一次警告并忽略它们;启用严格功能验证时,则会在请求之前抛出 UserError。reasoning.effort 在受支持的 Chat Completions 模型上仍然可用。
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,该批准才会被保留。
运行器与智能体的合并行为
Section titled “运行器与智能体的合并行为”运行器级别和智能体级别的 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 notbe available in your project.
To use it, please:1. Go to https://platform.openai.com/chat/edit2. 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。有关计算机操作的相关详情,请参阅工具。
高级提供方与可观测性
Section titled “高级提供方与可观测性”自定义模型提供方
Section titled “自定义模型提供方”实现自己的提供方很简单:实现 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 集成
Section titled “AI SDK 集成”如果希望使用非 OpenAI 模型而不自行实现 ModelProvider,请参阅 AI SDK 集成。该适配器允许你将 AI SDK 模型直接接入智能体运行时,适合应用已经统一使用 AI SDK 提供方,或希望接入更广泛的提供方生态系统的情况。该文档还介绍了 Agents SDK 的 providerData 如何映射到 AI SDK 的 providerMetadata,以及可用于 AI SDK UI 路由的流式传输辅助函数。
在受支持的服务器运行时中,追踪默认已启用。只有在追踪导出需要使用不同于默认 OpenAI API 密钥的凭证时,才使用 setTracingExportApiKey():
import { setTracingExportApiKey } from '@openai/agents';
setTracingExportApiKey('sk-...');这会使用该凭证将追踪发送到 OpenAI 控制台。有关导出器自定义设置,例如自定义接收端点或重试调优,请参阅追踪指南。