模型
每个智能体最终都会调用一个 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。
export OPENAI_DEFAULT_MODEL=gpt-5node my-awesome-agent.js其次,您可以为某个 Runner 实例设置默认模型。如果您没有为某个智能体设置模型,将使用该 Runner 的默认模型。
import { Runner } from '@openai/agents';
const runner = new Runner({ model: 'gpt‑4.1-mini' });GPT-5 模型
Section titled “GPT-5 模型”当您以这种方式使用任意 GPT-5 推理模型(gpt-5、gpt-5-mini 或 gpt-5-nano)时,SDK 会默认应用合理的 modelSettings。具体来说,会将 reasoning.effort 和 verbosity 都设置为 "low"。若要调整默认模型的推理强度,请传入自定义的 modelSettings:
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 模型
Section titled “非 GPT-5 模型”如果您传入的是非 GPT-5 的模型名称且未设置自定义 modelSettings,SDK 将回退到与任意模型兼容的通用 modelSettings。
OpenAI 提供程序
Section titled “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 客户端。
ModelSettings
Section titled “ModelSettings”ModelSettings 与 OpenAI 的参数相对应,但与具体提供方无关。
| 字段 | 类型 | 说明 |
|---|---|---|
temperature | number | 创造性与确定性的权衡。 |
topP | number | 核采样(Nucleus sampling)。 |
frequencyPenalty | number | 惩罚重复的 tokens。 |
presencePenalty | number | 鼓励新 tokens。 |
toolChoice | 'auto' | 'required' | 'none' | string | 参见强制使用工具。 |
parallelToolCalls | boolean | 在支持的情况下允许并行函数调用。 |
truncation | 'auto' | 'disabled' | Token 截断策略。 |
maxTokens | number | 响应中的最大 tokens 数。 |
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 globallynew 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,都会覆盖您在存储的提示中可能配置的值。
自定义模型提供程序
Section titled “自定义模型提供程序”实现您自己的提供程序很简单——实现 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 dashboard,您可以在其中检查完整的工作流执行图。