跳转到内容

模型

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

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

日常使用中,你通常只与模型名称交互,偶尔会用到 ModelSettings

为每个智能体指定模型
import { Agent } from '@openai/agents';
const agent = new Agent({
name: 'Creative writer',
model: 'gpt-4.1',
});

当初始化 Agent 时未指定模型,将使用默认模型。目前默认是 gpt-4.1,在面向智能体的工作流中兼具良好的可预测性与低延迟。

如果你想切换到其他模型(如 gpt-5),有两种方式配置你的智能体。

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

Terminal window
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-5gpt-5-minigpt-5-nano)时,SDK 会默认应用合理的 modelSettings:将 reasoning.effortverbosity 均设置为 "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-minigpt-5-nanoreasoning.effort="minimal" 搭配,通常会比默认设置更快返回响应。但需注意,Responses API 中的一些内置工具(如文件搜索与图像生成)不支持 "minimal" 推理强度,这也是本 Agents SDK 默认采用 "low" 的原因。

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


默认的 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 与 OpenAI 的参数对应,但与提供方无关。

字段类型说明
temperaturenumber创造性与确定性的平衡。
topPnumber核采样。
frequencyPenaltynumber惩罚重复的 token。
presencePenaltynumber鼓励引入新 token。
toolChoice'auto' | 'required' | 'none' | string参见强制使用工具
parallelToolCallsboolean在支持的情况下允许并行函数调用。
truncation'auto' | 'disabled'Token 截断策略。
maxTokensnumber响应中的最大 token 数。
storeboolean持久化响应,以供检索/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 时支持。

字段类型说明
promptIdstring提示词的唯一标识符。
versionstring你希望使用的提示词版本。
variablesobject要替换到提示词中的键/值变量。值可以是字符串或内容输入类型(如文本、图像或文件)。
带有提示词的智能体
import { Agent, run } from '@openai/agents';
async function main() {
const agent = new Agent({
name: 'Assistant',
prompt: {
promptId: 'pmpt_684b3b772e648193b92404d7d0101d8a07f7a7903e519946',
version: '1',
variables: {
poem_style: 'limerick',
},
},
});
const result = await run(agent, 'Write about unrequited love.');
console.log(result.finalOutput);
}
if (require.main === module) {
main().catch(console.error);
}

任何额外的智能体配置(如 tools 或 instructions)都会覆盖你在存储提示词中配置的相应值。


实现自定义提供方很简单——实现 ModelProviderModel,并将该提供方传给 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 控制台,你可以在其中检查工作流的完整执行图。