Skip to content

Models

Every Agent ultimately calls an LLM. The SDK abstracts models behind two lightweight interfaces:

  • Model – knows how to make one request against a specific API.
  • ModelProvider – resolves human‑readable model names (e.g. 'gpt‑4o') to Model instances.

In day‑to‑day work you normally only interact with model names and occasionally ModelSettings.

Specifying a model per‑agent
import { Agent } from '@openai/agents';
const agent = new Agent({
name: 'Creative writer',
model: 'gpt-4.1',
});

The default ModelProvider resolves names using the OpenAI APIs. It supports two distinct endpoints:

APIUsageCall setOpenAIAPI()
Chat CompletionsStandard chat & function callssetOpenAIAPI('chat_completions')
ResponsesNew streaming‑first generative API (tool calls, flexible outputs)setOpenAIAPI('responses') (default)
Set default OpenAI key
import { setDefaultOpenAIKey } from '@openai/agents';
setDefaultOpenAIKey(process.env.OPENAI_API_KEY!); // sk-...

You can also plug your own OpenAI client via setDefaultOpenAIClient(client) if you need custom networking settings.

The OpenAI provider defaults to gpt‑4o. Override per agent or globally:

Set a default model
import { Runner } from '@openai/agents';
const runner = new Runner({ model: 'gpt‑4.1-mini' });

ModelSettings mirrors the OpenAI parameters but is provider‑agnostic.

FieldTypeNotes
temperaturenumberCreativity vs. determinism.
topPnumberNucleus sampling.
frequencyPenaltynumberPenalise repeated tokens.
presencePenaltynumberEncourage new tokens.
toolChoice'auto' | 'required' | 'none' | stringSee forcing tool use.
parallelToolCallsbooleanAllow parallel function calls where supported.
truncation'auto' | 'disabled'Token truncation strategy.
maxTokensnumberMaximum tokens in the response.
storebooleanPersist the response for retrieval / RAG workflows.

Attach settings at either level:

Model settings
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‑level settings override any conflicting per‑agent settings.


Implementing your own provider is straightforward – implement ModelProvider and Model and pass the provider to the Runner constructor:

Minimal custom provider
import {
ModelProvider,
Model,
ModelRequest,
AgentOutputType,
ModelResponse,
ResponseStreamEvent,
TextOutput,
} 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);

When using the OpenAI provider you can opt‑in to automatic trace export by providing your API key:

Tracing exporter
import { setTracingExportApiKey } from '@openai/agents';
setTracingExportApiKey('sk-...');

This sends traces to the OpenAI dashboard where you can inspect the complete execution graph of your workflow.