模型

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

• Model – 知道如何针对特定 API 发起一次请求。
• ModelProvider – 将人类可读的模型名称（如 'gpt‑5.2'）解析为 Model 实例。

在日常工作中，你通常只会与模型名称交互，偶尔会接触到 ModelSettings。

为每个智能体指定模型

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

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

模型选择

默认模型

当你在初始化 Agent 时未指定模型，将使用默认模型。当前默认是为兼容性和低延迟考虑的 gpt-4.1。如果你有权限，建议将智能体设置为 gpt-5.2，以获得更高质量，同时保留显式的 modelSettings。

如果你想切换到其他模型（如 gpt-5.2），有两种方式配置你的智能体。

首先，如果你希望对未设置自定义模型的所有智能体一致使用某个特定模型，请在运行智能体前设置 OPENAI_DEFAULT_MODEL 环境变量。

export OPENAI_DEFAULT_MODEL=gpt-5.2
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.2）时，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.2 is set, passing only modelSettings works.
  // It's also fine to pass a GPT-5.x model name explicitly:
  model: 'gpt-5.2',
  modelSettings: {
    reasoning: { effort: 'high' },
    text: { verbosity: 'low' },
  },
});

为了更低的延迟，建议在 gpt-5.2 上使用 reasoning.effort: "none"。gpt-4.1 系列（包括 mini 和 nano 变体）仍然是构建交互式智能体应用的可靠选择。

非 GPT-5 模型

如果你传入非 GPT-5 的模型名称且未提供自定义 modelSettings，SDK 会回退到与任意模型兼容的通用 modelSettings。

---

OpenAI 提供方配置

OpenAI 提供方

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

API	用途	调用 setOpenAIAPI()
Chat Completions	标准对话与函数调用	setOpenAIAPI('chat_completions')
Responses	新的以流式优先的生成式 API（工具调用、灵活输出）	setOpenAIAPI('responses') (default)

身份验证

设置默认 OpenAI 密钥

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

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

你也可以通过 setDefaultOpenAIClient(client) 插入你自己的 OpenAI 客户端，以满足自定义网络设置的需求。

Responses WebSocket 传输

当你在 Responses API 下使用 OpenAI 提供方时，可以通过 WebSocket 传输发送请求，而不是默认的 HTTP 传输。

使用 setOpenAIResponsesTransport('websocket') 全局启用，或在提供方级别通过 new OpenAIProvider({ useResponses: true, useResponsesWebSocket: true }) 启用。

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

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

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

尽管名字如此，withResponsesWebSocketSession(...) 是一个传输层生命周期助手，与会话指南中描述的内存 Session 接口无关。

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

如果你自行实例化 OpenAIProvider，请注意基于 websocket 的 Responses 模型封装默认会被缓存以复用连接。请在关闭时调用 await provider.close() 以释放这些缓存连接。withResponsesWebSocketSession(...) 在很大程度上就是为你管理该生命周期：它会创建启用 websocket 的 provider 和 runner，将它们传给你的回调，并在之后始终关闭 provider。使用 providerOptions 配置临时 provider，使用 runnerConfig 配置回调作用域内的 runner 默认值。

参见 examples/basic/stream-ws.ts，了解使用 Responses WebSocket 传输的完整流式传输 + HITL 示例。

---

模型行为与提示

ModelSettings

ModelSettings 镜像 OpenAI 的参数，但与提供方无关。

字段	类型	说明
temperature	number	创造性与确定性之间的权衡。
topP	number	核采样。
frequencyPenalty	number	惩罚重复的 token。
presencePenalty	number	鼓励引入新 token。
toolChoice	'auto' | 'required' | 'none' | string	参见强制使用工具。
parallelToolCalls	boolean	在支持的情况下允许并行函数调用。
truncation	'auto' | 'disabled'	Token 截断策略。
maxTokens	number	响应中的最大 token 数。
store	boolean	持久化响应以便检索 / RAG 工作流。
promptCacheRetention	'in-memory' | '24h' | null	在支持时控制提供方提示缓存的保留策略。
reasoning.effort	'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'	gpt-5.x 模型的推理强度。
reasoning.summary	'auto' | 'concise' | 'detailed'	控制模型返回的推理摘要量。
text.verbosity	'low' | 'medium' | 'high'	gpt-5.x 等模型的文本详尽度。
providerData	Record<string, any>	提供方特定的直通选项，将被转发到底层模型。

可在任一层级附加设置：

模型设置

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 级别的设置会覆盖任何与之冲突的逐智能体设置。

---

提示

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

字段	类型	说明
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）都会覆盖你在存储提示中配置的值。

---

高级提供方与可观测性

自定义模型提供方

实现你自己的提供方很简单——实现 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);

如果你需要为非 OpenAI 模型提供现成的适配器，请参见使用 AI SDK 指定任意模型。

---

追踪凭据

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

设置追踪导出 API 密钥

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

setTracingExportApiKey('sk-...');

这会使用该凭据将追踪发送到 OpenAI dashboard。关于导出器自定义（如自定义采集端点或重试调优），请参见 追踪指南。

---

后续步骤

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