模型

每个智能体最终都会调用 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.4-mini，并设置 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.4-mini 配置开始，或在其他 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 客户端。

提供商选项参考

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

选项	用途
apiKey	提供商创建自己的 OpenAI 客户端时使用的 API 密钥。默认为 SDK 全局 OpenAI 密钥。
baseURL	OpenAI 兼容端点的 HTTP 基础 URL。不能与 openAIClient 结合使用。
websocketBaseURL	Responses WebSocket 传输的 WebSocket 基础 URL。不能与 openAIClient 结合使用。
openAIClient	预配置的 OpenAI 客户端实例。不能与 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，改为拒绝此转换。

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 启用的同时禁用心跳超时。保活要求 WebSocket 实现公开 ping 和 pong 支持。

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

有关使用 Responses WebSocket 传输的完整流式传输与 HITL 示例，请参阅 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 官方工具搜索指南。

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

实验性测试版

托管式多智能体使用测试版 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 负责综合生成最终答案。有关测试版 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 项目，同时过滤仅限测试版的协作记录；高层文本流式传输则仅包含根智能体的最终答案。这样既能使 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	惩罚重复词元。
presencePenalty	number	鼓励生成新词元。
toolChoice	'auto' | 'required' | 'none' | string	请参阅强制使用工具。在 OpenAI Responses 中，toolChoice: 'computer' 会在可用时强制使用正式版内置计算机工具。
parallelToolCalls	boolean	在支持的情况下允许并行函数调用。
truncation	'auto' | 'disabled'	词元截断策略。
maxTokens	number	响应中的最大词元数。
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>	转发给底层模型的提供商特定直通选项。
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 显式清除继承的值。

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。

配置 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。

策略可以返回：

• true / false，表示简单的重试决定。
• { retry, delayMs?, reason? }，用于覆盖延迟或附加供日志记录使用的诊断原因。

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() 实现。

运行器与智能体的合并行为

运行器层级与智能体层级 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 模型接入智能体运行时；如果应用已统一使用 AI SDK 提供商，或需要访问更广泛的提供商生态系统，这会非常有用。它还介绍了 Agents SDK providerData 如何映射到 AI SDK providerMetadata，以及 AI SDK UI 路由可用的流式辅助函数。

---

追踪凭据

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

设置追踪导出 API 密钥

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

setTracingExportApiKey('sk-...');

这会使用该凭据将追踪数据发送到 OpenAI 控制面板。有关自定义接收端点或重试调优等导出器自定义选项，请参阅追踪指南。

---

后续步骤

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