模型

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

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

身份验证

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`	转发给基于 WebSocket 的 Responses 模型包装器的高级选项。
`strictFeatureValidation`	对于 Chat Completions 模型，如果使用 `previousResponseId`、`conversationId` 和 `prompt` 等仅限 Responses 的功能，则抛出 `UserError`。默认情况下，会发出警告并忽略这些功能。

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。

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

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

请将提供商软件包和 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 压缩端点的显式调用不属于此模型的生命周期。您仍可通过稳定版 OpenAIResponsesModel 使用 SDK 交接和 agents-as-tools。

模型行为与提示

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 数。
`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。受支持的 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。

策略可以返回以下任一内容：

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);
});

工具或 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 控制面板。有关自定义接收端点或重试调优等导出器自定义设置，请参阅追踪。

后续步骤

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