モデル

すべてのエージェントは最終的に 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 環境変数を設定してください。

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-5 の reasoning モデル（gpt-5、gpt-5-mini、gpt-5-nano）を使用すると、SDK は既定で妥当な modelSettings を適用します。具体的には、reasoning.effort と verbosity の両方を "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-mini または gpt-5-nano に reasoning.effort="minimal" を指定すると、既定設定よりも高速に応答が返ることが多いです。ただし、Responses API の一部の組み込みツール（ファイル検索や画像生成など）は "minimal" の推論負荷をサポートしていないため、この Agents SDK では既定を "low" にしています。

非 GPT-5 モデル

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

---

OpenAI プロバイダー

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

API	用途	setOpenAIAPI() の呼び出し
Chat Completions	標準的なチャットと Function Calling	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

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

フィールド	型	注記
temperature	number	クリエイティビティ vs. 決定性
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 globally
new 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);
});

ツールや instructions などの追加のエージェント設定は、保存済みプロンプトで設定した値を上書きします。

---

カスタムモデルプロバイダー

独自のプロバイダーの実装は簡単です。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 に送信し、ワークフローの完全な実行グラフを確認できます。

---

次のステップ

• エージェントの実行 を探索する
• ツール でモデルに強力な機能を付与する
• 必要に応じて ガードレール や トレーシング を追加する