模型

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

• Model – 知道如何向特定 API 发起一次请求。
• ModelProvider – 将易读的模型名称（如 'gpt‑4o'）解析为 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
node my-awesome-agent.js

其次，您可以为某个 Runner 实例设置默认模型。如果未为某个智能体设置模型，将使用该 Runner 的默认模型。

为 Runner 设置默认模型

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

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

GPT-5 模型

当您以这种方式使用任意 GPT-5 推理模型（gpt-5、gpt-5-mini 或 gpt-5-nano）时，SDK 会默认应用合理的 modelSettings。具体来说，会将 reasoning.effort 和 verbosity 都设置为 "low"。要为默认模型调整推理强度，请传入您自己的 modelSettings：

自定义 GPT-5 默认设置

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

const myAgent = new Agent({
  name: 'My Agent',
  instructions: "You're a helpful agent.",
  modelSettings: {
    reasoning: { effort: 'minimal' },
    text: { verbosity: 'low' },
  },
  // If OPENAI_DEFAULT_MODEL=gpt-5 is set, passing only modelSettings works.
  // It's also fine to pass a GPT-5 model name explicitly:
  // model: 'gpt-5',
});

为降低延迟，使用 gpt-5-mini 或 gpt-5-nano 且设置 reasoning.effort="minimal"，通常会比默认设置更快返回响应。但需要注意，Responses API 中的一些内置工具（如文件搜索与图像生成）不支持 "minimal" 推理强度，这也是本 Agents SDK 默认使用 "low" 的原因。

非 GPT-5 模型

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

---

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 客户端。

---

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 工作流。
reasoning.effort	'minimal' | 'low' | 'medium' | 'high'	gpt-5 等模型的推理强度。
text.verbosity	'low' | 'medium' | 'high'	gpt-5 等模型的文本详尽度。

可在任一层级附加设置：

模型设置

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 { Agent, run } from '@openai/agents';

async function main() {
  const agent = new Agent({
    name: 'Assistant',
    prompt: {
      promptId: 'pmpt_68d50b26524c81958c1425070180b5e10ab840669e470fc7',
      variables: { name: 'Kaz' },
    },
  });

  const result = await run(agent, 'What is your name?');
  console.log(result.finalOutput);
}

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 提供方时，您可以通过提供 API 密钥选择加入自动追踪导出：

追踪导出器

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

setTracingExportApiKey('sk-...');

这会将追踪发送到 OpenAI 仪表盘，您可以在其中检查工作流的完整执行图。

---

下一步

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