モデル
最終的にすべてのエージェントは 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',});既定のモデル
Section titled “既定のモデル”Agent を初期化するときにモデルを指定しない場合、既定のモデルが使用されます。現在の既定は gpt-4.1 で、エージェントワークフローにおける予測可能性と低レイテンシのバランスに優れています。
gpt-5 など他のモデルに切り替えたい場合、エージェントを構成する方法は 2 つあります。
まず、カスタムモデルを設定していないすべてのエージェントで特定のモデルを一貫して使用したい場合は、エージェントを実行する前に 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 モデル”カスタム modelSettings なしで GPT-5 以外のモデル名を渡した場合、SDK はあらゆるモデルと互換性のある汎用的な modelSettings にフォールバックします。
OpenAI プロバイダー
Section titled “OpenAI プロバイダー”既定の ModelProvider は OpenAI API を使って名前を解決します。次の 2 つの明確に異なるエンドポイントをサポートします。
| 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 サンプリング |
frequencyPenalty | number | 繰り返し出現するトークンにペナルティを課す |
presencePenalty | number | 新しいトークンの出現を促す |
toolChoice | 'auto' | 'required' | 'none' | string | ツール使用の強制 を参照 |
parallelToolCalls | boolean | 対応している場合に関数呼び出しの並列実行を許可 |
truncation | 'auto' | 'disabled' | トークン切り詰め戦略 |
maxTokens | number | 応答内の最大トークン数 |
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);トレーシングエクスポーター
Section titled “トレーシングエクスポーター”OpenAI プロバイダー使用時、API キーを指定することで自動トレースエクスポートをオプトインできます。
import { setTracingExportApiKey } from '@openai/agents';
setTracingExportApiKey('sk-...');これによりトレースが OpenAI ダッシュボード に送信され、ワークフローの完全な実行グラフを確認できます。