コンテンツにスキップ

モデル

すべての エージェント は最終的に LLM を呼び出します。SDK は 2 つの軽量なインターフェースの背後にモデルを抽象化します:

  • Model – 特定の API に対して 1 回 のリクエストを行う方法を知っています
  • 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 など他のモデルに切り替えたい場合、エージェントを設定する方法は 2 つあります。

まず、カスタムモデルを設定していないすべてのエージェントで一貫して特定のモデルを使用したい場合は、エージェントを実行する前に環境変数 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 の reasoning モデル(gpt-5gpt-5-minigpt-5-nano)を使用すると、SDK は既定で妥当な modelSettings を適用します。具体的には、reasoning.effortverbosity の両方を "low" に設定します。既定モデルの reasoning effort を調整するには、独自の 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-nanoreasoning.effort="minimal" を組み合わせると、既定設定より高速に応答が返ることが多いです。ただし、Responses API の一部の組み込みツール(ファイル検索や画像生成など)は "minimal" の reasoning effort をサポートしていないため、本 Agents SDK の既定は "low" になっています。

カスタムの modelSettings なしで GPT-5 以外のモデル名を渡すと、SDK はあらゆるモデルと互換性のある汎用的な modelSettings にフォールバックします。


既定の ModelProvider は OpenAI API を使用して名称を解決します。2 つの異なるエンドポイントをサポートします:

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 クライアントを差し込むこともできます。


ModelSettings は OpenAI のパラメーターを反映しますが、プロバイダーに依存しません。

フィールド注記
temperaturenumber創造性と決定性のバランス
topPnumberNucleus sampling
frequencyPenaltynumber繰り返しトークンへのペナルティ
presencePenaltynumber新しいトークンの促進
toolChoice'auto' | 'required' | 'none' | stringforcing tool use を参照
parallelToolCallsbooleanサポートされる場合に並列の関数呼び出しを許可
truncation'auto' | 'disabled'トークン切り詰め戦略
maxTokensnumber応答内の最大トークン数
storeboolean応答を永続化して取得/RAG ワークフローで使用
reasoning.effort'minimal' | 'low' | 'medium' | 'high'gpt-5 などの reasoning effort
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_68d50b26524c81958c1425070180b5e10ab840669e470fc7',
version: '1',
variables: { name: 'Kaz' },
},
});
const result = await run(agent, 'What is your name?');
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 ダッシュボード に送信され、ワークフローの完全な実行グラフを確認できます。